PROCPS_PIDS(3) | Library Functions Manual | PROCPS_PIDS(3) |
NAZWA
procps_pids - API do dostępu do informacji o procesach w systemie plików /proc
SKŁADNIA
#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.
OPIS
Przegląd
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.
Użycie
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'.
Zastrzeżenia
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.
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ę. Jednak, jeśli program przeżyje wywołanie fatal_proc_unmounted, zwracany jest zawsze NULL, jeśli return_self jest zerowy.
DIAGNOSTYKA
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.
ZMIENNE ŚRODOWISKOWE
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.
ZOBACZ TAKŻE
Sierpień 2022 | libproc2 |