PROCPS(3) Library Functions Manual PROCPS(3) BEZEICHNUNG procps - API fur den Zugriff auf Informationen auf Systemebene im /proc-Dateisystem UBERSICHT In dieser Ubersicht werden funf verschiedene Schnittstellen dargestellt, die nach den Dateien benannt sind, auf die sie im Pseudodateisystem /proc zugreifen: diskstats, meminfo, slabinfo, stat und vmstat. #include int procps_new (struct info **info); int procps_ref (struct info *info); int procps_unref (struct info **info); struct result *procps_get ( struct info *Info, [ const char *Name, ] nur diskstats-API enum item Element); struct stack *procps_select ( struct info *Info, [ const char *Name, ] nur diskstats-API enum item *Element, int numitems); struct reaped *procps_reap ( struct info *Info, [ enum reap_type was, ] nur stat-API enum item *Elemente, int numitems); struct stack **procps_sort ( struct info *Info, struct stack *stacks[], int numstacked, enum item sortitem, enum sort_order order); Die oben genannten Funktionen und Strukturen sind generisch, aber das spezifische named_interface ware auch Teil aller Bezeichner. Beispielsweise ware `procps_new' tatsachlich `procps_meminfo_new' und `info' ware wirklich `diskstats_info' usw. In jedem Header-Dateinamen wird dasselbe named_interface mit dem angehangten Suffix `.h' verwendet. Linken Sie mit der Option -lproc2. BESCHREIBUNG Ubersicht Im Mittelpunkt dieser Schnittstellen 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. Jede 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 Headerdatei named_interface 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 Das Folgende ware eine typische Abfolge von Aufrufen dieser Schnittstellen. 1. procps_new() 2. procps_get(), procps_select() oder procps_reap() 3. procps_unref() Die Funktion get wird verwendet, um eine `result'-Struktur fur ein einzelnes `Element' abzurufen. Alternativ steht ein GET-Makro zur Verfugung, wenn nur der Ruckgabewert von Interesse ist. Die Funktion select kann mehrere `result'-Strukturen in einem einzigen `Stapel' abrufen. Fur unvorhersehbare variable Ergebnisse exportieren die Schnittstellen diskstats, slabinfo und stat eine reap-Funktion. Diese dient zum Abrufen mehrerer `Stapel', die jeweils mehrere `result'-Strukturen enthalten. Optional kann der Benutzer diese Ergebnisse 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 Funktionen new, ref, unref, get und select sind in allen funf Schnittstellen verfugbar. 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. Bei der diskstats-Schnittstelle identifiziert ein name-Parameter der Funktionen get und select einen Datentrager- oder Partitionsnamen. Fur die stat-Schnittstelle gibt ein what-Parameter der reap-Funktion an, ob Daten nur fur CPUs oder sowohl fur CPUs als auch fur NUMA-Knoten erfasst werden sollen. Bei Verwendung der Funktion sort waren die Parameter stacks und numstacked normalerweise diejenigen, die in der Struktur `reaped' zuruckgegeben werden. 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. FEHLERDIAGNOSE Zur Unterstutzung der Programmentwicklung gibt es eine zweite Bestimmung, die dazu beitragen kann, 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 verwendeten ./configure-Optionen hinzu. 2) Fugen Sie #include zu jedem Programm hinzu, das die benannte Schnittstelle enthalt. Diese Verifizierungsfunktion verursacht einen erheblichen Mehraufwand. Daher ist es wichtig, dass sie fur einen Produktions-/Release-Build nicht aktiviert wird. SIEHE AUCH procps_misc(3), procps_pids(3), proc(5). procps-ng 22. Januar 2024 PROCPS(3)