Scroll to navigation

PROCPS_PIDS(3) Library Functions Manual PROCPS_PIDS(3)

НАЗВА

procps_pids — програмний інтерфейс для доступу до даних процесів у файловій системі /proc

КОРОТКИЙ ОПИС

#include <libproc2/pids.h>
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.

Для функцій 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 <procps/xtra-procps-debug.h> у програму після #include <procps/pids.h>.

Використання цієї можливості перевірки призводить до суттєвих обчислювальних витрат. Через це, важливо не вмикати її під час остаточного збирання або збирання програми для випуску.

ЗМІННІ СЕРЕДОВИЩА

Встановлене значення є несуттєвим, достатнього самого факту його встановлення.

Призведе до приховування потоків обробки ядра, які інакше було б повернуто викликом procps_pids_get, procps_pids_select або procps_pids_reap.

ТАКОЖ ПЕРЕГЛЯНЬТЕ

procps(3), procps_misc(3), proc(5).

серпень 2022 року libproc2