Provided by: manpages-pl-dev_0.6-2_all 
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.
2014-08-19 GETUTENT(3)