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).