PROCPS(3) Library Functions Manual PROCPS(3)

procps – API für den Zugriff auf Informationen auf Systemebene im /proc-Dateisystem

ÜBERSICHT

In dieser Übersicht werden fünf verschiedene Schnittstellen dargestellt, die nach den Dateien benannt sind, auf die sie im Pseudodateisystem /proc zugreifen: diskstats, meminfo, slabinfo, stat und vmstat.

#include <libproc2/benannte_Schnittstelle.h>
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 wäre auch Teil aller Bezeichner. Beispielsweise wäre ‘procps_new’ tatsächlich ‘procps_meminfo_new’ und ‘info’ wäre wirklich ‘diskstats_info’ usw.

In jedem Header-Dateinamen wird dasselbe named_interface mit dem angehängten Suffix ‘.h’ verwendet.

Linken Sie mit der Option -lproc2.

Übersicht

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

Jede 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 Headerdatei named_interface 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.

Das Folgende wäre 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 für ein einzelnes ‘Element’ abzurufen. Alternativ steht ein GET-Makro zur Verfügung, wenn nur der Rückgabewert von Interesse ist.

Die Funktion select kann mehrere ‘result’-Strukturen in einem einzigen ‘Stapel’ abrufen.

Für 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 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.

Die Funktionen new, ref, unref, get und select sind in allen fünf Schnittstellen verfügbar.

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.

Bei der diskstats-Schnittstelle identifiziert ein name-Parameter der Funktionen get und select einen Datenträger- oder Partitionsnamen.

Für die stat-Schnittstelle gibt ein what-Parameter der reap-Funktion an, ob Daten nur für CPUs oder sowohl für CPUs als auch für NUMA-Knoten erfasst werden sollen.

Bei Verwendung der Funktion sort wären die Parameter stacks und numstacked normalerweise diejenigen, die in der Struktur ‘reaped’ zurückgegeben werden.

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.

Zur Unterstützung 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 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 verwendeten ./configure-Optionen hinzu.
2)
Fügen Sie #include <libproc2/xtra-procps-debug.h> zu jedem Programm hinzu, das die benannte Schnittstelle enthält.

Diese Verifizierungsfunktion verursacht einen erheblichen Mehraufwand. Daher ist es wichtig, dass sie für einen Produktions-/Release-Build nicht aktiviert wird.

procps_misc(3), procps_pids(3), proc(5).

22. Januar 2024 procps-ng