getutent(3)

1GETUTENT(3)                    Library functions                   GETUTENT(3)
2
3
4

NAME

6       getutent, getutid, getutline, pututline, setutent, endutent, utmpname -
7       access utmp file entries
8

SYNOPSIS

10       #include <utmp.h>
11
12       struct utmp *getutent(void);
13       struct utmp *getutid(struct utmp *ut);
14       struct utmp *getutline(struct utmp *ut);
15
16       struct utmp *pututline(struct utmp *ut);
17
18       void setutent(void);
19       void endutent(void);
20
21       void utmpname(const char *file);
22

DESCRIPTION

24       utmpname() sets the name of the utmp-format file  for  the  other  utmp
25       functions  to  access.   If  utmpname() is not used to set the filename
26       before the other functions are used, they assume _PATH_UTMP, as defined
27       in <paths.h>.
28
29       setutent()  rewinds the file pointer to the beginning of the utmp file.
30       It is generally a Good Idea to call it before any of  the  other  func‐
31       tions.
32
33       endutent()  closes  the  utmp  file.  It should be called when the user
34       code is done accessing the file with the other functions.
35
36       getutent() reads a line from the current  file  position  in  the  utmp
37       file.  It returns a pointer to a structure containing the fields of the
38       line.
39
40       getutid() searches forward from the current file position in  the  utmp
41       file  based  upon  ut.   If  ut->ut_type  is one of RUN_LVL, BOOT_TIME,
42       NEW_TIME, or OLD_TIME,  getutid()  will  find  the  first  entry  whose
43       ut_type   field   matches   ut->ut_type.   If  ut->ut_type  is  one  of
44       INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or  DEAD_PROCESS,  getutid()
45       will find the first entry whose ut_id field matches ut->ut_id.
46
47       getutline() searches forward from the current file position in the utmp
48       file.  It scans entries whose ut_type is USER_PROCESS or  LOGIN_PROCESS
49       and returns the first one whose ut_line field matches ut->ut_line.
50
51       pututline()  writes  the utmp structure ut into the utmp file.  It uses
52       getutid() to search for the proper place in the file to insert the  new
53       entry.   If it cannot find an appropriate slot for ut, pututline() will
54       append the new entry to the end of the file.
55

RETURN VALUE

57       getutent(), getutid(), getutline() and pututline() return a pointer  to
58       a  struct  utmp  on  success, and NULL on failure.  This struct utmp is
59       allocated in static storage,  and  may  be  overwritten  by  subsequent
60       calls.
61

REENTRANT VERSIONS

63       These  above  functions  are not thread-safe. Glibc adds reentrant ver‐
64       sions
65
66       #define _GNU_SOURCE    /* or _SVID_SOURCE or _BSD_SOURCE */
67       #include <utmp.h>
68
69       int getutent_r(struct utmp *ubuf, struct utmp **ubufp);
70
71       int getutid_r(struct utmp *ut,
72                     struct utmp *ubuf, struct utmp **ubufp);
73
74       int getutline_r(struct utmp *ut,
75                       struct utmp *ubuf, struct utmp **ubufp);
76
77       These functions are GNU extensions, analogs of  the  functions  of  the
78       same  name  without the _r suffix. The ubuf parameter gives these func‐
79       tions a place to store their result.  On success they return 0,  and  a
80       pointer  to  the result is written in *ubufp.  On error these functions
81       return -1.
82

EXAMPLE

84       The following example adds and removes a utmp record,  assuming  it  is
85       run  from  within  a pseudo terminal.  For usage in a real application,
86       you should check the return values of getpwuid() and ttyname().
87
88       #include <string.h>
89       #include <stdlib.h>
90       #include <pwd.h>
91       #include <unistd.h>
92       #include <utmp.h>
93
94       int main(int argc, char *argv[])
95       {
96         struct utmp entry;
97
98         system("echo before adding entry:;who");
99
100         entry.ut_type=USER_PROCESS;
101         entry.ut_pid=getpid();
102         strcpy(entry.ut_line,ttyname(0)+strlen("/dev/"));
103         /* only correct for ptys named /dev/tty[pqr][0-9a-z] */
104         strcpy(entry.ut_id,ttyname(0)+strlen("/dev/tty"));
105         time(&entry.ut_time);
106         strcpy(entry.ut_user,getpwuid(getuid())->pw_name);
107         memset(entry.ut_host,0,UT_HOSTSIZE);
108         entry.ut_addr=0;
109         setutent();
110         pututline(&entry);
111
112         system("echo after adding entry:;who");
113
114         entry.ut_type=DEAD_PROCESS;
115         memset(entry.ut_line,0,UT_LINESIZE);
116         entry.ut_time=0;
117         memset(entry.ut_user,0,UT_NAMESIZE);
118         setutent();
119         pututline(&entry);
120
121         system("echo after removing entry:;who");
122
123         endutent();
124         return 0;
125       }
126

FILES

128       /var/run/utmp  database of currently logged-in users
129       /var/log/wtmp  database of past user logins
130

CONFORMING TO

132       XPG2, SVr4.
133
134       In XPG2 and SVID 2 the function pututline()  is  documented  to  return
135       void,  and  that  is  what  it  does on many systems (AIX, HP-UX, Linux
136       libc5).  HP-UX introduces a new function _pututline() with  the  proto‐
137       type given above for pututline() (also found in Linux libc5).
138
139       All   these   functions   are   obsolete   now  on  non-Linux  systems.
140       POSIX.1-2001, following SUSv1, does not have any  of  these  functions,
141       but instead uses
142
143       #include <utmpx.h>
144
145       struct utmpx *getutxent(void);
146       struct utmpx *getutxid(const struct utmpx *);
147       struct utmpx *getutxline(const struct utmpx *);
148       struct utmpx *pututxline(const struct utmpx *);
149       void setutxent(void);
150       void endutxent(void);
151
152       The  utmpx  structure  is  a superset of the utmp structure, with addi‐
153       tional fields, and larger versions of the existing fields.  The  corre‐
154       sponding files are often /var/*/utmpx and /var/*/wtmpx.
155
156       Linux  glibc on the other hand does not use utmpx since its utmp struc‐
157       ture is already large enough. The functions getutxent etc. are  aliases
158       for getutent etc.
159