PROCPS\_PIDS(3) Library Functions Manual PROCPS\_PIDS(3) # НАЗВА procps\_pids — програмний інтерфейс для доступу до даних процесів у файловій системі /proc # КОРОТКИЙ ОПИС ``` #include ``` ``` int procps_pids_new (struct pids_info **info, enum pids_item *items, int numitems); int procps_pids_ref (struct pids_info *info); int procps_pids_unref (struct pids_info **info); ``` ``` struct pids_stack *procps_pids_get ( struct pids_info *info, enum pids_fetch_type which); ``` ``` struct pids_fetch *procps_pids_reap ( struct pids_info *info, enum pids_fetch_type which); ``` ``` struct pids_fetch *procps_pids_select ( struct pids_info *info, unsigned *these, int numthese, enum pids_select_type which); ``` ``` struct pids_stack **procps_pids_sort ( struct pids_info *info, struct pids_stack *stacks[], int numstacked, enum pids_item sortitem, enum pids_sort_order order); ``` ``` int procps_pids_reset ( struct pids_info *info, enum pids_item *newitems, int newnumitems); ``` ``` struct pids_stack *fatal_proc_unmounted ( struct pids_info *info, int return_self); ``` ``` ``` Компонувати з *-lproc2*. # ОПИС ## Огляд Центральною для цього інтерфейсу є проста структура «result», яка визначає «item» і його значення (в об'єднання зі стандартними типами мови C, як учасниками). Усі структури «result» буде автоматично розподілено і надано бібліотекою. Заданням масиву значень «item» ці структури можна упорядкувати як «стек» із потенційним отримання багатьох результатів одним викликом функції. Таким чином, «стек» можна розглядати як запис змінної довжини, вміст якого та порядок записів у якому визначаються лише користувачем. Частиною цього інтерфейсу є два унікальних лічильники. Для зберігання їхніх значень передбачено записи «noop» та «extra». Їхні значення ніколи не встановлюються бібліотекою, але результат «extra» буде занулено на початку кожної взаємодії із бібліотекою. Базовим документом при розробці користувацької програми буде файл заголовків pids.h. Там ви знайдете усі доступні записи (item), тип, який вони повертають (назву члена структури «result») і джерело для таких значень. Також там наведено документацію щодо додаткових лічильників та структур. ## Користування Нижче наведено типову послідовність викликів цього інтерфейсу. ``` 1. fatal_proc_unmounted() 2. procps_pids_new() 3. procps_pids_get(), procps_pids_reap() або procps_pids_select() 4. procps_pids_unref() ``` Функція **get** є ітератором для послідовних PID/TID, що повертає ці «items», раніше вказані за допомогою **new** або **reset**. Для непередбачуваних результатів для змінних передбачено дві функції. Функція **reap** збирає дані для усіх процесів, а функція **select** працює зі специфічними PID та UID. Обидві можуть повертати декілька «стеків», кожне з яких містить декілька структур «result». Крім того, користувач може наказати **упорядкувати** (**sort**) ці результати. Щоб скористатися будь-яким «stack» і отримати доступ до окремих структур «result», потрібен *relative\_enum*, як це показано у макросі **VAL**, який визначено у файлі заголовка. ТАкі значення можна запрограмувати як: значення від 0 до numitems-1. Втім, цю потребу типово можна задовольнити створенням ваших власних лічильників, які відповідають порядку у масиві «items». ## Застереження Програмний інтерфейс <pids> відрізняється від інших тим, що потрібні записи має бути надано під час виконання **new** або **reset**, останній варіант є унікальним для цього програмного інтерфейсу. Якщо якийсь із параметрів, *items* або *numitems*, є нульовим на час **new**, обов'язковим перед надсиланням будь-якого іншого виклику стає **reset**. Інакше, procps\_pids\_reset() слід викликати, лише якщо порядок або кількість записів у стеках змінено. Для функцій **new** і **unref** має бути надано адресу вказівник структури *info*. Із **new** її має бути ініціалізовано значенням NULL. Із **unref** її буде скинуто до NULL, якщо контрольний відлік дійде до нуля. Функції **get** і **reap** використовують параметр *which* для визначення того, слід отримувати дані лише для завдань чи для завдань і потоків обробки. Функція **select** потребує масиву PID або UID, як *these* разом із *numthese*, для визначення того, дані яких процесів слід отримати. Далі, ця функція працює із підмножиною **reap**. Якщо використано функцію **sort**, зазвичай, буде повернуто параметри *stacks* і *numstacked* у структурі «pids\_fetch». Нарешті, можна викликати функцію **fatal\_proc\_unmounted** до будь-якої іншої функції для забезпечення монтування каталогу /proc/. Якщо каталог змонтовано, параметр *info* матиме значення NULL, а параметр *return\_self* матиме нульове значення. Якщо, втім, деякі записи потрібні для запуску програми (*return\_self* відмінне від нуля), виклик **new** має передувати виклику цієї функції для того, щоб вказати *items* і отримати потрібний вказівник *info*. # ПОВЕРНУТЕ ЗНАЧЕННЯ ## Функції, які повертають ‘int’ На помилку вказуватиме від'ємне число, яке є завжди оберненим до якогось відомого значення з errno.h. На успіх вказує нульовий стан повернення. Втім, функції **ref** і **unref** повертають поточний контрольний відлік структури *info*. ## Функції, які повертають ‘address’ На помилку вказуватиме повернутий NUL-вказівник із повідомлення про причину у формальному значенні errno. На успіх вказує повернення вказівника на іменовану структуру. Втім, якщо щось переживе виклик **fatal\_proc\_unmounted**, NULL завжди буде повернуто, якщо значенням *return\_self* є нуль. # ДІАГНОСТИКА Щоб полегшити розробку програм, передбачено дві можливості procps-ng, якими можна скористатися. Першою є файл із назвою «libproc.supp», яким можна скористатися при розробці *багатопотокової* програми. Якщо скористатися ним у поєднанні із параметром valgrind «--suppressions=», можна уникнути виведення попереджень, які пов'язано із самою бібліотекою procps. Такі попередження виникають через те, що бібліотека обробляє засновані на «купі» функції отримання пам'яті у безпечний щодо потоків обробки спосіб. *Однопотокові* програми не призводитимуть до появи таких попереджень. Друга функція може допомогти забезпечити узгодженість посилань на члени «result» із очікуваннями бібліотеки. У цій функції передбачено, що наданий макрос у файлі заголовків буде використано для доступу до значення «result». Цю можливість можна активувати за допомогою будь-якого з вказаних нижче методів, а усі розбіжності буде записано до **stderr**. 1\) Додайте CFLAGS='-DXTRA\_PROCPS\_DEBUG' до будь-яких інших застосованих у вашому проєкті параметрів ./configure. 2\) Додайте #include <libproc2/xtra-procps-debug.h> у програму *після* #include <libproc2/pids.h>. Використання цієї можливості перевірки призводить до суттєвих обчислювальних витрат. Через це, важливо *не* вмикати її під час остаточного збирання або збирання програми для випуску. # ЗМІННІ СЕРЕДОВИЩА Встановлене значення є несуттєвим, достатнього самого факту його встановлення. [LIBPROC\_HIDE\_KERNEL](#LIBPROC_HIDE_KERNEL) Призведе до приховування потоків обробки ядра, які інакше було б повернуто викликом **procps\_pids\_get**, **procps\_pids\_select** або **procps\_pids\_reap**. # ТАКОЖ ПЕРЕГЛЯНЬТЕ [**procps**(3)](/man/os/procps/procps.3), [**procps\_misc**(3)](/man/os/procps/procps_misc.3), [**proc**(5)](/man/os/procps/proc.5). 3 вересня 2004 року procps-ng --- Document: procps_pids(3) from procps 4.0.7-r1 (Chainguard OS) Source: https://downloads.sourceforge.net/project/procps-ng/Production/procps-ng-4.0.7.tar.xz