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
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
.\"
.\" 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_PIDS 3 "серпень 2022 року" libproc2
.\" Please adjust this date whenever revising the manpage.
.\"
.nh
.SH НАЗВА
procps_pids — програмний інтерфейс для доступу до даних процесів у файловій
системі /proc
.SH "КОРОТКИЙ ОПИС"
.nf
#include <libproc2/pids.h>
int\fB procps_pids_new \fP (struct pids_info **\fIinfo\fP, enum pids_item *\fIitems\fP, int \fInumitems\fP);
int\fB procps_pids_ref \fP (struct pids_info *\fIinfo\fP);
int\fB procps_pids_unref\fP (struct pids_info **\fIinfo\fP);
struct pids_stack *\fBprocps_pids_get\fP (
struct pids_info *\fIinfo\fP,
enum pids_fetch_type \fIwhich\fP);
struct pids_fetch *\fBprocps_pids_reap\fP (
struct pids_info *\fIinfo\fP,
enum pids_fetch_type \fIwhich\fP);
struct pids_fetch *\fBprocps_pids_select\fP (
struct pids_info *\fIinfo\fP,
unsigned *\fIthese\fP,
int \fInumthese\fP,
enum pids_select_type \fIwhich\fP);
struct pids_stack **\fBprocps_pids_sort\fP (
struct pids_info *\fIinfo\fP,
struct pids_stack *\fIstacks\fP[],
int \fInumstacked\fP,
enum pids_item \fIsortitem\fP,
enum pids_sort_order \fIorder\fP);
int \fBprocps_pids_reset\fP (
struct pids_info *\fIinfo\fP,
enum pids_item *\fInewitems\fP,
int \fInewnumitems\fP);
struct pids_stack *\fBfatal_proc_unmounted\fP (
struct pids_info *\fIinfo\fP,
int \fIreturn_self\fP);
.fi
Компонувати з \fI\-lproc2\fP.
.SH ОПИС
.SS Огляд
Центральною для цього інтерфейсу є проста структура «result», яка визначає
«item» і його значення (в об'єднання зі стандартними типами мови C, як
учасниками). Усі структури «result» буде автоматично розподілено і надано
бібліотекою.
Заданням масиву значень «item» ці структури можна упорядкувати як «стек» із
потенційним отримання багатьох результатів одним викликом функції. Таким
чином, «стек» можна розглядати як запис змінної довжини, вміст якого та
порядок записів у якому визначаються лише користувачем.
Частиною цього інтерфейсу є два унікальних лічильники. Для зберігання їхніх
значень передбачено записи «noop» та «extra». Їхні значення ніколи не
встановлюються бібліотекою, але результат «extra» буде занулено на початку
кожної взаємодії із бібліотекою.
Базовим документом при розробці користувацької програми буде файл заголовків
pids.h. Там ви знайдете усі доступні записи (item), тип, який вони
повертають (назву члена структури «result») і джерело для таких
значень. Також там наведено документацію щодо додаткових лічильників та
структур.
.SS Користування
Нижче наведено типову послідовність викликів цього інтерфейсу.
.nf
1. \fBfatal_proc_unmounted()\fP
2. \fBprocps_pids_new()\fP
3. \fBprocps_pids_get()\fP, \fBprocps_pids_reap()\fP або \fBprocps_pids_select()\fP
4. \fBprocps_pids_unref()\fP
.fi
Функція \fBget\fP є ітератором для послідовних PID/TID, що повертає ці «items»,
раніше вказані за допомогою \fBnew\fP або \fBreset\fP.
Для непередбачуваних результатів для змінних передбачено дві
функції. Функція \fBreap\fP збирає дані для усіх процесів, а функція \fBselect\fP
працює зі специфічними PID та UID. Обидві можуть повертати декілька
«стеків», кожне з яких містить декілька структур «result». Крім того,
користувач може наказати \fBупорядкувати\fP (\fBsort\fP) ці результати.
Щоб скористатися будь\-яким «stack» і отримати доступ до окремих структур
«result», потрібен \fIrelative_enum\fP, як це показано у макросі \fBVAL\fP, який
визначено у файлі заголовка. ТАкі значення можна запрограмувати як: значення
від 0 до numitems\-1. Втім, цю потребу типово можна задовольнити створенням
ваших власних лічильників, які відповідають порядку у масиві «items».
.SS Застереження
Програмний інтерфейс <pids> відрізняється від інших тим, що потрібні
записи має бути надано під час виконання \fBnew\fP або \fBreset\fP, останній
варіант є унікальним для цього програмного інтерфейсу. Якщо якийсь із
параметрів, \fIitems\fP або \fInumitems\fP, є нульовим на час \fBnew\fP, обов'язковим
перед надсиланням будь\-якого іншого виклику стає \fBreset\fP.
Для функцій \fBnew\fP і \fBunref\fP має бути надано адресу вказівник структури
\fIinfo\fP. Із \fBnew\fP її має бути ініціалізовано значенням NULL. Із \fBunref\fP її
буде скинуто до NULL, якщо контрольний відлік дійде до нуля.
Функції \fBget\fP і \fBreap\fP використовують параметр \fIwhich\fP для визначення
того, слід отримувати дані лише для завдань чи для завдань і потоків
обробки.
Функція \fBselect\fP потребує масиву PID або UID, як \fIthese\fP разом із
\fInumthese\fP, для визначення того, дані яких процесів слід отримати. Далі, ця
функція працює із підмножиною \fBreap\fP.
Якщо використано функцію \fBsort\fP, зазвичай, буде повернуто параметри
\fIstacks\fP і \fInumstacked\fP у структурі «pids_fetch».
Нарешті, можна викликати функцію \fBfatal_proc_unmounted\fP до будь\-якої іншої
функції для забезпечення монтування каталогу /proc/. Якщо каталог
змонтовано, параметр \fIinfo\fP матиме значення NULL, а параметр \fIreturn_self\fP
матиме нульове значення. Якщо, втім, деякі записи потрібні для запуску
програми (\fIreturn_self\fP відмінне від нуля), виклик \fBnew\fP має передувати
виклику цієї функції для того, щоб вказати \fIitems\fP і отримати потрібний
вказівник \fIinfo\fP.
.SH "ПОВЕРНУТЕ ЗНАЧЕННЯ"
.SS "Функції, які повертають «int»"
На помилку вказуватиме від'ємне число, яке є завжди оберненим до якогось
відомого значення з errno.h.
На успіх вказує нульовий стан повернення. Втім, функції \fBref\fP і \fBunref\fP
повертають поточний контрольний відлік структури \fIinfo\fP.
.SS "Функції, які повертають «address»"
На помилку вказуватиме повернутий NUL\-вказівник із повідомлення про причину
у формальному значенні errno.
На успіх вказує повернення вказівника на іменовану структуру. Втім, якщо
щось переживе виклик \fBfatal_proc_unmounted\fP, NULL завжди буде повернуто,
якщо значенням \fIreturn_self\fP є нуль.
.SH ДІАГНОСТИКА
Щоб полегшити розробку програм, передбачено дві можливості procps\-ng, якими
можна скористатися.
Першою є файл із назвою «libproc.supp», яким можна скористатися при розробці
\fIбагатопотокової\fP програми. Якщо скористатися ним у поєднанні із параметром
valgrind «\-\-suppressions=», можна уникнути виведення попереджень, які
пов'язано із самою бібліотекою procps.
Такі попередження виникають через те, що бібліотека обробляє засновані на
«купі» функції отримання пам'яті у безпечний щодо потоків обробки
спосіб. \fIОднопотокові\fP програми не призводитимуть до появи таких
попереджень.
Друга функція може допомогти забезпечити узгодженість посилань на члени
«result» із очікуваннями бібліотеки. У цій функції передбачено, що наданий
макрос у файлі заголовків буде використано для доступу до значення «result».
Цю можливість можна активувати за допомогою будь\-якого з вказаних нижче
методів, а усі розбіжності буде записано до \fBstderr\fP.
.IP 1) 3
Додайте CFLAGS='\-DXTRA_PROCPS_DEBUG' до будь\-яких інших застосованих у
вашому проєкті параметрів ./configure.
.IP 2) 3
Додайте #include <procps/xtra\-procps\-debug.h> у програму \fIпісля\fP
#include <procps/pids.h>.
.PP
Використання цієї можливості перевірки призводить до суттєвих обчислювальних
витрат. Через це, важливо \fIне\fP вмикати її під час остаточного збирання або
збирання програми для випуску.
.SH "ЗМІННІ СЕРЕДОВИЩА"
Встановлене значення є несуттєвим, достатнього самого факту його
встановлення.
.IP LIBPROC_HIDE_KERNEL
Призведе до приховування потоків обробки ядра, які інакше було б повернуто
викликом \fBprocps_pids_get\fP, \fBprocps_pids_select\fP або \fBprocps_pids_reap\fP.
.SH "ТАКОЖ ПЕРЕГЛЯНЬТЕ"
\fBprocps\fP(3), \fBprocps_misc\fP(3), \fBproc\fP(5).
|
