procps - API do dostępu do informacji systemowych w systemie
plików /proc
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.
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.
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'.
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'.
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.
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ę.
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.
procps_misc(3),
procps_pids(3),
proc(5).