PROCPS\_PIDS(3) Library Functions Manual PROCPS\_PIDS(3) # [BEZEICHNUNG](#BEZEICHNUNG) procps\_pids – API für den Zugriff auf Prozessinformationen im /proc-Dateisystem # ÜBERSICHT ``` #include ``` ``` 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); ``` ``` ``` Linken Sie mit der Option *-lproc2*. # [BESCHREIBUNG](#BESCHREIBUNG) ## Übersicht Im Mittelpunkt dieser Schnittstelle steht eine einfache ‘result’-Struktur, die ein ‘item’ plus seinen Wert widerspiegelt (in einer Union mit Standard-C-Sprachtypen als Mitgliedern). Alle ‘result’-Strukturen werden automatisch von der Bibliothek zugewiesen und bereitgestellt. Durch die Angabe eines Arrays von ‘Elementen’ können diese Strukturen als ‘Stapel’ organisiert werden, wodurch potenziell viele Ergebnisse mit einem einzigen Funktionsaufruf erzielt werden. Somit kann ein ‘Stapel’ als Datensatz variabler Länge betrachtet werden, dessen Inhalt und Reihenfolge ausschließlich vom Benutzer bestimmt werden. Diese Schnittstelle verfügt über zwei eindeutige Enumeratoren. Die Elemente ‘noop’ und ‘extra’ dienen zur Speicherung von Benutzerwerten. Sie werden nie von der Bibliothek gesetzt, aber das Ergebnis von ‘extra’ wird bei jeder Bibliotheksinteraktion auf Null gesetzt. Die Datei pids.h ist ein unverzichtbares Dokument während der Entwicklung Ihres Benutzerprogramms. Dort finden Sie die verfügbaren Elemente, deren Rückgabetyp (den Namen des Strukturelements ‘result’) und den Quellcode dieser Werte. Zusätzliche Enumeratoren und Strukturen sind dort ebenfalls dokumentiert. ## [Verwendung](#Verwendung) Im Folgenden sehen Sie eine typische Sequenz zum Aufruf dieser Schnittstelle. ``` 1. fatal_proc_unmounted() 2. procps_pids_new() 3. procps_pids_get(), procps_pids_reap() oder procps_pids_select() 4. procps_pids_unref() ``` Die Funktion **get** ist ein Iterator für aufeinanderfolgende PIDs/TIDs und gibt diejenigen ‘items’ zurück, die zuvor über **new** oder **reset** identifiziert wurden. Zwei Funktionen unterstützen unvorhersehbare, variable Ergebnisse. Die Funktion **reap** sammelt Daten für alle Prozesse, während die Funktion **select** bestimmte Prozess-IDs (PIDs) oder Benutzer-IDs (UIDs) verarbeitet. Beide können mehrere ‘Stacks’ zurückgeben, die jeweils mehrere Strukturen vom Typ ‘result’ enthalten. Optional kann ein Benutzer diese Ergebnisse mit **sort** sortieren. Um einen beliebigen ‘stack’ zu nutzen und auf einzelne ‘result’-Strukturen zuzugreifen, ist ein *relative\_enum* erforderlich, wie im Makro **VAL** in der Header-Datei definiert. Solche Werte könnten fest codiert werden, z.B. 0 bis numitems-1. In der Regel wird dieser Bedarf jedoch durch die Erstellung eigener Enumeratoren gedeckt, die der Reihenfolge des ‘items’-Arrays entsprechen. ## [Einschränkungen](#Einschr) Die <pids>-API unterscheidet sich von anderen dadurch, dass die relevanten Elemente zum Zeitpunkt **new** oder **reset** angegeben werden müssen, wobei letzteres für diese API einzigartig ist. Wenn der Parameter *items* oder *numitems* zum Zeitpunkt **new** null ist, ist **reset** zwingend erforderlich, bevor ein weiterer Aufruf erfolgt. Anderenfalls sollte procps\_pids\_reset() nur aufgerufen werden, wenn sich die Reihenfolge oder die Anzahl der Elemente in Ihren Stacks ändert. Für die Funktionen **new** und **unref** muss die Adresse eines *Info*-Strukturzeigers angegeben werden. Bei **new** muss dieser auf NULL initialisiert worden sein. Bei **unref** wird er auf NULL zurückgesetzt, wenn der Referenzzähler Null erreicht. Die Funktionen **get** und **reap** verwenden den Parameter *which*, um anzugeben, ob nur Tasks oder sowohl Tasks als auch Threads abgerufen werden sollen. Die Funktion **select** benötigt ein Array von PIDs oder UIDs als *these* sowie*numthese*, um die abzurufenden Prozesse zu identifizieren. Diese Funktion arbeitet dann als Teilmenge von **reap**. Bei Verwendung der Funktion **sort** wären die Parameter *stacks* und *numstacked* normalerweise diejenigen, die in der Struktur ‘pids\_fetch’ zurückgegeben werden. Schließlich kann vor jeder anderen Funktion die Funktion **fatal\_proc\_unmounted** aufgerufen werden, um sicherzustellen, dass das Verzeichnis /proc/ eingehängt ist. In diesem Fall wäre der Parameter *info* NULL und der Parameter *return\_self* null. Falls jedoch für das aufrufende Programm bestimmte Elemente benötigt werden (ein *return\_self* ungleich null), muss der Aufruf von **new** vorangestellt werden, um die Elemente *items* zu identifizieren und den benötigten Zeiger *info* zu erhalten. # [RÜCKGABEWERT](#R) ## Funktionen, die ein ‘int’ zurückgeben Ein Fehler wird durch eine negative Zahl angezeigt, die stets der Kehrwert eines bekannten errno.h-Wertes ist. Ein Erfolg wird durch den Rückgabewert Null signalisiert. Die Funktionen **ref** und **unref** geben jedoch die aktuelle Referenzanzahl der *info*-Struktur zurück. ## Funktionen, die ein ‘address’ zurückgeben Ein Fehler wird durch einen NULL-Rückgabezeiger angezeigt, wobei der Grund im formalen errno-Wert zu finden ist. Der Erfolg wird durch einen Zeiger auf die genannte Struktur angezeigt. Wenn jedoch ein **fatal\_proc\_unmounted**-Aufruf überstanden wird, wird immer NULL zurückgegeben, wenn*return\_self* null ist. # [FEHLERDIAGNOSE](#FEHLERDIAGNOSE) Zur Unterstützung der Programmentwicklung stehen zwei procps-ng-Provisionen zur Verfügung, die genutzt werden können. Die erste ist eine mitgelieferte Datei namens ‘libproc.supp’, die bei der Entwicklung einer *multithreaded*-Anwendung nützlich sein kann. Bei Verwendung mit der valgrind-Option ‘--suppressions=’ werden Warnungen vermieden, die mit der procps-Bibliothek selbst zusammenhängen. Solche Warnungen entstehen, weil die Bibliothek Heap-basierte Zuweisungen threadsicher verarbeitet. Eine *single-threaded*-Anwendung erhält diese Warnungen nicht. Die zweite Bestimmung kann dazu beitragen, sicherzustellen, dass die Mitgliedsreferenzen von ‘result’ den Erwartungen der Bibliothek entsprechen. Sie setzt voraus, dass für den Zugriff auf den Wert von ‘result’ ein in der Header-Datei bereitgestelltes Makro verwendet wird. Diese Funktion kann über eine der folgenden Methoden aktiviert werden und etwaige Abweichungen werden in **stderr** geschrieben. 1\) Fügen Sie CFLAGS='-DXTRA\_PROCPS\_DEBUG' zu allen anderen ./configure-Optionen hinzu, die Ihr Projekt möglicherweise verwendet. 2\) Fügen Sie #include <libproc2/xtra-procps-debug.h> zu jedem Programm *nach* dem #include <libproc2/pids.h> hinzu. Diese Verifizierungsfunktion verursacht einen erheblichen Mehraufwand. Daher ist es wichtig, dass sie für einen Produktions-/Release-Build *nicht* aktiviert wird. # [UMGEBUNGSVARIABLE(N)](#UMGEBUNGSVARIABLE%28N%29) The value set for the following is unimportant, just its presence. [LIBPROC\_HIDE\_KERNEL](#LIBPROC_HIDE_KERNEL) Dadurch werden Kernel-Threads ausgeblendet, die anderenfalls mit einem **procps\_pids\_get**-, **procps\_pids\_select**- oder **procps\_pids\_reap**-Aufruf zurückgegeben werden würden. # [SIEHE AUCH](#SIEHE_AUCH) [**procps**(3)](/man/os/procps/procps.3), [**procps\_misc**(3)](/man/os/procps/procps_misc.3), [**proc**(5)](/man/os/procps/proc.5). 3\. September 2004 procps-ng --- Document: procps_pids(3) from procps 4.0.7-r3 (Chainguard OS) Source: https://downloads.sourceforge.net/project/procps-ng/Production/procps-ng-4.0.7.tar.xz