NAZWA¶
getutent, getutid, getutline, pututline, setutent, endutent, utmpname -
dostęp do wpisów pliku utmp
SKŁADNIA¶
#include <utmp.h>
struct utmp *getutent(void);
struct utmp *getutid(const struct utmp *ut);
struct utmp *getutline(const struct utmp *ut);
struct utmp *pututline(const struct utmp *ut);
void setutent(void);
void endutent(void);
int utmpname(const char *file);
OPIS¶
Nowe aplikacje powinny używać podanych w standardzie POSIX.1
wersji "utmpx" tych funkcji, patrz rozdział "ZGODNE
Z" poniżej.
utmpname() ustawia nazwę pliku w formacie utmp, który
będzie używany przez pozostałe funkcje utmp.
Jeżeli nie użyto
utmpname() przed wywołaniem
innych funkcji, to używają one domyślnej nazwy
_PATH_UTMP, zdefiniowanej w
<paths.h>.
setutent() przesuwa wskaźnik pliku z powrotem na początek
pliku utmp. Funkcja ta powinna zostać wywołana przed
wywołaniem którejkolwiek z pozostałych funkcji.
endutent() zamyka plik utmp. Powinna być wywołana, gdy
program już zakończył używanie tego pliku przy
pomocy innych funkcji.
getutent() odczytuje linię z pliku utmp, zaczynając od
bieżącej pozycji w tym pliku. Zwraca wskaźnik do
struktury zawierającej pola linii. Definicję tej struktury
opisano w
utmp(5).
getutid() przeszukuje plik w przód, zaczynając od
bieżącej pozycji, biorąc pod uwagę parametr
ut. Jeżeli
ut->ut_type jest jednym z
RUN_LVL,
BOOT_TIME,
NEW_TIME lub
OLD_TIME, to
getutid()
wyszuka pierwszy rekord, którego pole
ut_type odpowiada
ut->ut_type. Jeżeli
ut->ut_type jest jednym z
INIT_PROCESS,
LOGIN_PROCESS,
USER_PROCESS lub
DEAD_PROCESS, to
getutid() wyszuka pierwszy wpis, którego
pole
ut_id pasuje do
ut->ut_id.
getutline() przeszukuje plik utmp w przód, zaczynając od
bieżącej pozycji w pliku. Sprawdza wpisy, których
ut_type jest równe
USER_PROCESS lub
LOGIN_PROCESS,
i zwraca pierwszy z nich, którego pole
ut_line odpowiada
ut->ut_line.
pututline() zapisuje strukturę
ut, której typem jest
utmp, do pliku utmp. Używa
getutid(), aby
znaleźć odpowiednie miejsce do dodania nowego rekordu.
Jeśli go nie znajdzie, to
pututline() doda nowy wpis na
końcu pliku.
WARTOŚĆ ZWRACANA¶
Funkcje
getutent(),
getutid() i
getutline() zwracają
wskaźnik do
struct utmp, jeśli zakończą
się powodzeniem, lub NULL w razie wystąpienia
błędu.
struct utmp jest zaalokowana w statycznej
przestrzeni danych i może zostać nadpisana przez kolejne
wywołania funkcji.
Funkcja
pututline() zwraca
ut, jeśli zakończy
się powodzeniem, lub NULL w razie wystąpienia
błędu.
utmpname() zwraca 0, jeśli zachowano nową nazwę, lub
-1 w przypadku błędu.
W razie wystąpienia błędu ustawiana jest zmienna
errno aby wskazać przyczynę.
BŁĘDY¶
- ENOMEM
- Brak pamięci.
- ESRCH
- Nie znaleziono rekordu.
Funkcje
setutent(),
pututline() i
getut*() mogą
także zwrócić błędy opisane w
open(2).
PLIKI¶
/var/run/utmp baza danych obecnie zalogowanych użytkowników
/var/log/wtmp baza danych poprzednich logowań użytkowników
ZGODNE Z¶
XPG2, SVr4.
W dokumentacji XPG2 i SVID2 funkcja
pututline() zwraca void, i to jest
to, co ona rzeczywiście zwraca na wielu systemach (AIX, HPUX). HPUX
wprowadza nową funkcję
_pututline() o prototypie podanym
powyżej dla
pututline().
Wszystkie te funkcje są przestarzałe na systemach nielinuksowych.
POSIX.1-2001, naśladując SUSv1, nie zawiera żadnej z tych
funkcji, ale zamiast nich używa
#include <utmpx.h>
struct utmpx *getutxent(void);
struct utmpx *getutxid(const struct utmpx *);
struct utmpx *getutxline(const struct utmpx *);
struct utmpx *pututxline(const struct utmpx *);
void setutxent(void);
void endutxent(void);
Powyższe funkcje są dostarczane przez glibc i wykonują
dokładnie te same zadania, co ich odpowiedniki bez przyrostka
"x", tyle że używają struktury
struct
utmpx, zdefiniowanej pod Linuksem dokładnie tak samo jak
struct utmp. glibc dostarcza także
utmpxname(),
chociaż POSIX.1 nie zawiera tej funkcji.
Na niektórych systemach struktura
utmpx jest rozszerzeniem
struktury
utmp o dodatkowe pola i o większe wersje
istniejących pól. Utrzymywane są tam
równoległe wersje plików, często jako
/var/*/utmpx oraz
/var/*/wtmpx.
Z drugiej strony linuksowe glibc nie używa pliku
utmpx,
ponieważ jego struktura
utmp jest już
wystarczająco duża. Funkcje "x" opisane powyżej
są aliasami do funkcji bez "x" (np.
getutxent jest
aliasem
getutent()).
UWAGI¶
Uwagi dotyczące biblioteki glibc¶
Powyższe funkcje nie są bezpieczne dla wątków. Glibc
dodaje wersje współbieżne:
#define _GNU_SOURCE /* lub _SVID_SOURCE, lub _BSD_SOURCE;
patrz feature_test_macros(7) */
#include <utmp.h>
int getutent_r(struct utmp *ubuf, struct utmp **ubufp);
int getutid_r(struct utmp *ut,
struct utmp *ubuf, struct utmp **ubufp);
int getutline_r(struct utmp *ut,
struct utmp *ubuf, struct utmp **ubufp);
Te funkcje są rozszerzeniami GNU, analogicznymi do funkcji o tych samych
nazwach, ale bez przyrostka "_r". Parametr
ubuf
określa miejsce, w którym te funkcje powinny zapisać
wynik. Jeśli zakończą się powodzeniem, to
zwracają 0, a wskaźnik do wyniku jest zapisywany w
*ubufp. W razie błędu funkcje zwracają -1. Funkcje
te nie mają swoich odpowiedników utmpx (POSIX.1 ich nie
zawiera).
PRZYKŁAD¶
Następujący przykład dodaje i usuwa rekord utmp, przy
założeniu, że zostanie uruchomiony z pseudoterminalu.
Użycie w rzeczywistej aplikacji wymagałoby sprawdzenia
wartości zwracanych przez
getpwuid(3) i
ttyname(3).
#include <string.h>
#include <stdlib.h>
#include <pwd.h>
#include <unistd.h>
#include <utmp.h>
int
main(int argc, char *argv[])
{
struct utmp entry;
system("echo przed dodaniem wpisu:;who");
entry.ut_type = USER_PROCESS;
entry.ut_pid = getpid();
strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
/* poprawne tylko dla pseudoterminali nazwanych /dev/tty[pqr][0-9a-z] */
strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
time(&entry.ut_time);
strcpy(entry.ut_user, getpwuid(getuid())->pw_name);
memset(entry.ut_host, 0, UT_HOSTSIZE);
entry.ut_addr = 0;
setutent();
pututline(&entry);
system("echo po dodaniu wpisu:;who");
entry.ut_type = DEAD_PROCESS;
memset(entry.ut_line, 0, UT_LINESIZE);
entry.ut_time = 0;
memset(entry.ut_user, 0, UT_NAMESIZE);
setutent();
pututline(&entry);
system("echo po usunięciu wpisu:;who");
endutent();
exit(EXIT_SUCCESS);
}
ZOBACZ TAKŻE¶
getutmp(3),
utmp(5)
O STRONIE¶
Angielska wersja tej strony pochodzi z wydania 3.71 projektu Linux
man-pages. Opis projektu, informacje dotyczące zgłaszania
błędów, oraz najnowszą wersję
oryginału można znaleźć pod adresem
http://www.kernel.org/doc/man-pages/.
TŁUMACZENIE¶
Autorami polskiego tłumaczenia niniejszej strony podręcznika man
są: Robert Luberda <robert@debian.org> i Michał
Kułach <michal.kulach@gmail.com>.
Polskie tłumaczenie jest częścią projektu
manpages-pl; uwagi, pomoc, zgłaszanie błędów na
stronie
http://sourceforge.net/projects/manpages-pl/. Jest zgodne z
wersją
3.71 oryginału.