Provided by: procps_4.0.4-4ubuntu5_amd64 
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).