procps_pids - API do dostępu do informacji o procesach w systemie
plików /proc
#include <libproc2/pids.h>
int procps_pids_new (struct pids_info **info, enum pids_item *items, int numitems);
int procps_pids_ref (struct pids_info *info);
int procps_pids_unref (struct pids_info **info);
struct pids_stack * procps_pids_get (
struct pids_info * info,
enum pids_fetch_type which);
struct pids_fetch * procps_pids_reap (
struct pids_info * info,
enum pids_fetch_type which);
struct pids_fetch * procps_pids_select (
struct pids_info * info,
unsigned * these,
int numthese,
enum pids_select_type which);
struct pids_stack ** procps_pids_sort (
struct pids_info * info,
struct pids_stack * stacks[],
int numstacked,
enum pids_item sortitem,
enum pids_sort_order order);
int procps_pids_reset (
struct pids_info * info,
enum pids_item * newitems,
int newnumitems);
struct pids_stack * fatal_proc_unmounted (
struct pids_info * info,
int return_self);
Konsolidować z
-lproc2.
Interfejs ten opiera 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ą tego 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 pids.h 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ń tego
intefejsu.
1. fatal_proc_unmounted()
2. procps_pids_new()
3. procps_pids_get(), procps_pids_reap() lub procps_pids_select()
4. procps_pids_unref()
Funkcja
get to iterator dla kolejnych PIDów/TIDów,
zwracający te elementy `item' wcześniej określane poprzez
new lub
reset.
Dwie funkcje obsługują nieprzewidywalne, zmienne wyniki. Funkcja
reap zbiera dane dla wszystkich procesów, a funkcja
select obsługuje konkretne PIDy i UIDy. Obie mogą
zwrócić wiele "stosów", z których
każdy zawiera 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'.
API <pids> różni się od innych tym, że
interesujące elementy trzeba przekazać w czasie
new lub
reset - to drugie zachodzi tylko dla tego API. Jeśli w czasie
new parametr
items lub
numitems jest zerowy,
wywołanie
reset jest obowiązkowe przed wykonaniem
dowolnego innego wywołania.
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.
Funkcje
get i
reap wykorzystują parametr
which,
określający, czy pobrane mogą być tylko zadania,
czy zadania i wątki.
Funkcja
select wymaga jako
these wraz z
numthese tablicy
PIDów lub UIDów, określających procesy do
pobrania. Ta funkcja operuje działa jako podzbiór
reap.
W przypadku funkcji
sort, parametry
stacks oraz
numstacked
będą zwykle zwracane w strukturze `pids_fetch'.
Funkcja
fatal_proc_unmounted może być wywołana przed
dowolną inną funkcją, aby upewnić się,
że katalog /proc/ jest zamontowany. W takim przypadku parametr
info będzie NULLem, a parametr
return_self zerem.
Jeśli jednak jakieś elementy są pożądane
przez wywołujący program (
return_self inny niż
zero), wywołanie
new musi je poprzedzać, aby
określić elementy
items i uzyskać
żądany wskaźnik
info.
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ę.
Jednak, jeśli program przeżyje wywołanie
fatal_proc_unmounted, zwracany jest zawsze NULL, jeśli
return_self jest zerowy.
Aby pomóc przy rozwijaniu programów, można
wykorzystać dwa udogodnienia procps-ng.
Pierwsze do dołączony plik o nazwie `libproc.supp', który
może być przydatny przy rozwijaniu aplikacji
wielowątkowych. W przypadku użycia opcji valgrinda
`--suppressions=', pomijane będą ostrzeżenia
związane z samą biblioteką procps.
Ostrzeżenia takie mogą się pojawić, ponieważ
biblioteka obsługuje przydzielanie pamięci na stercie w
sposób bezpieczny dla wątków. Aplikacje
jednowątkowe nie będą powodowały
ostrzeżeń.
Drugie udogodnienie pozwala 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 #include <procps/pids.h>.
Ta opcja weryfikacji dodaje istotny narzut. W związku z tym ważne
jest, żeby
nie była włączona w binariach
produkcyjnych.
Ustawiona wartość następującej zmiennej nie jest
istotna, a jedynie jej obecność.
- LIBPROC_HIDE_KERNEL
- Zmienna ukrywa wątki jądra, które w
innym wypadku byłyby zwrócone przez wywołania
procps_pids_get, procps_pids_select i
procps_pids_reap.
procps(3),
procps_misc(3),
proc(5).