1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
.\"
.\" Copyright (c) 2020-2023 Jim Warner <james.warner@comcast.net>
.\" Copyright (c) 2020-2023 Craig Small <csmall@dropbear.xyz>
.\"
.\" This manual is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public
.\" License as published by the Free Software Foundation; either
.\" version 2.1 of the License, or (at your option) any later version.
.\"
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH PROCPS 3 "Sierpień 2022" libproc2
.\" Please adjust this date whenever revising the manpage.
.\"
.nh
.SH NAZWA
procps \- API do dostępu do informacji systemowych w systemie plików /proc
.SH SKŁADNIA
W niniejszym opisie jest reprezentowanych pięć różnych interfejsów,
nazwanych od plików służących do dostępu w pseudo systemie plików /proc:
\fBdiskstats\fP, \fBmeminfo\fP, \fBslabinfo\fP, \fBstat\fP oraz \fBvmstat\fP.
.nf
.RS +4
#include <libproc2/\fBinterfejs\fP.h>
int\fB procps_new \fP (struct info **\fIinfo\fP);
int\fB procps_ref \fP (struct info *\fIinfo\fP);
int\fB procps_unref\fP (struct info **\fIinfo\fP);
struct result *\fBprocps_get\fP (
struct info *\fIinfo\fP,
[ const char *\fIname\fP, ] tylko API \fBdiskstats\fP
enum item \fIitem\fP);
struct stack *\fBprocps_select\fP (
struct info *\fIinfo\fP,
[ const char *\fIname\fP, ] tylko API \fBdiskstats\fP
enum item *\fIitems\fP,
int \fInumitems\fP);
struct reaped *\fBprocps_reap\fP (
struct info *\fIinfo\fP,
[ enum reap_type \fIwhat\fP, ] tylko API \fBstat\fP
enum item *\fIitems\fP,
int \fInumitems\fP);
struct stack **\fBprocps_sort\fP (
struct info *\fIinfo\fP,
struct stack *\fIstacks\fP[],
int \fInumstacked\fP,
enum item \fIsortitem\fP,
enum sort_order \fIorder\fP);
.fi
Powyższe funkcje i struktury są ogólne, ale konkretne \fBinterfejsy\fP stają
się częścią identyfikatorów. Np. `procps_new' właściwie staje się
`procps_\fBmeminfo\fP_new', `info' staje się `\fBdiskstats\fP_info' itd.
Ten sam \fBinterfejs\fP jest używany w nazwie każdego pliku nagłówkowego z
dodanym rozszerzeniem `.h'.
Konsolidować z \fI\-lproc2\fP.
.SH OPIS
.SS Przegląd
Interfejsy te opierają się na prostej strukturze `result',
odzwierciedlającej element `item' wraz z jego wartością (w unii ze
standardowymi typami C jako składowymi). Wszystkie struktury `result' są
automatycznie przydzielane i dostarczane przez bibliotekę.
Podając tablicę elementów `item', struktury te mogą być zorganizowane w
"stos", potencjalnie zwracając wiele wyników w pojedynczym wywołaniu
funkcji. W ten sposób na "stos" można patrzeć jak na rekord zmiennej
długości, którego zawartość i porządek są określane wyłącznie przez
użytkownika.
Częścią każdego interfejsu jest para unikatowych enumeratorów. Elementy
`noop' i `extra' istnieją w celu trzymania wartości użytkownika. Nie są
nigdy ustawiane przez bibliotekę, ale wynik `extra' jest zerowany przy
każdej interakcji z biblioteką.
Plik nagłówkowy \fBinterfejsu\fP jest podstawowym dokumentem przy tworzeniu
programu użytkownika. Tam można zaleźć dostępne elementy, ich typ zwracany
(nazwę składowej struktury `result') oraz źródła tych wartości. Tam też są
udokumentowane dodatkowe enumeratory czy struktury.
.SS Użycie
Poniżej znajduje się typowa sekwencja wywołań tych intefejsów.
.nf
1. \fBprocps_new()\fP
2. \fBprocps_get()\fP, \fBprocps_select()\fP lub \fBprocps_reap()\fP
3. \fBprocps_unref()\fP
.fi
Funkcja \fBget\fP służy do odczytania struktury `result' dla pojedynczego
elementu `item'. Alternatywnie dostępne jest makro \fBGET\fP, kiedy istotna
jest tylko wartość zwracana.
Funkcja \fBselect\fP potrafi odczytać wiele struktur `result' z pojedynczego
"stosu".
Na potrzeby nieprzewidywalnych, zmiennych wyników, interfejsy \fBdiskstats\fP,
\fBslabinfo\fP oraz \fBstat\fP eksportują funkcję \fBreap\fP. Służy do odczytania
wielu "stosów", zawierających wiele struktur `result'. Opcjonalnie
użytkownik może zdecydować, aby wykonać \fBsort\fP tych wyników.
Aby wykorzystać dowolny "stos" i dostać się do poszczególnych struktur
`result', wymagana jest wartość \fIrelative_enum\fP, jak widać w makrze \fBVAL\fP
zdefiniowanym w pliku nagłówkowym. Takie wartości mogą być sztywno
zakodowane od 0 do numitems\-1. Zwykle jednak tę potrzebę zaspokaja się
tworząc własne enumeratory odpowiadające kolejności tablicy `items'.
.SS Zastrzeżenia
Funkcje \fBnew\fP, \fBref\fP, \fBunref\fP, \fBget\fP oraz \fBselect\fP są dostępne we
wszystkich pięciu interfejsach.
W przypadku funkcji \fBnew\fP i \fBunref\fP, trzeba przekazać adres wskaźnika do
struktury \fIinfo\fP. W przypadku \fBnew\fP musi być zainicjowany na NULL. W
przypadku \fBunref\fP zostanie ustawiony na NULL, jeśli licznik odwołań
osiągnie zero.
W przypadku interfejsu \fBdiskstats\fP, parametr \fIname\fP funkcji \fBget\fP i
\fBselect\fP określa nazwę dysku lub partycji
W przypadku interfejsu \fBstat\fP, parametr \fIwhat\fP funkcji \fBreap\fP określa,
czy zebrane mają być dane tylko dla CPU, czy dla CPU oraz NUMA.
Przy używaniu funkcji \fBsort\fP, parametry \fIstacks\fP i \fInumstacked\fP są zwykle
zwracame w strukturze `reaped'.
.SH "WARTOŚĆ ZWRACANA"
.SS "Funkcje zwracające `int'"
Błąd jest oznaczany poprzez liczbę ujemną, będącą liczbą przeciwną do znanej
wartości errno.h.
Sukces jest oznaczany wartością zerową. Jednak funkcje \fBref\fP i \fBunref\fP
zwracają bieżący licznik odwołań struktury \fIinfo\fP.
.SS "Funkcje zwracające adres"
Błąd jest oznaczany zwracanym wskaźnikiem NULL, a powód można znaleźć w
wartości errno.
Sukces jest oznaczany wskaźnikiem na nazwaną strukturę.
.SH DIAGNOSTYKA
Aby pomóc przy rozwijaniu programów, jest udogodnienie pozwalające zapewnić,
że odwołania do składowej `result' zgadzają się z oczekiwaniami
biblioteki. Zakłada, że do dostępu do wartości `result' jest używane makro
udostępnione w pliku nagłówkowym.
Tę opcję można włączyć w jeden z poniższych sposobów, a wszystkie
niezgodności będą wypisane na \fBstderr\fP.
.IP 1) 3
Dodanie CFLAGS='\-DXTRA_PROCPS_DEBUG' do pozostałych użytych opcji
\&./configure.
.IP 2) 3
Dodanie #include <procps/xtra\-procps\-debug.h> do dowolnego programu
\fIpo\fP nagłówkach nazwanych interfejsów.
.PP
Ta opcja weryfikacji dodaje istotny narzut. W związku z tym ważne jest, żeby
\fInie\fP była włączona w binariach produkcyjnych.
.SH "ZOBACZ TAKŻE"
\fBprocps_misc\fP(3), \fBprocps_pids\fP(3), \fBproc\fP(5).
|
