Man page - procps_pids(3)

Packages contains this manual

Available languages:

en pl sv uk ro

Manual

PROCPS_PIDS

NAZWA
SKŁADNIA
OPIS
Przegląd
Użycie
Zastrzeżenia
WARTOŚĆ ZWRACANA
Funkcje zwracające ‘int’
Funkcje zwracające adres
DIAGNOSTYKA
ZMIENNE ŚRODOWISKOWE
ZOBACZ TAKŻE

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

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