PROCPS_PIDS(3) Library Functions Manual PROCPS_PIDS(3) BEZEICHNUNG procps_pids - API fur den Zugriff auf Prozessinformationen im /proc-Dateisystem UBERSICHT #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 Ubersicht 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' konnen diese Strukturen als `Stapel' organisiert werden, wodurch potenziell viele Ergebnisse mit einem einzigen Funktionsaufruf erzielt werden. Somit kann ein `Stapel' als Datensatz variabler Lange betrachtet werden, dessen Inhalt und Reihenfolge ausschliesslich vom Benutzer bestimmt werden. Diese Schnittstelle verfugt uber 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 wahrend der Entwicklung Ihres Benutzerprogramms. Dort finden Sie die verfugbaren Elemente, deren Ruckgabetyp (den Namen des Strukturelements `result') und den Quellcode dieser Werte. Zusatzliche 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 fur aufeinanderfolgende PIDs/TIDs und gibt diejenigen `items' zuruck, die zuvor uber new oder reset identifiziert wurden. Zwei Funktionen unterstutzen unvorhersehbare, variable Ergebnisse. Die Funktion reap sammelt Daten fur alle Prozesse, wahrend die Funktion select bestimmte Prozess-IDs (PIDs) oder Benutzer-IDs (UIDs) verarbeitet. Beide konnen mehrere `Stacks' zuruckgeben, 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 konnten 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. Einschrankungen Die -API unterscheidet sich von anderen dadurch, dass die relevanten Elemente zum Zeitpunkt new oder reset angegeben werden mussen, wobei letzteres fur 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 andert. Fur 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 zuruckgesetzt, wenn der Referenzzahler 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 benotigt 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 waren die Parameter stacks und numstacked normalerweise diejenigen, die in der Struktur `pids_fetch' zuruckgegeben werden. Schliesslich kann vor jeder anderen Funktion die Funktion fatal_proc_unmounted aufgerufen werden, um sicherzustellen, dass das Verzeichnis /proc/ eingehangt ist. In diesem Fall ware der Parameter info NULL und der Parameter return_self null. Falls jedoch fur das aufrufende Programm bestimmte Elemente benotigt werden (ein return_self ungleich null), muss der Aufruf von new vorangestellt werden, um die Elemente items zu identifizieren und den benotigten Zeiger info zu erhalten. RUCKGABEWERT Funktionen, die ein `int' zuruckgeben Ein Fehler wird durch eine negative Zahl angezeigt, die stets der Kehrwert eines bekannten errno.h-Wertes ist. Ein Erfolg wird durch den Ruckgabewert Null signalisiert. Die Funktionen ref und unref geben jedoch die aktuelle Referenzanzahl der info-Struktur zuruck. Funktionen, die ein `address' zuruckgeben Ein Fehler wird durch einen NULL-Ruckgabezeiger 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 uberstanden wird, wird immer NULL zuruckgegeben, wennreturn_self null ist. FEHLERDIAGNOSE Zur Unterstutzung der Programmentwicklung stehen zwei procps-ng-Provisionen zur Verfugung, die genutzt werden konnen. Die erste ist eine mitgelieferte Datei namens `libproc.supp', die bei der Entwicklung einer multithreaded-Anwendung nutzlich sein kann. Bei Verwendung mit der valgrind-Option `--suppressions=' werden Warnungen vermieden, die mit der procps-Bibliothek selbst zusammenhangen. Solche Warnungen entstehen, weil die Bibliothek Heap-basierte Zuweisungen threadsicher verarbeitet. Eine single-threaded-Anwendung erhalt diese Warnungen nicht. Die zweite Bestimmung kann dazu beitragen, sicherzustellen, dass die Mitgliedsreferenzen von `result' den Erwartungen der Bibliothek entsprechen. Sie setzt voraus, dass fur den Zugriff auf den Wert von `result' ein in der Header-Datei bereitgestelltes Makro verwendet wird. Diese Funktion kann uber eine der folgenden Methoden aktiviert werden und etwaige Abweichungen werden in stderr geschrieben. 1) Fugen Sie CFLAGS='-DXTRA_PROCPS_DEBUG' zu allen anderen ./configure-Optionen hinzu, die Ihr Projekt moglicherweise verwendet. 2) Fugen Sie #include zu jedem Programm nach dem #include hinzu. Diese Verifizierungsfunktion verursacht einen erheblichen Mehraufwand. Daher ist es wichtig, dass sie fur 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 zuruckgegeben werden wurden. SIEHE AUCH procps(3), procps_misc(3), proc(5). procps-ng 3. September 2004 PROCPS_PIDS(3)