getutline

GETUTENT(3)                Linux-Programmierhandbuch               GETUTENT(3)



BEZEICHNUNG
       getutent, getutid, getutline, pututline, setutent, endutent, utmpname -
       auf Einträge der utmp-Datei zugreifen

ÃBERSICHT
       #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);

BESCHREIBUNG
       Neue Applikationen sollten die in POSIX.1 spezifizierten
       »utmpx«-Versionen dieser Funktionen verwenden, siehe KONFORM ZU.

       utmpname() setzt den Namen der Datei im utmp-Format, auf die die
       anderen utmp-Funktionen zugreifen. Wenn utmpname() nicht benutzt wird,
       um den Dateinamen zu setzen bevor die anderen Funktionen benutzt
       werden, wird von diesen _PATH_UTMP angenommen, wie in <paths.h>
       definiert.

       setutent() setzt den Dateizeiger auf den Anfang der Datei utmp zurück.
       Im Allgemeinen ist es sinnvoll, dies vor Verwendung der anderen
       Funktionen aufzurufen.

       endutent() schlieÃt die Datei utmp. Sie sollte aufgerufen werden, wenn
       die Verwendung der anderen Funktionen im Benutzercode beendet ist.

       getutent() liest eine Zeile ab der aktuellen Dateiposition in der Datei
       utmp. Es wird ein Zeiger auf eine Struktur zurückgegeben, welche die
       Felder der Zeile enthält. Die Definition dieser Struktur ist in
       utmp(5) aufgeschlüsselt.

       getutid() sucht ab der aktuellen Dateiposition in der Datei utmp
       vorwärts, basierend auf ut. Wenn ut->ut_type gleich RUN_LVL,
       BOOT_TIME, NEW_TIME oder OLD_TIME ist, findet getutid() den ersten
       Eintrag, dessen Feld ut_type ut->ut_type entspricht. Wenn ut->ut_type
       gleich INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS oder DEAD_PROCESS ist,
       findet getutid() den ersten Eintrag, dessen Feld ut_id ut->ut_id
       entspricht.

       getutline() sucht ab der aktuellen Dateiposition in der Datei utmp
       vorwärts. Die Funktion überprüft Einträge, deren Feld ut_type
       gleich USER_PROCESS oder LOGIN_PROCESS ist und gibt den ersten Eintrag
       zurück, dessen Feld ut_line ut->ut_line entspricht.

       pututline() schreibt die utmp-Struktur ut in die Datei utmp. Die
       Funktion benutzt getutid(), um den geeigneten Platz in der Datei für
       das Einfügen des neuen Eintrags zu finden. Wenn kein geeigneter Platz
       für ut gefunden werden kann, hängt pututline() den neuen Eintrag am
       Ende der Datei an.

RÃCKGABEWERT
       getutent(), getutid() und getutline() liefern bei Erfolg einen Zeiger
       auf eine struct utmp-Struktur zurück und NULL bei Fehlern (dies
       schlieÃt den Fall ein, dass ein Eintrag nicht gefunden wird, »record
       not found«). Die Struktur struct utmp wird als statischer Speicher
       alloziert und kann von nachfolgenden Aufrufen überschrieben werden.

       Bei Erfolg gibt pututline() ut zurück; bei Fehlern gibt die Funktion
       NULL zurück.

       Wenn der Name erfolgreich gespeichert wurde, gibt utmpname() 0 zurück,
       bei Fehlern -1.

       Im Fehlerfall setzen diese Funktionen errno, um die Ursache anzuzeigen.

FEHLER
       ENOMEM Speicher aufgebraucht.

       ESRCH  Eintrag nicht gefunden.

       setutent(), pututline() und die getut*()-Funktionen können aus den
       gleichen Gründen fehlschlagen wie in open(2) beschrieben.

DATEIEN
       /var/run/utmp
              Datenbank aktuell angemeldeter Benutzer

       /var/log/wtmp
              Datenbank früherer Benutzeranmeldungen

ATTRIBUTE
       Siehe attributes(7) für eine Erläuterung der in diesem Abschnitt
       verwandten Ausdrücke.

       ┌──────────────┬────────────────────────┬──────────────────────────────┐
       │Schnittstelle Attribut               Wert                         │
       ├──────────────┼────────────────────────┼──────────────────────────────┤
       │getutent()    │ Multithread-Fähigkeit │ MT-Unsafe init race:utent    │
       │              │                        │ race:utentbuf sig:ALRM timer │
       ├──────────────┼────────────────────────┼──────────────────────────────┤
       │getutid(),    │ Multithread-Fähigkeit │ MT-Unsafe init race:utent    │
       │getutline()   │                        │ sig:ALRM timer               │
       ├──────────────┼────────────────────────┼──────────────────────────────┤
       │pututline()   │ Multithread-Fähigkeit │ MT-Unsafe race:utent         │
       │              │                        │ sig:ALRM timer               │
       ├──────────────┼────────────────────────┼──────────────────────────────┤
       │setutent(),   │ Multithread-Fähigkeit │ MT-Unsafe race:utent         │
       │endutent(),   │                        │                              │
       │utmpname()    │                        │                              │
       └──────────────┴────────────────────────┴──────────────────────────────┘
       In der obigen Tabelle bedeutet utent in race:utent, dass, falls eine
       der Funktionen setutent(), getutent(), getutid(), getutline(),
       pututline(), utmpname() oder endutent() in verschiedenen Threads eines
       Programms parallel verwandt werden, konkurrierende Zugriffe auf Daten
       (»data races«) auftreten könnten.

KONFORM ZU
       XPG2, SVr4.

       In XPG2 und SVID 2 ist dokumentiert, dass die Funktion pututline() void
       zurückgibt und das tut sie auch auf vielen Systemen (AIX, HP-UX).
       HP-UX führt eine neue Funktion _pututline() mit dem oben angegebenen
       Prototyp für pututline() ein.

       Alle diese Funktionen sind jetzt auf Nicht-Linux-Systemen überholt.
       POSIX.1-2001 und POSIX.1-2008 folgt SUSv1 und erwähnt keine dieser
       Funktionen, sondern nutzt

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

       Diese Funktionen werden von der Glibc bereitgestellt und erledigen die
       gleiche Aufgabe wie ihre Ãquivalente ohne das »x«, aber verwenden
       struct utmpx, welche unter Linux als das Gleiche wie struct utmp
       definiert ist. Der Vollständigkeit wegen stellt Glibc auch utmpxname()
       bereit, obwohl diese Funktion nicht von POSIX.1 beschrieben wird.

       Auf manchen anderen Systemen ist die utmpx-Struktur eine Obermenge der
       utmp-Struktur mit zusätzlichen Feldern und gröÃeren Versionen der
       vorhandenen Felder. Zudem werden auch parallele Dateien unterstützt,
       oft /var/*/utmpx und /var/*/wtmpx.

       Die Linux-Glibc auf der anderen Seite verwendet keine parallele
       utmpx-Datei, weil ihre utmp-Struktur schon groà genug ist. Die oben
       aufgeführten »x«-Funktionen sind nur Aliase für ihre Gegenstücke
       ohne »x« (z. B. ist getutxent() ein Alias für getutent()).

ANMERKUNGEN
   Anmerkungen zur Glibc
       Die oben erwähnten Funktionen sind nicht multithread-fähig. Glibc
       fügt ablaufinvariante Versionen hinzu.

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

       Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):

       getutent_r(), getutid_r(), getutline_r():
           _GNU_SOURCE
           || /* seit Glibc 2.19: */ _DEFAULT_SOURCE
           || /* Glibc <= 2.19: */    _SVID_SOURCE || _BSD_SOURCE

       Diese Funktionen sind GNU-Erweiterungen, Gegenstücke der Funktionen
       gleichen Namens ohne den Suffix _r. Das Argument ubuf gibt diesen
       Funktionen einen Ort für die Speicherung ihrer Ergebnisse. Bei Erfolg
       geben Sie 0 zurück und schreiben einen Zeiger auf das Ergebnis in *
       ubufp. Tritt ein Fehler auf, geben diese Funktionen -1 zurück. Es gibt
       keine utmpx-Ãquivalente dieser Funktionen. (POSIX.1 beschreibt diese
       Funktionen nicht.)

BEISPIEL
       Das folgende Beispiel erstellt und entfernt einen umtp-Datensatz. Es
       wird angenommen, dass es in einem Pseudo-Terminal läuft. Zur
       Verwendung in einer realen Anwendung sollten Sie die Rückgabewerte von
       getpwuid(3) und ttyname(3) prüfen.

       #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 vor dem Hinzufügen des Eintrags:;who");

           entry.ut_type = USER_PROCESS;
           entry.ut_pid = getpid();
           strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
           /* stimmt nur für ptys namens /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 nach dem Hinzufügen des Eintrags:;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 nach dem Entfernen des Eintrags:;who");

           endutent();
           exit(EXIT_SUCCESS);
       }

SIEHE AUCH
       getutmp(3), utmp(5)

KOLOPHON
       Diese Seite ist Teil der Veröffentlichung 5.01 des Projekts
       Linux-man-pages. Eine Beschreibung des Projekts, Informationen, wie
       Fehler gemeldet werden können sowie die aktuelle Version dieser Seite
       finden sich unter https://www.kernel.org/doc/man-pages/.


ÃBERSETZUNG
       Die deutsche Ãbersetzung dieser Handbuchseite wurde von Martin Eberhard
       Schauer <Martin.E.Schauer@gmx.de>, Mario Blättermann
       <mario.blaettermann@gmail.com> und Dr. Tobias Quathamer
       <toddy@debian.org> erstellt.

       Diese Ãbersetzung ist Freie Dokumentation; lesen Sie die GNU General
       Public License Version 3 oder neuer bezüglich der Copyright-
       Bedingungen. Es wird KEINE HAFTUNG übernommen.

       Wenn Sie Fehler in der Ãbersetzung dieser Handbuchseite finden,
       schicken Sie bitte eine E-Mail an <debian-l10n-
       german@lists.debian.org>.



                              15. September 2017                   GETUTENT(3)