Scroll to navigation

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ść.

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

procps(3), procps_misc(3), proc(5).

Sierpień 2022 libproc2