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