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