.\" .\" Copyright (c) 2020-2023 Jim Warner .\" Copyright (c) 2020-2023 Craig Small .\" .\" 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 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 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).