1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
.\"
.\" Copyright (c) 2020-2023 Jim Warner <james.warner@comcast.net>
.\" Copyright (c) 2020-2023 Craig Small <csmall@dropbear.xyz>
.\"
.\" This manual is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public
.\" License as published by the Free Software Foundation; either
.\" version 2.1 of the License, or (at your option) any later version.
.\"
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH PROCPS 3 "серпень 2022 року" libproc2
.\" Please adjust this date whenever revising the manpage.
.\"
.nh
.SH НАЗВА
procps — програмний інтерфейс для доступу до даних системного рівня у
файловій системі /proc
.SH "КОРОТКИЙ ОПИС"
У цьому короткому описі представлено п'ять різних інтерфейсів, які названо
за файлами, до яких вони надають доступ у фіктивній файловій системі /proc:
\fBdiskstats\fP, \fBmeminfo\fP, \fBslabinfo\fP, \fBstat\fP та \fBvmstat\fP.
.nf
.RS +4
#include <libproc2/\fBіменований_інтерфейс\fP.h>
int\fB procps_new \fP (struct info **\fIinfo\fP);
int\fB procps_ref \fP (struct info *\fIinfo\fP);
int\fB procps_unref\fP (struct info **\fIinfo\fP);
struct result *\fBprocps_get\fP (
struct info *\fIinfo\fP,
[ const char *\fIname\fP, ] лише програмний інтерфейс \fBdiskstats\fP
enum item \fIitem\fP);
struct stack *\fBprocps_select\fP (
struct info *\fIinfo\fP,
[ const char *\fIname\fP, ] лише програмний інтерфейс \fBdiskstats\fP
enum item *\fIitems\fP,
int \fInumitems\fP);
struct reaped *\fBprocps_reap\fP (
struct info *\fIinfo\fP,
[ enum reap_type \fIwhat\fP, ] лише програмний інтерфейс \fBstat\fP
enum item *\fIitems\fP,
int \fInumitems\fP);
struct stack **\fBprocps_sort\fP (
struct info *\fIinfo\fP,
struct stack *\fIstacks\fP[],
int \fInumstacked\fP,
enum item \fIsortitem\fP,
enum sort_order \fIorder\fP);
.fi
Наведені вище функції і структури є загальними, але частиною будь\-якого
ідентифікатора може також бути специфічний запис
\fBіменований_інтерфейс\fP. Наприклад, «procps_new» може бути насправді
«procps_\fBmeminfo\fP_new», а «info» може бути насправді «\fBdiskstats\fP_info»
тощо.
Той самий \fBіменований_інтерфейс\fP буде використано у кожній з назв файлів
заголовків, назви яких формуються додаванням суфікса «.h».
Компонувати з \fI\-lproc2\fP.
.SH ОПИС
.SS Огляд
Центральною для цих інтерфейсів є проста структура «result», яка визначає
«item» і його значення (в об'єднання зі стандартними типами мови C, як
учасниками). Усі структури «result» буде автоматично розподілено і надано
бібліотекою.
Заданням масиву значень «item» ці структури можна упорядкувати як «стек» із
потенційним отримання багатьох результатів одним викликом функції. Таким
чином, «стек» можна розглядати як запис змінної довжини, вміст якого та
порядок записів у якому визначаються лише користувачем.
Частиною кожного інтерфейсу є два унікальних лічильники. Для зберігання
їхніх значень передбачено записи «noop» та «extra». Їхні значення ніколи не
встановлюються бібліотекою, але результат «extra» буде занулено на початку
кожної взаємодії із бібліотекою.
Базовим документом при розробці користувацької програми буде файл заголовків
\fBіменованого інтерфейсу\fP. Там ви знайдете усі доступні записи (item), тип,
який вони повертають (назву члена структури «result») і джерело для таких
значень. Також там наведено документацію щодо додаткових лічильників та
структур.
.SS Користування
Нижче наведено типову послідовність викликів цих інтерфейсів.
.nf
1. \fBprocps_new()\fP
2. \fBprocps_get()\fP, \fBprocps_select()\fP або \fBprocps_reap()\fP
3. \fBprocps_unref()\fP
.fi
Функцію \fBget\fP призначено для отримання структури «result» для окремого
«item». Крім того, можна скористатися макросом \fBGET\fP, якщо потрібне лише
значення, яке повертає функція.
Функція \fBselect\fP може отримувати декілька структур «result» в одному
значенні «stack».
Для непередбачуваних результатів для змінних інтерфейси \fBdiskstats\fP,
\fBslabinfo\fP і \fBstat\fP експортують функцію \fBreap\fP. Її використовують для
отримання декількох «стеків», кожен з яких містить декілька структур
«result». Крім того, користувач може наказати \fBупорядкувати\fP (\fBsort\fP) ці
результати.
Щоб скористатися будь\-яким «stack» і отримати доступ до окремих структур
«result», потрібен \fIrelative_enum\fP, як це показано у макросі \fBVAL\fP, який
визначено у файлі заголовка. ТАкі значення можна запрограмувати як: значення
від 0 до numitems\-1. Втім, цю потребу типово можна задовольнити створенням
ваших власних лічильників, які відповідають порядку у масиві «items».
.SS Застереження
Функціями \fBnew\fP, \fBref\fP, \fBunref\fP, \fBget\fP та \fBselect\fP можна скористатися в
усіх п'яти інтерфейсах.
Для функцій \fBnew\fP і \fBunref\fP має бути надано адресу вказівник структури
\fIinfo\fP. Із \fBnew\fP її має бути ініціалізовано значенням NULL. Із \fBunref\fP її
буде скинуто до NULL, якщо контрольний відлік дійде до нуля.
У випадку інтерфейсу \fBdiskstats\fP параметр \fIname\fP у функціях \fBget\fP і
\fBselect\fP вказує на диск або назву розділу
Для інтерфейсу \fBstat\fP параметр \fIwhat\fP функції \fBreap\fP вказує на те, чи
слід збирати дані лише для процесорів або процесорів і вузлів NUMA.
Якщо використано функцію \fBsort\fP, зазвичай, буде повернуто параметри
\fIstacks\fP і \fInumstacked\fP у структурі «reaped».
.SH "ПОВЕРНУТЕ ЗНАЧЕННЯ"
.SS "Функції, які повертають «int»"
На помилку вказуватиме від'ємне число, яке є завжди оберненим до якогось
відомого значення з errno.h.
На успіх вказує нульовий стан повернення. Втім, функції \fBref\fP і \fBunref\fP
повертають поточний контрольний відлік структури \fIinfo\fP.
.SS "Функції, які повертають «address»"
На помилку вказуватиме повернутий NUL\-вказівник із повідомлення про причину
у формальному значенні errno.
На успіх вказує повернення вказівника на іменовану структуру.
.SH ДІАГНОСТИКА
Щоб допомогти у розробці програм, передбачено функцію, яка може допомогти
забезпечити узгодженість посилань на члени «result» із очікуваннями
бібліотеки. У цій функції передбачено, що наданий макрос у файлі заголовків
буде використано для доступу до значення «result».
Цю можливість можна активувати за допомогою будь\-якого з вказаних нижче
методів, а усі розбіжності буде записано до \fBstderr\fP.
.IP 1) 3
Додайте CFLAGS='\-DXTRA_PROCPS_DEBUG' до будь\-яких інших застосованих
параметрів ./configure.
.IP 2) 3
Додайте #include <procps/xtra\-procps\-debug.h> у програму \fIпісля\fP
команд включення іменованих інтерфейсів.
.PP
Використання цієї можливості перевірки призводить до суттєвих обчислювальних
витрат. Через це, важливо \fIне\fP вмикати її під час остаточного збирання або
збирання програми для випуску.
.SH "ТАКОЖ ПЕРЕГЛЯНЬТЕ"
\fBprocps_misc\fP(3), \fBprocps_pids\fP(3), \fBproc\fP(5).
|
