Scroll to navigation

PROCPS(3) Library Functions Manual PROCPS(3)

NAZWA

procps - API do dostępu do informacji systemowych w systemie plików /proc

SKŁADNIA

W niniejszym opisie jest reprezentowanych pięć różnych interfejsów, nazwanych od plików służących do dostępu w pseudo systemie plików /proc: diskstats, meminfo, slabinfo, stat oraz vmstat.

#include <libproc2/interfejs.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,      ]   tylko API diskstats


    enum item item);
struct stack *procps_select (


    struct info *info,
[   const char *name,      ]   tylko API diskstats


    enum item *items,


    int numitems);
struct reaped *procps_reap (


    struct info *info,
[   enum reap_type what,   ]   tylko API 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);

Powyższe funkcje i struktury są ogólne, ale konkretne interfejsy stają się częścią identyfikatorów. Np. `procps_new' właściwie staje się `procps_meminfo_new', `info' staje się `diskstats_info' itd.

Ten sam interfejs jest używany w nazwie każdego pliku nagłówkowego z dodanym rozszerzeniem `.h'.

Konsolidować z -lproc2.

OPIS

Przegląd

Interfejsy te opierają się na prostej strukturze `result', odzwierciedlającej element `item' wraz z jego wartością (w unii ze standardowymi typami C jako składowymi). Wszystkie struktury `result' są automatycznie przydzielane i dostarczane przez bibliotekę.

Podając tablicę elementów `item', struktury te mogą być zorganizowane w "stos", potencjalnie zwracając wiele wyników w pojedynczym wywołaniu funkcji. W ten sposób na "stos" można patrzeć jak na rekord zmiennej długości, którego zawartość i porządek są określane wyłącznie przez użytkownika.

Częścią każdego interfejsu jest para unikatowych enumeratorów. Elementy `noop' i `extra' istnieją w celu trzymania wartości użytkownika. Nie są nigdy ustawiane przez bibliotekę, ale wynik `extra' jest zerowany przy każdej interakcji z biblioteką.

Plik nagłówkowy interfejsu jest podstawowym dokumentem przy tworzeniu programu użytkownika. Tam można zaleźć dostępne elementy, ich typ zwracany (nazwę składowej struktury `result') oraz źródła tych wartości. Tam też są udokumentowane dodatkowe enumeratory czy struktury.

Użycie

Poniżej znajduje się typowa sekwencja wywołań tych intefejsów.

1. procps_new()
2. procps_get(), procps_select() lub procps_reap()
3. procps_unref()

Funkcja get służy do odczytania struktury `result' dla pojedynczego elementu `item'. Alternatywnie dostępne jest makro GET, kiedy istotna jest tylko wartość zwracana.

Funkcja select potrafi odczytać wiele struktur `result' z pojedynczego "stosu".

Na potrzeby nieprzewidywalnych, zmiennych wyników, interfejsy diskstats, slabinfo oraz stat eksportują funkcję reap. Służy do odczytania wielu "stosów", zawierających wiele struktur `result'. Opcjonalnie użytkownik może zdecydować, aby wykonać sort tych wyników.

Aby wykorzystać dowolny "stos" i dostać się do poszczególnych struktur `result', wymagana jest wartość relative_enum, jak widać w makrze VAL zdefiniowanym w pliku nagłówkowym. Takie wartości mogą być sztywno zakodowane od 0 do numitems-1. Zwykle jednak tę potrzebę zaspokaja się tworząc własne enumeratory odpowiadające kolejności tablicy `items'.

Zastrzeżenia

Funkcje new, ref, unref, get oraz select są dostępne we wszystkich pięciu interfejsach.

W przypadku funkcji new i unref, trzeba przekazać adres wskaźnika do struktury info. W przypadku new musi być zainicjowany na NULL. W przypadku unref zostanie ustawiony na NULL, jeśli licznik odwołań osiągnie zero.

W przypadku interfejsu diskstats, parametr name funkcji get i select określa nazwę dysku lub partycji

W przypadku interfejsu stat, parametr what funkcji reap określa, czy zebrane mają być dane tylko dla CPU, czy dla CPU oraz NUMA.

Przy używaniu funkcji sort, parametry stacks i numstacked są zwykle zwracame w strukturze `reaped'.

WARTOŚĆ ZWRACANA

Funkcje zwracające `int'

Błąd jest oznaczany poprzez liczbę ujemną, będącą liczbą przeciwną do znanej wartości errno.h.

Sukces jest oznaczany wartością zerową. Jednak funkcje ref i unref zwracają bieżący licznik odwołań struktury info.

Funkcje zwracające adres

Błąd jest oznaczany zwracanym wskaźnikiem NULL, a powód można znaleźć w wartości errno.

Sukces jest oznaczany wskaźnikiem na nazwaną strukturę.

DIAGNOSTYKA

Aby pomóc przy rozwijaniu programów, jest udogodnienie pozwalające zapewnić, że odwołania do składowej `result' zgadzają się z oczekiwaniami biblioteki. Zakłada, że do dostępu do wartości `result' jest używane makro udostępnione w pliku nagłówkowym.

Tę opcję można włączyć w jeden z poniższych sposobów, a wszystkie niezgodności będą wypisane na stderr.

1)
Dodanie CFLAGS='-DXTRA_PROCPS_DEBUG' do pozostałych użytych opcji ./configure.

2)
Dodanie #include <procps/xtra-procps-debug.h> do dowolnego programu po nagłówkach nazwanych interfejsów.

Ta opcja weryfikacji dodaje istotny narzut. W związku z tym ważne jest, żeby nie była włączona w binariach produkcyjnych.

ZOBACZ TAKŻE

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

Sierpień 2022 libproc2