getutline

GETUTENT(3)               Manuel du programmeur Linux              GETUTENT(3)



NOM
       getutent, getutid, getutline, pututline, setutent, endutent, utmpname -
       Accéder aux enregistrements utmp

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

DESCRIPTION
       Les nouvelles applications devraient utiliser les versions « utmpx »
       spécifiées par POSIX.1 de ces fonctions ; voir CONFORMITÃ.

       utmpname() indique le nom du fichier au format utmp à utiliser avec
       les autres fonctions. Si utmpname() n'est pas appelé avant les autres
       fonctions, elles utiliseront le fichier _PATH_UTMP, défini dans
       <paths.h>.

       setutent() ramène le pointeur au début du fichier utmp. Il est
       généralement conseillé d'appeler cette fonction au début du
       programme.

       endutent() ferme le fichier utmp. Ceci devrait être appelé une fois
       que le programme a terminé ses accès au fichier.

       getutent() lit une ligne du fichier utmp, Ã  la position courante. Elle
       renvoie un pointeur sur une structure contenant les divers champs de la
       ligne. La définition de cette structure peut être consultée dans
       utmp(5).

       getutid() effectue une recherche dans le fichier utmp, Ã  partir de la
       position courante, en se basant sur ut. Si ut->ut_type vaut RUN_LVL,
       BOOT_TIME, NEW_TIME, ou OLD_TIME, getutid() recherchera le premier
       enregistrement dont le champ ut_type correspond à ut->ut_type. Si
       ut->ut_type vaut INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, ou
       DEAD_PROCESS, getutid() recherchera le premier enregistrement dont le
       champ ut_id correspond à ut->ut_id.

       getutline() effectue une recherche dans le fichier utmp, Ã  partir de
       la position courante. Elle examine les enregistrements dont le champ
       ut_type est USER_PROCESS ou LOGIN_PROCESS et renvoie le premier dont le
       champ ut_line correspond à ut->ut_line.

       pututline() écrit la structure utmp ut dans le fichier utmp. Elle
       utilise getutid() pour rechercher l'emplacement ou insérer le nouvel
       enregistrement. Si elle ne trouve pas d'emplacement approprié pour ut,
       pututline() ajoutera le nouvel enregistrement à la fin du fichier.

VALEUR RENVOYÃE
       getutent(), getutid() et getutline() renvoient un pointeur sur une
       structure utmp, ou NULL en cas d'erreur (ce qui inclut le cas « pas
       d'enregistrement trouvé »). Cette structure utmp est allouée
       statiquement, et peut être écrasée par des appels successifs.

       Si elle réussit, pututline() renvoie ut ; si elle échoue, elle
       renvoie NULL.

       utmpname() renvoie 0 si le nouveau nom a été correctement
       enregistré, ou -1 si elle échoue.

       En cas d'échec, ces fonctions renseignent le code d'erreur dans errno.

ERREURS
       ENOMEM Plus de mémoire disponible.

       ESRCH  Enregistrement non trouvé.

       setutent(), pututline() et les fonctions getut*() peuvent également
       échouer pour les raisons décrites dans open(2).

FICHIERS
       /var/run/utmp - Base de données des utilisateurs connectés.
       /var/log/wtmp - Base de données des connexions passées.

CONFORMITÃ
       XPG2, SVr4.

       Dans XPG2 et SVID 2, la fonction pututline() est décrite comme
       renvoyant « void », et c'est le cas sur de nombreux systèmes (AIX,
       HP-UX, Linux libc5). HP-UX introduit une nouvelle fonction _pututline()
       avec le prototype fourni plus haut pour pututline() (existe aussi dans
       la libc5 de Linux).

       Toutes ces fonctions sont maintenant obsolètes sur les systèmes non
       Linux. POSIX.1-2001, suivant SUSv1, ne propose aucune de ces fonctions,
       mais utilise plutôt

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

       Ces fonctions sont fournies par la glibc et effectuent les mêmes
       tâches que leurs équivalents sans le « x » mais utilisent une
       structure utmpx, définie sous Linux pour être identique à la
       structure utmp. Pour être complet, la glibc fournit également
       utmpxname(), bien que cette fonction ne soit pas spécifiée par
       POSIX.1.

       Sur quelques autres systèmes, la structure utmpx est un surensemble de
       la structure utmp, avec des champs supplémentaires, et des versions
       plus grandes des champs existants, et des fichiers sont maintenus en
       parallèle, souvent /var/*/utmpx et /var/*/wtmpx.

       D'un autre côté, la glibc sous Linux n'utilise pas de fichier utmpx
       en parallèle car sa structure utmp est déjà assez grande. Les
       fonctions contenant un « x » listées ci-dessus sont simplement des
       alias des fonctions sans le « x » (par exemple, getutxent() est un
       alias de getutent()).

NOTES
   Notes sur la glibc
       Les fonctions ci-dessus ne sont pas sûres dans un contexte de thread.
       La glibc ajoute les versions réentrantes.

       #define _GNU_SOURCE    /* ou _SVID_SOURCE ou _BSD_SOURCE;
                                 consultez 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);

       Ces fonctions sont des extensions GNU, analogues aux fonctions de même
       nom sans le suffixe « _r ». Le paramètre ubuf fournit à ces
       fonctions un endroit où stocker leur résultat. Si elles réussissent
       elles renvoient 0 et un pointeur vers le résultat dans *ubufp. Si
       elles échouent, ces fonctions renvoient -1. Il n'y a pas d'équivalent
       « utmpx » aux fonctions ci-dessus. (POSIX.1 ne spécifie pas de
       telles fonctions.)

EXEMPLE
       L'exemple suivant ajoute et retire un enregistrement utmp, en supposant
       qu'il est invoqué depuis un pseudoterminal. Dans une véritable
       application, il faudrait vérifier les valeurs renvoyées par
       getpwuid(3) et 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 before adding entry:;who");

           entry.ut_type = USER_PROCESS;
           entry.ut_pid = getpid();
           strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
           /* only correct for ptys named /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 after adding entry:;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 after removing entry:;who");

           endutent();
           exit(EXIT_SUCCESS);
       }

VOIR AUSSI
       getutmp(3), utmp(5)

COLOPHON
       Cette page fait partie de la publication 3.65 du projet man-pages
       Linux. Une description du projet et des instructions pour signaler des
       anomalies peuvent être trouvées à l'adresse
       http://www.kernel.org/doc/man-pages/.

TRADUCTION
       Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a
       <http://po4a.alioth.debian.org/> par l'équipe de traduction
       francophone au sein du projet perkamon
       <http://perkamon.alioth.debian.org/>.

       Christophe Blaess <http://www.blaess.fr/christophe/> (1996-2003), Alain
       Portal <http://manpagesfr.free.fr/> (2003-2006).  Florentin Duneau et
       l'équipe francophone de traduction de Debian (2006-2009).

       Veuillez signaler toute erreur de traduction en écrivant Ã
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous pouvez toujours avoir accès à la version anglaise de ce document
       en utilisant la commande « man -L C <section> <page_de_man> ».



                                 19 avril 2013                     GETUTENT(3)