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).

libproc2                                          Sierpień 2022                                   PROCPS_PIDS(3)