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
Sierpień 2022 | libproc2 |