PROCPS_PIDS(3)

BEZEICHNUNG
procps_pids – API für den Zugriff auf Prozessinformationen im /proc-Dateisystem

ÜBERSICHT
#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);

Linken Sie mit der Option -lproc2.

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
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
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 sowienumthese, 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

  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, wennreturn_self null ist.

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)
The value set for the following is unimportant, just its presence.

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
procps(3), procps_misc(3), proc(5).