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

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.