GETUTENT(3)

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);

void utmpname(const char *file);

OPIS
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.

getutid() przeszukuje plik w przód, zaczynając od bieżącej pozycji, biorąc poduwagę 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 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 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(), getutline() i pututline() zwracają wskaźnik do struct utmp, jeśli zakończą się powodzeniem, lub NULL w razie wystąpienia błędu. Ta struct utmp jest zaalokowana w statycznej przestrzeni danych i może zostać nadpisana przez kolejne wywołania funkcji.

WERSJE BEZPIECZNE DLA WĄTKÓW
Powyższe funkcje nie są bezpieczne dla wątków. Glibc dodaje wersje wielobieżne:

#define _GNU_SOURCE /* lub _SVID_SOURCE, lub _BSD_SOURCE */
#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, do którego te funkcje powinny zwrócić 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.

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() i ttyname().

#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(0)+strlen("/dev/"));
  /* poprawne tylko dla terminali nazwanych /dev/tty[pqr][0-9a-z] */
  strcpy(entry.ut_id,ttyname(0)+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();
  return 0;
}

PLIKI
/var/run/utmp    baza danych obecnie zalogowanych użytkowników
/var/log/wtmp    baza danych poprzednich logowań użytkowników

ZGODNE Z
XPG 2, SVID 2, Linux FSSTND 1.2

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 1003.1-2001, naśladując XPG4.2, 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);

Struktura utmpx jest rozszerzeniem struktury utmp o dodatkowe pola i o większe wersje istniejących pól. Odpowiadającymi plikami są często /var/*/utmpx oraz /var/*/wtmpx.

Z drugiej strony linuksowe glibc nie używa utmpx, ponieważ jego struktura utmp jest już wystarczjąco duża. Funkcje getutxent itp. są aliasami funkcji getutent itp.

ZOBACZ TAKŻE
utmp(5)