Provided by: manpages-fr-dev_3.57d1p1-1_all 
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 sur-ensemble 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.57 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)