Provided by: procps_4.0.4-4ubuntu3_amd64 bug

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