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

libproc2                                          Sierpień 2022                                        PROCPS(3)