Provided by: procps_4.0.4-4ubuntu5_amd64 
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).