PROCPS_PIDS(3) Library Functions Manual PROCPS_PIDS(3) NAZWA procps_pids - API do dostepu do informacji o procesach w systemie plikow /proc SKLADNIA #include 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); Konsolidowac z -lproc2. OPIS Przeglad Interfejs ten opiera sie na prostej strukturze `result', odzwierciedlajacej element `item' wraz z jego wartoscia (w unii ze standardowymi typami C jako skladowymi). Wszystkie struktury `result' sa automatycznie przydzielane i dostarczane przez biblioteke. Podajac tablice elementow `item', struktury te moga byc zorganizowane w "stos", potencjalnie zwracajac wiele wynikow w pojedynczym wywolaniu funkcji. W ten sposob na "stos" mozna patrzec jak na rekord zmiennej dlugosci, ktorego zawartosc i porzadek sa okreslane wylacznie przez uzytkownika. Czescia tego interfejsu jest para unikatowych enumeratorow. Elementy `noop' i `extra' istnieja w celu trzymania wartosci uzytkownika. Nie sa nigdy ustawiane przez biblioteke, ale wynik `extra' jest zerowany przy kazdej interakcji z biblioteka. Plik pids.h jest podstawowym dokumentem przy tworzeniu programu uzytkownika. Tam mozna zalezc dostepne elementy, ich typ zwracany (nazwe skladowej struktury `result') oraz zrodla tych wartosci. Tam tez sa udokumentowane dodatkowe enumeratory czy struktury. Uzycie Ponizej znajduje sie typowa sekwencja wywolan 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 PIDow/TIDow, zwracajacy te elementy `item' wczesniej okreslane poprzez new lub reset. Dwie funkcje obsluguja nieprzewidywalne, zmienne wyniki. Funkcja reap zbiera dane dla wszystkich procesow, a funkcja select obsluguje konkretne PIDy i UIDy. Obie moga zwrocic wiele "stosow", z ktorych kazdy zawiera wiele struktur `result'. Opcjonalnie uzytkownik moze zdecydowac, aby wykonac sort tych wynikow. Aby wykorzystac dowolny "stos" i dostac sie do poszczegolnych struktur `result', wymagana jest wartosc relative_enum, jak widac w makrze VAL zdefiniowanym w pliku naglowkowym. Takie wartosci moga byc sztywno zakodowane od 0 do numitems-1. Zwykle jednak te potrzebe zaspokaja sie tworzac wlasne enumeratory odpowiadajace kolejnosci tablicy `items'. Zastrzezenia API rozni sie od innych tym, ze interesujace elementy trzeba przekazac w czasie new lub reset - to drugie zachodzi tylko dla tego API. Jesli w czasie new parametr items lub numitems jest zerowy, wywolanie reset jest obowiazkowe przed wykonaniem dowolnego innego wywolania. W przypadku funkcji new i unref, trzeba przekazac adres wskaznika do struktury info. W przypadku new musi byc zainicjowany na NULL. W przypadku unref zostanie ustawiony na NULL, jesli licznik odwolan osiagnie zero. Funkcje get i reap wykorzystuja parametr which, okreslajacy, czy pobrane moga byc tylko zadania, czy zadania i watki. Funkcja select wymaga jako these wraz z numthese tablicy PIDow lub UIDow, okreslajacych procesy do pobrania. Ta funkcja operuje dziala jako podzbior reap. W przypadku funkcji sort, parametry stacks oraz numstacked beda zwykle zwracane w strukturze `pids_fetch'. Funkcja fatal_proc_unmounted moze byc wywolana przed dowolna inna funkcja, aby upewnic sie, ze katalog /proc/ jest zamontowany. W takim przypadku parametr info bedzie NULLem, a parametr return_self zerem. Jesli jednak jakies elementy sa pozadane przez wywolujacy program (return_self inny niz zero), wywolanie new musi je poprzedzac, aby okreslic elementy items i uzyskac zadany wskaznik info. WARTOSC ZWRACANA Funkcje zwracajace `int' Blad jest oznaczany poprzez liczbe ujemna, bedaca liczba przeciwna do znanej wartosci errno.h. Sukces jest oznaczany wartoscia zerowa. Jednak funkcje ref i unref zwracaja biezacy licznik odwolan struktury info. Funkcje zwracajace adres Blad jest oznaczany zwracanym wskaznikiem NULL, a powod mozna znalezc w wartosci errno. Sukces jest oznaczany wskaznikiem na nazwana strukture. Jednak, jesli program przezyje wywolanie fatal_proc_unmounted, zwracany jest zawsze NULL, jesli return_self jest zerowy. DIAGNOSTYKA Aby pomoc przy rozwijaniu programow, mozna wykorzystac dwa udogodnienia procps-ng. Pierwsze do dolaczony plik o nazwie `libproc.supp', ktory moze byc przydatny przy rozwijaniu aplikacji wielowatkowych. W przypadku uzycia opcji valgrinda `--suppressions=', pomijane beda ostrzezenia zwiazane z sama biblioteka procps. Ostrzezenia takie moga sie pojawic, poniewaz biblioteka obsluguje przydzielanie pamieci na stercie w sposob bezpieczny dla watkow. Aplikacje jednowatkowe nie beda powodowaly ostrzezen. Drugie udogodnienie pozwala zapewnic, ze odwolania do skladowej `result' zgadzaja sie z oczekiwaniami biblioteki. Zaklada, ze do dostepu do wartosci `result' jest uzywane makro udostepnione w pliku naglowkowym. Te opcje mozna wlaczyc w jeden z ponizszych sposobow, a wszystkie niezgodnosci beda wypisane na stderr. 1) Dodanie CFLAGS='-DXTRA_PROCPS_DEBUG' do pozostalych uzytych opcji ./configure. 2) Dodanie #include do dowolnego programu po #include . Ta opcja weryfikacji dodaje istotny narzut. W zwiazku z tym wazne jest, zeby nie byla wlaczona w binariach produkcyjnych. ZMIENNE SRODOWISKOWE Ustawiona wartosc nastepujacej zmiennej nie jest istotna, a jedynie jej obecnosc. LIBPROC_HIDE_KERNEL Zmienna ukrywa watki jadra, ktore w innym wypadku bylyby zwrocone przez wywolania procps_pids_get, procps_pids_select i procps_pids_reap. ZOBACZ TAKZE procps(3), procps_misc(3), proc(5). libproc2 Sierpien 2022 PROCPS_PIDS(3)