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(struct utmp *ut);
struct utmp *getutline(struct utmp *ut);
struct utmp *pututline(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.
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, Linux
libc5). HPUX wprowadza nową funkcję
_pututline() o prototypie
podanym powyżej dla
pututline() (funkcja ta znajduje się
również w libc5 Linuksa).
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ż wystarczjąco
duża. Funkcje
getutxent itp. są aliasami funkcji
getutent itp.
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.40 projektu Linux
man-pages. Opis projektu oraz informacje dotyczące zgłaszania
błędów można znaleźć pod adresem
http://www.kernel.org/doc/man-pages/.
TŁUMACZENIE¶
Autorem polskiego tłumaczenia niniejszej strony podręcznika man jest
Robert Luberda <robert@debian.org>.
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.40 oryginału.
