PROCPS_PIDS(3)             Library Functions Manual             PROCPS_PIDS(3)

NUME
       procps_pids - API (interfa<?>a 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);


       Legatura cu -lproc2.


DESCRIERE
   Prezentare generala
       Esen<?>ial pentru aceasta interfa<?>a este o structura simpla de
       ,,rezultat" care reflecta un ,,element" plus valoarea acestuia (intr-o
       uniune cu tipuri de limbaj C standard ca membri).  Toate structurile
       ,,rezultat" sunt alocate <?>i furnizate automat de biblioteca.

       Prin specificarea unei matrice de ,,elemente", aceste structuri pot fi
       organizate ca o ,,stiva", cu poten<?>ialul de-a produce multe rezultate
       cu un singur apel catre func<?>ie.  Astfel, o ,,stiva" poate fi vazuta
       ca o inregistrare cu lungime variabila al carei con<?>inut <?>i ordine
       sunt determinate exclusiv de utilizator.

       Ca parte a acestei interfe<?>e exista doi enumeratori unici.
       Elementele ,,noop" <?>i ,,extra" exista pentru a pastra valorile
       utilizatorului.  Ele nu sunt niciodata definite de biblioteca, dar
       rezultatul ,,extra" va fi redus la zero cu fiecare interac<?>iune cu
       biblioteca.

       Fi<?>ierul pids.h va fi un document esen<?>ial in timpul dezvoltarii
       programului utilizatorului.  Acolo ve<?>i gasi elementele disponibile,
       tipul lor de returnare (numele membrului structurii ,,rezultat)" <?>i
       sursa acestor valori.  Acolo sunt de asemenea documentate enumeratori
       <?>i structuri suplimentare.


   Utilizare
       Urmatoarele linii, ar fi o secven<?>a tipica 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,
       returnand acele ,,articole" identificate anterior prin new sau reset.

       Doua func<?>ii asigura suport pentru rezultate variabile imprevizibile.
       Func<?>ia reap aduna date pentru toate procesele, in timp ce func<?>ia
       select se ocupa de PID-uri sau UID-uri specifice.  Ambele pot returna
       mai multe ,,stive" fiecare con<?>inand mai multe structuri ,,rezultat".
       Op<?>ional, un utilizator poate alege sa  foloseasca sort pentru a
       sorta astfel de rezultate

       Pentru a exploata orice ,,stiva" <?>i pentru a accesa structuri
       ,,rezultat" individuale, este necesar un relative_enum, a<?>a cum se
       arata in macrocomanda VAL definita in fi<?>ierul antet.  Astfel de
       valori ar putea fi codificate ca: de la 0 la numitems-1.  Cu toate
       acestea, aceasta nevoie este de obicei satisfacuta prin crearea
       propriilor enumeratori corespunzatori ordinii matricei ,,elemente".


   Avertismente
       Interfa<?>a de program <pids> difera de celelalte prin faptul ca acele
       elemente de interes trebuie furnizate in timpul execu<?>iei new sau
       reset, acesta din urma fiind unic pentru acest API.  Daca fie
       parametrul items, fie numitems este zero in timpul execu<?>iei new,
       atunci reset devine obligatoriu inainte de a lansa orice alt apel.

       Pentru func<?>iile new <?>i unref, trebuie furnizata adresa unui
       indicator de structura info.  Cu new, acesta trebuie sa fi fost
       ini<?>ializat la NULL.  Cu unref va fi reini<?>ializat la NULL daca
       numarul de referin<?>e ajunge la zero.

       Func<?>iile get <?>i reap folosesc parametrul which pentru a specifica
       daca trebuie preluate doar sarcinile sau atat sarcinile cat <?>i firele
       de execu<?>ie.

       Func<?>ia select necesita o matrice de PID-uri sau UID-uri ca these
       impreuna cu numthese pentru a identifica procesele care urmeaza sa fie
       preluate.  Aceasta func<?>ie func<?>ioneaza apoi ca un subset al lui
       reap.

       Cand se utilizeaza func<?>ia sort, parametrii stacks <?>i numstacked ar
       fi in mod normal cei returna<?>i in structura ,,pids_fetch".

       In cele din urma, o func<?>ie fatal_proc_unmounted poate fi apelata
       inaintea oricarei alte func<?>ii pentru a se asigura ca directorul
       ,,/proc/" este montat.  Ca atare, parametrul info va fi NULL <?>i
       parametrul return_self zero.  Daca, totu<?>i, unele elemente sunt
       dorite pentru programul emitent (un return_self altul decat zero),
       atunci apelul new trebuie sa il preceda pentru a identifica items <?>i
       pentru a ob<?>ine indicatorul info necesar.


VALOARE RETURNATA
   Func<?>ii care returneaza un ,,int" (numar intreg)
       O eroare va fi indicata printr-un numar negativ care este intotdeauna
       inversul unei valori binecunoscute a errno.h.

       Succesul este indicat de o valoare de returnare zero.  Cu toate
       acestea, func<?>iile ref <?>i unref returneaza numarul de referin<?>e
       curent al structurii info.


   Func<?>ii care returneaza o ,,adresa"
       O eroare va fi indicata printr-un indicator de returnare NULL cu
       motivul gasit in valoarea formala errno (numar eroare).

       Succesul este indicat de un indicator catre structura numita.  Cu toate
       acestea, daca ceva supravie<?>uie<?>te apelului fatal_proc_unmounted,
       NULL este intotdeauna returnat atunci cand return_self este zero.


DEPANAREA
       Pentru a ajuta la dezvoltarea programului, exista doua facilita<?>i
       procps-ng care pot fi exploatate.

       Prima este un fi<?>ier furnizat numit ,,libproc.supp" care poate fi
       util atunci cand se dezvolta o aplica<?>ie cu multiple-fire de
       execu<?>ie.  Cand este utilizat cu op<?>iunea valgrind
       ,,--suppressions=", avertismentele asociate cu biblioteca procps in
       sine sunt evitate.

       Astfel de avertismente apar deoarece biblioteca gestioneaza alocarile
       bazate pe ,,heap" intr-o maniera sigura pentru fire.  O aplica<?>ie cu
       un singur-fir de execu<?>ie nu va primi aceste avertismente.

       A doua facilitate poate ajuta sa ne asiguram ca referin<?>ele membrului
       ,,rezultat" sunt in acord cu a<?>teptarile bibliotecii.  Se presupune
       ca o macrocomanda furnizata in fi<?>ierul antet este utilizata pentru a
       accesa valoarea ,,rezultat".

       Aceasta caracteristica poate fi activata prin oricare dintre
       urmatoarele metode <?>i orice discrepan<?>e vor fi scrise la ie<?>irea
       standard de eroare.


       1) Adauga CFLAGS='-DXTRA_PROCPS_DEBUG' la orice alte op<?>iuni
          ./configure pe care le poate folosi proiectul dvs.


       2) Adauga #include <procps/xtra-procps-debug.h> la orice program dupa
          linia #include <procps/pids.h>.


       Aceasta caracteristica de verificare implica o suprasarcina
       substan<?>iala.  Prin urmare, este important ca aceasta sa nu fie
       activata pentru o versiune de produc<?>ie/lansare.


VARIABILE DE MEDIU
       Valoarea stabilita pentru urmatoarea variabila este neimportanta, 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)