Provided by: procps_4.0.4-4ubuntu3.2_amd64 
NUME
procps_pids - API (interfață de program) pentru a accesa informații la nivel de sistem din sistemul de
fișiere „/proc”
REZUMAT
#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);
Legătură cu -lproc2.
DESCRIERE
Prezentare generală
Esențial pentru această interfață este o structură simplă de „rezultat” care reflectă un „element” plus
valoarea acestuia (într-o uniune cu tipuri de limbaj C standard ca membri). Toate structurile „rezultat”
sunt alocate și furnizate automat de bibliotecă.
Prin specificarea unei matrice de „elemente”, aceste structuri pot fi organizate ca o „stivă”, cu
potențialul de-a produce multe rezultate cu un singur apel către funcție. Astfel, o „stivă” poate fi
văzută ca o înregistrare cu lungime variabilă al cărei conținut și ordine sunt determinate exclusiv de
utilizator.
Ca parte a acestei interfețe există doi enumeratori unici. Elementele „noop” și „extra” există pentru a
păstra valorile utilizatorului. Ele nu sunt niciodată definite de bibliotecă, dar rezultatul „extra” va
fi redus la zero cu fiecare interacțiune cu bibliotecă.
Fișierul pids.h va fi un document esențial în timpul dezvoltării programului utilizatorului. Acolo veți
găsi elementele disponibile, tipul lor de returnare (numele membrului structurii „rezultat)” și sursa
acestor valori. Acolo sunt de asemenea documentate enumeratori și structuri suplimentare.
Utilizare
Următoarele linii, ar fi o secvență tipică de apeluri la aceste interfețe.
1. fatal_proc_unmounted()
2. procps_pids_new()
3. procps_pids_get(), procps_pids_reap() sau procps_pids_select()
4. procps_pids_unref()
Funcția get este un iterator pentru PID-uri/TID-uri succesive, returnând acele „articole” identificate
anterior prin new sau reset.
Două funcții asigură suport pentru rezultate variabile imprevizibile. Funcția reap adună date pentru
toate procesele, în timp ce funcția select se ocupă de PID-uri sau UID-uri specifice. Ambele pot returna
mai multe „stive” fiecare conținând mai multe structuri „rezultat”. Opțional, un utilizator poate alege
să folosească sort pentru a sorta astfel de rezultate
Pentru a exploata orice „stivă” și pentru a accesa structuri „rezultat” individuale, este necesar un
relative_enum, așa cum se arată în macrocomanda VAL definită în fișierul antet. Astfel de valori ar
putea fi codificate ca: de la 0 la numitems-1. Cu toate acestea, această nevoie este de obicei
satisfăcută prin crearea propriilor enumeratori corespunzători ordinii matricei „elemente”.
Avertismente
Interfața de program <pids> diferă de celelalte prin faptul că acele elemente de interes trebuie
furnizate în timpul execuției new sau reset, acesta din urmă fiind unic pentru acest API. Dacă fie
parametrul items, fie numitems este zero în timpul execuției new, atunci reset devine obligatoriu înainte
de a lansa orice alt apel.
Pentru funcțiile new și unref, trebuie furnizată adresa unui indicator de structură info. Cu new, acesta
trebuie să fi fost inițializat la NULL. Cu unref va fi reinițializat la NULL dacă numărul de referințe
ajunge la zero.
Funcțiile get și reap folosesc parametrul which pentru a specifica dacă trebuie preluate doar sarcinile
sau atât sarcinile cât și firele de execuție.
Funcția select necesită o matrice de PID-uri sau UID-uri ca these împreună cu numthese pentru a
identifica procesele care urmează să fie preluate. Această funcție funcționează apoi ca un subset al lui
reap.
Când se utilizează funcția sort, parametrii stacks și numstacked ar fi în mod normal cei returnați în
structura „pids_fetch”.
În cele din urmă, o funcție fatal_proc_unmounted poate fi apelată înaintea oricărei alte funcții pentru a
se asigura că directorul „/proc/” este montat. Ca atare, parametrul info va fi NULL și parametrul
return_self zero. Dacă, totuși, unele elemente sunt dorite pentru programul emitent (un return_self
altul decât zero), atunci apelul new trebuie să îl precedă pentru a identifica items și pentru a obține
indicatorul info necesar.
VALOARE RETURNATĂ
Funcții care returnează un „int” (număr întreg)
O eroare va fi indicată printr-un număr negativ care este întotdeauna inversul unei valori binecunoscute
a errno.h.
Succesul este indicat de o valoare de returnare zero. Cu toate acestea, funcțiile ref și unref
returnează numărul de referințe curent al structurii info.
Funcții care returnează o „adresă”
O eroare va fi indicată printr-un indicator de returnare NULL cu motivul găsit în valoarea formală errno
(număr eroare).
Succesul este indicat de un indicator către structura numită. Cu toate acestea, dacă ceva
supraviețuiește apelului fatal_proc_unmounted, NULL este întotdeauna returnat atunci când return_self
este zero.
DEPANAREA
Pentru a ajuta la dezvoltarea programului, există două facilități procps-ng care pot fi exploatate.
Prima este un fișier furnizat numit „libproc.supp” care poate fi util atunci când se dezvoltă o aplicație
cu multiple-fire de execuție. Când este utilizat cu opțiunea valgrind „--suppressions=”, avertismentele
asociate cu biblioteca procps în sine sunt evitate.
Astfel de avertismente apar deoarece biblioteca gestionează alocările bazate pe „heap” într-o manieră
sigură pentru fire. O aplicație cu un singur-fir de execuție nu va primi aceste avertismente.
A doua facilitate poate ajuta să ne asigurăm că referințele membrului „rezultat” sunt în acord cu
așteptările bibliotecii. Se presupune că o macrocomandă furnizată în fișierul antet este utilizată
pentru a accesa valoarea „rezultat”.
Această caracteristică poate fi activată prin oricare dintre următoarele metode și orice discrepanțe vor
fi scrise la ieșirea standard de eroare.
1) Adaugă CFLAGS='-DXTRA_PROCPS_DEBUG' la orice alte opțiuni ./configure pe care le poate folosi
proiectul dvs.
2) Adaugă #include <procps/xtra-procps-debug.h> la orice program după linia #include <procps/pids.h>.
Această caracteristică de verificare implică o suprasarcină substanțială. Prin urmare, este important ca
aceasta să nu fie activată pentru o versiune de producție/lansare.
VARIABILE DE MEDIU
Valoarea stabilită pentru următoarea variabilă este neimportantă, doar prezența acesteia.
LIBPROC_HIDE_KERNEL
Acest lucru va ascunde firele de execuție ale nucleului care altfel ar fi returnate cu un apel
procps_pids_get, procps_pids_select sau procps_pids_reap.
CONSULTAȚI ȘI
procps(3), procps_misc(3), proc(5).
libproc2 august 2022 PROCPS_PIDS(3)