Provided by: procps_4.0.4-4ubuntu3_amd64 bug

NAMN

       procps_pids — API för att hämta ut processinformation i filsystemet /proc

SYNOPSIS

       #include <libproc2/pids.h>

       int procps_pids_new   (struct pids_info **info, enum pids_item *element, int antalelement);
       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 vilken);

       struct pids_fetch *procps_pids_reap (
           struct pids_info *info,
           enum pids_fetch_type vilken);

       struct pids_fetch *procps_pids_select (
           struct pids_info *info,
           unsigned *dessa,
           int antaldessa,
           enum pids_select_type vilken);

       struct pids_stack **procps_pids_sort (
           struct pids_info *info,
           struct pids_stack *stackar[],
           int antalstackade,
           enum pids_item sortelement,
           enum pids_sort_order ordning);

       int procps_pids_reset (
           struct pids_info *info,
           enum pids_item *nyaelement,
           int nyaantalelement);

       struct pids_stack *fatal_proc_unmounted (
           struct pids_info *info,
           int returnera_själv);

       Länka med -lproc2.

BESKRIVNING

   Översikt
       Centralt för detta gränssnitt är en enkel ”resultat”-post som avspeglar ett ”element” plus
       dess  värde  (i  en  union  med  standardtyper  i   språket   C   som   medlemmar).   Alla
       ”resultat”-poster allokeras automatiskt och tillhandahålls av biblioteket.

       Genom att ange en vektor av ”element” kan dessa strukturer organiseras som en ”stack”, som
       potentiellt ger många resultat med ett enda funktionsanrop. Alltså kan en ”stack” ses  som
       en post med variabel längd vars innehåll och ordning helt avgörs av användaren.

       Som  en  del  av  detta  gränssnitt  finns  det två unika uppräknare. Elementen ”noop” och
       ”extra”  finns  för  att  hålla  användarvärden.  De  sätts  aldrig  av  biblioteket,  men
       ”extra”-resultatet kommer nollställas vid varje biblioteksinteraktion.

       Filen  pids.h  kommer vara ett avgörande dokument under användarens utveckling av program.
       Där hittar man tillgängliga element, deras returtyp (medlemsnamnen  i  posten  ”resultat”)
       och källan för sådana värden. Ytterligare uppräknare och poster dokumenteras också där.

   Användning
       Följande skulle vara en typisk anropssekvens till detta gränssnitt.

       1. fatal_proc_unmounted()
       2. procps_pids_new()
       3. procps_pids_get(), procps_pids_reap() eller procps_pids_select()
       4. procps_pids_unref()

       Funktionen  get  är  en iterator för succesiva PID:n/TID:n, och returnerar dessa ”element”
       som tidigare identifierats via new eller reset.

       Två funktioner stödjer oförutsägbara variabla utfall. Funktionen reap samlar dat för  alla
       processer  medan  funktionen  select  arbetar  med  specifikaPID:er eller UID:er. Båda kan
       returnera flera ”stackar” som var och en innehåller multipla ”resultat”-poster. Om  önskas
       kan en användare välja att sort sådana resultat

       För  att  använda  någon  ”stack”,  och  komma åt individuella ”resultat”-poster, krävs en
       relativ_uppräkning som visas i makrot VAL definierat i huvudfilen.  Sådana  värden  skulle
       kunna  hårdkodas  som:  0 till antalelement-1. Dock uppfylls detta behov typiskt genom att
       skapa ens egna uppräknare motsvarande ordningen i vektorn av ”element”.

   Förbehåll
       API:et <pids> skiljer sig från andra genom att de intressanta elementen  måste  anges  vid
       tidpunkten  för  new  eller  reset,  där  den  senare  är  unik för detta API. Om antingen
       parametern  element  eller  antalelement  är  noll  vid  tidpunkten  för  new  blir  reset
       obligatorisk före man gör något annat anrop.

       För  funktionerna  new och unref måste adressen till en info-postpekare ges. Med new måste
       den  ha  initierats  till  NULL.  Med  unref  kommer  den   återställas   till   NULL   om
       referensräknaren når noll.

       Funktionerna  get  och  reap  använder  parametern  vilken  för  att  ange huruvida endast
       uppgifter eller både uppgifter och trådar skall hämtas.

       Funktionen select behöver en vektor av PID:er  eller  UID:er  som  dessa  tillsammans  med
       antaldessa  för  att  identifera  vilka processer som skall hämtas. Denna funktion arbetar
       sedan som en delmängd av reap.

       När man använder funktionen sort skall parametrarna stackar och antalstackade normalt vara
       de som returneras i posten ”pids_fetch”.

       Slutligen  kan  funktion  fatal_proc_unmounted  anropas  före någon annan funktion för att
       säkerställa att katalogen /proc/ är monterad. Därmed skall parametern info vara  NULL  och
       parametern  returnera_själv  vara noll. Om, däremot, några element önskas av det anropande
       programmet (en returnera_själv något annat än noll) då måste anropet av new föregå det för
       att identfiera elementen och hämta den önskade info-pekaren.

RETURVÄRDE

   Funktioner som returnerar en ”int”
       Ett  fel  kommer indikera ett negativt tal som alltid är inversen av något känt värde från
       errno.h.

       Lyckat resultat markeras med ett returvärde av noll. Dock returnerar funktionerna ref  och
       unref det aktuella värdet på referensräknaren för info-posten.

   Funktioner som returnerar en ”adress”
       Ett  fel kommer indikeras av en NULL-returpekare och orsaken går att hitta i dett formella
       errno-värdet.

       Lyckat resultat indikeras av en pekare på den namngivna posten.  Dock,  om  man  överlever
       anropet av fatal_proc_unmounted kommer NULL alltid returneras när returnera_själv är noll.

FELSÖKNING

       För  att  hjälpa  till  med  programutveckling  finns  det två metoder i procps-ng som kan
       användas.

       Den första är en levererad fil med namnet ”libproc.supp” som kan vara  användbar  när  man
       utvecklar  ett  multitrådat  program.  När  den används med flaggan ”--suppressions=” till
       valgrind undviks varningar som hör ihop med biblioteket procps självt.

       Sådana varningar uppstår för att biblioteket hanterar heap-baserade  allokeringar  på  ett
       trädsäkert sätt. Ett enkeltrådat program kommer inte att få dessa varningar.

       Den  andra  metoden  kan  hjälpa  till  att säkerställa att medlemsreferenser i ”resultat”
       stämmer överens med bibliotekets förväntningar. Den räknar  med  att  ett  tillhandahållet
       makro i huvuddfilen används för att komma åt ”resultat”-värdet.

       Denna  funktion  kan  aktiveras  genom  någon  av  de  följande  metoderna  och eventuella
       avvikelser kommer att skrivas till standard fel.

       1) Lägg till CFLAGS='-DXTRA_PROCPS_DEBUG' till eventuella andra flaggor  till  ./configure
          som ditt projekt kan tänkas använda.

       2) Lägg till #include <procps/xtra-procps-debug.h> till varje program efter raden #include
          <procps/pids.h>.

       Denna verifieringsfunktion orsakar en väsentlig kostnad. Därför är  det  viktigt  att  den
       inte är aktiverad för produktions-/utgåvebyggen.

MILJÖVARIABLER

       Värdet som sätts på följande är oviktigt, bara att den finns.

       LIBPROC_HIDE_KERNEL
              Detta  kommer  dölja  kärntrådar  som  annars  skulle  returnera  med  ett anrop av
              procps_pids_get, procps_pids_select eller procps_pids_reap.

SE ÄVEN

       procps(3), procps_misc(3), proc(5).