Provided by: procps_4.0.4-4ubuntu3.2_amd64 
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).