Scroll to navigation

PROCPS(3) Library Functions Manual PROCPS(3)

НАЗВА

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

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

У цьому короткому описі представлено п'ять різних інтерфейсів, які названо за файлами, до яких вони надають доступ у фіктивній файловій системі /proc: diskstats, meminfo, slabinfo, stat та vmstat.

#include <libproc2/іменований_інтерфейс.h>
int procps_new   (struct info **info);
int procps_ref   (struct info  *info);
int procps_unref (struct info **info);
struct result *procps_get (


    struct info *info,
[   const char *name,      ]   лише програмний інтерфейс diskstats


    enum item item);
struct stack *procps_select (


    struct info *info,
[   const char *name,      ]   лише програмний інтерфейс diskstats


    enum item *items,


    int numitems);
struct reaped *procps_reap (


    struct info *info,
[   enum reap_type what,   ]   лише програмний інтерфейс stat


    enum item *items,


    int numitems);
struct stack **procps_sort (


    struct info *info,


    struct stack *stacks[],


    int numstacked,


    enum item sortitem,


    enum sort_order order);

Наведені вище функції і структури є загальними, але частиною будь-якого ідентифікатора може також бути специфічний запис іменований_інтерфейс. Наприклад, «procps_new» може бути насправді «procps_meminfo_new», а «info» може бути насправді «diskstats_info» тощо.

Той самий іменований_інтерфейс буде використано у кожній з назв файлів заголовків, назви яких формуються додаванням суфікса «.h».

Компонувати з -lproc2.

ОПИС

Огляд

Центральною для цих інтерфейсів є проста структура «result», яка визначає «item» і його значення (в об'єднання зі стандартними типами мови C, як учасниками). Усі структури «result» буде автоматично розподілено і надано бібліотекою.

Заданням масиву значень «item» ці структури можна упорядкувати як «стек» із потенційним отримання багатьох результатів одним викликом функції. Таким чином, «стек» можна розглядати як запис змінної довжини, вміст якого та порядок записів у якому визначаються лише користувачем.

Частиною кожного інтерфейсу є два унікальних лічильники. Для зберігання їхніх значень передбачено записи «noop» та «extra». Їхні значення ніколи не встановлюються бібліотекою, але результат «extra» буде занулено на початку кожної взаємодії із бібліотекою.

Базовим документом при розробці користувацької програми буде файл заголовків іменованого інтерфейсу. Там ви знайдете усі доступні записи (item), тип, який вони повертають (назву члена структури «result») і джерело для таких значень. Також там наведено документацію щодо додаткових лічильників та структур.

Користування

Нижче наведено типову послідовність викликів цих інтерфейсів.

1. procps_new()
2. procps_get(), procps_select() або procps_reap()
3. procps_unref()

Функцію get призначено для отримання структури «result» для окремого «item». Крім того, можна скористатися макросом GET, якщо потрібне лише значення, яке повертає функція.

Функція select може отримувати декілька структур «result» в одному значенні «stack».

Для непередбачуваних результатів для змінних інтерфейси diskstats, slabinfo і stat експортують функцію reap. Її використовують для отримання декількох «стеків», кожен з яких містить декілька структур «result». Крім того, користувач може наказати упорядкувати (sort) ці результати.

Щоб скористатися будь-яким «stack» і отримати доступ до окремих структур «result», потрібен relative_enum, як це показано у макросі VAL, який визначено у файлі заголовка. ТАкі значення можна запрограмувати як: значення від 0 до numitems-1. Втім, цю потребу типово можна задовольнити створенням ваших власних лічильників, які відповідають порядку у масиві «items».

Застереження

Функціями new, ref, unref, get та select можна скористатися в усіх п'яти інтерфейсах.

Для функцій new і unref має бути надано адресу вказівник структури info. Із new її має бути ініціалізовано значенням NULL. Із unref її буде скинуто до NULL, якщо контрольний відлік дійде до нуля.

У випадку інтерфейсу diskstats параметр name у функціях get і select вказує на диск або назву розділу

Для інтерфейсу stat параметр what функції reap вказує на те, чи слід збирати дані лише для процесорів або процесорів і вузлів NUMA.

Якщо використано функцію sort, зазвичай, буде повернуто параметри stacks і numstacked у структурі «reaped».

ПОВЕРНУТЕ ЗНАЧЕННЯ

Функції, які повертають «int»

На помилку вказуватиме від'ємне число, яке є завжди оберненим до якогось відомого значення з errno.h.

На успіх вказує нульовий стан повернення. Втім, функції ref і unref повертають поточний контрольний відлік структури info.

Функції, які повертають «address»

На помилку вказуватиме повернутий NUL-вказівник із повідомлення про причину у формальному значенні errno.

На успіх вказує повернення вказівника на іменовану структуру.

ДІАГНОСТИКА

Щоб допомогти у розробці програм, передбачено функцію, яка може допомогти забезпечити узгодженість посилань на члени «result» із очікуваннями бібліотеки. У цій функції передбачено, що наданий макрос у файлі заголовків буде використано для доступу до значення «result».

Цю можливість можна активувати за допомогою будь-якого з вказаних нижче методів, а усі розбіжності буде записано до stderr.

1)
Додайте CFLAGS='-DXTRA_PROCPS_DEBUG' до будь-яких інших застосованих параметрів ./configure.

2)
Додайте #include <procps/xtra-procps-debug.h> у програму після команд включення іменованих інтерфейсів.

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

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

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

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