1getutxent(3C)            Standard C Library Functions            getutxent(3C)
2
3
4

NAME

6       getutxent, getutxid, getutxline, pututxline, setutxent, endutxent, utm‐
7       pxname, getutmp, getutmpx, updwtmp, updwtmpx - user accounting database
8       functions
9

SYNOPSIS

11       #include <utmpx.h>
12
13       struct utmpx *getutxent(void);
14
15
16       struct utmpx *getutxid(const struct utmpx *id);
17
18
19       struct utmpx *getutxline(const struct utmpx *line);
20
21
22       struct utmpx *pututxline(const struct utmpx *utmpx);
23
24
25       void setutxent(void);
26
27
28       void endutxent(void);
29
30
31       int utmpxname(const char *file);
32
33
34       void getutmp(struct utmpx *utmpx, struct utmp *utmp);
35
36
37       void getutmpx(struct utmp *utmp, struct utmpx *utmpx);
38
39
40       void updwtmp(char *wfile, struct utmp *utmp);
41
42
43       void updwtmpx(char *wfilex, struct utmpx *utmpx);
44
45

DESCRIPTION

47       These  functions  provide access to the user accounting database, utmpx
48       (see utmpx(4)). Entries in the database are described  by  the  defini‐
49       tions and data structures in <utmpx.h>.
50
51
52       The utmpx structure contains the following members:
53
54         char                 ut_user[32];   /* user login name */
55         char                 ut_id[4];      /* /etc/inittab id */
56                                             /* (usually line #) */
57         char                 ut_line[32];   /* device name */
58                                             /* (console, lnxx) */
59         pid_t                ut_pid;        /* process id */
60         short                ut_type;       /* type of entry */
61         struct exit_status   ut_exit;       /* exit status of a process */
62                                             /* marked as DEAD_PROCESS */
63         struct timeval       ut_tv;         /* time entry was made */
64         int                  ut_session;    /* session ID, used for */
65                                             /* windowing */
66         short                ut_syslen;     /* significant length of */
67                                             /* ut_host */
68                                             /* including terminating null */
69         char                 ut_host[257];  /* host name, if remote */
70
71
72
73       The exit_status structure includes the following members:
74
75         short   e_termination;   /* termination status */
76         short   e_exit;          /* exit status */
77
78
79   getutxent()
80       The getutxent() function reads in the next entry from a utmpx database.
81       If the database is not already open, it opens it. If it reaches the end
82       of the database, it fails.
83
84   getutxid()
85       The  getutxid() function searches forward from the current point in the
86       utmpx database  until  it  finds  an  entry  with  a  ut_type  matching
87       id->ut_type,  if  the  type specified is RUN_LVL, BOOT_TIME, DOWN_TIME,
88       OLD_TIME, or NEW_TIME. If the type specified  in  id  is  INIT_PROCESS,
89       LOGIN_PROCESS,  USER_PROCESS,  or  DEAD_PROCESS,  then  getutxid() will
90       return a pointer to the first entry whose type is one of these four and
91       whose ut_id member matches id->ut_id. If the end of database is reached
92       without a match, it fails.
93
94   getutxline()
95       The getutxline() function searches forward from the  current  point  in
96       the utmpx database until it finds an entry of the type LOGIN_PROCESS or
97       USER_PROCESS which also has a ut_line string matching the line->ut_line
98       string.   If  the  end  of  the database is reached without a match, it
99       fails.
100
101   pututxline()
102       The pututxline() function writes the supplied utmpx structure into  the
103       utmpx  database.   It  uses getutxid() to search forward for the proper
104       place if it finds that it is not already at the proper  place.   It  is
105       expected  that normally the user of pututxline() will have searched for
106       the proper entry using one of the getutx() routines.   If  so,  pututx‐
107       line()  will not search.  If pututxline() does not find a matching slot
108       for the new entry, it will add a new entry to the end of the  database.
109       It returns a pointer to the  utmpx structure. When called by a non-root
110       user, pututxline() invokes a setuid() root program to verify and  write
111       the  entry, since the utmpx database is normally writable only by root.
112       In this event, the ut_name member must correspond to  the  actual  user
113       name  associated  with  the process; the  ut_type member must be either
114       USER_PROCESS or DEAD_PROCESS; and the ut_line member must be  a  device
115       special file and be writable by the user.
116
117   setutxent()
118       The setutxent() function resets the input stream to the beginning. This
119       should be done before each search for a new entry if it is desired that
120       the entire database be examined.
121
122   endutxent()
123       The endutxent() function closes the currently open database.
124
125   utmpxname()
126       The  utmpxname()  function  allows  the  user to change the name of the
127       database file examined from /var/adm/utmpx  to  any  other  file,  most
128       often   /var/adm/wtmpx.  If  the  file does not exist, this will not be
129       apparent until the first attempt to reference the file  is  made.   The
130       utmpxname() function does not open the file, but closes the old file if
131       it is currently open and saves the new file name.  The  new  file  name
132       must  end with the "x" character to allow the name of the corresponding
133       utmp file to be easily obtainable.; otherwise, an error value of  0  is
134       returned. The function returns 1 on success.
135
136   getutmp()
137       The  getutmp() function copies the information stored in the members of
138       the utmpx structure to the corresponding members of the utmp structure.
139       If  the  information in any member of  utmpx does not fit in the corre‐
140       sponding utmp member, the data is silently truncated. (See getutent(3C)
141       for  utmp structure)
142
143   getutmpx()
144       The getutmpx() function copies the information stored in the members of
145       the utmp structure to the corresponding members of the utmpx structure.
146       (See getutent(3C) for  utmp structure)
147
148   updwtmp()
149       The updwtmp() function can be used in two ways.
150
151
152       If wfile is /var/adm/wtmp, the utmp format record supplied by the call‐
153       er is converted to a utmpx format record and the /var/adm/wtmpx file is
154       updated (because the /var/adm/wtmp file no longer exists, operations on
155       wtmp are converted to operations on wtmpx by the library functions.
156
157
158       If wfile is a file other than /var/adm/wtmp, it is assumed to be an old
159       file in utmp format and is updated directly with the utmp format record
160       supplied by the caller.
161
162   updwtmpx()
163       The updwtmpx() function writes the  contents  of  the  utmpx  structure
164       pointed to by utmpx to the database.
165
166   utmpx structure
167       The  values  of  the  e_termination  and  e_exit members of the ut_exit
168       structure are valid only for records of type  DEAD_PROCESS.  For  utmpx
169       entries  created  by  init(1M),   these values are set according to the
170       result of the wait() call that init performs on the  process  when  the
171       process  exits. See the wait(3C), manual page for the values init uses.
172       Applications creating utmpx entries can set ut_exit  values  using  the
173       following code example:
174
175         u->ut_exit.e_termination = WTERMSIG(process->p_exit)
176         u->ut_exit.e_exit = WEXITSTATUS(process->p_exit)
177
178
179
180       See  wait.h(3HEAD)  for  descriptions  of  the WTERMSIG and WEXITSTATUS
181       macros.
182
183
184       The ut_session member is not acted upon by the operating system. It  is
185       used by applications interested in creating utmpx entries.
186
187
188       For  records  of type USER_PROCESS, the nonuser() and nonuserx() macros
189       use the value of the ut_exit.e_exit member to  mark  utmpx  entries  as
190       real  logins (as opposed to multiple xterms started by the same user on
191       a window system).  This allows the system utilities that display  users
192       to  obtain  an accurate indication of the number of actual users, while
193       still permitting each pty to have a utmpx record (as most  applications
194       expect.). The NONROOT_USER macro defines the value that login places in
195       the ut_exit.e_exit member.
196

RETURN VALUES

198       Upon successful completion, getutxent(), getutxid(),  and  getutxline()
199       each  return  a  pointer  to a utmpx structure containing a copy of the
200       requested entry in the user  accounting  database.   Otherwise  a  null
201       pointer is returned.
202
203
204       The  return  value may point to a static area which is overwritten by a
205       subsequent call to getutxid () or getutxline().
206
207
208       Upon successful completion, pututxline() returns a pointer to  a  utmpx
209       structure  containing  a copy of the entry added to the user accounting
210       database.  Otherwise a null pointer is returned.
211
212
213       The endutxent() and setutxent() functions return no value.
214
215
216       A null pointer is returned upon failure to read,  whether  for  permis‐
217       sions or having reached the end of file, or upon failure to write.
218

USAGE

220       These  functions  use buffered standard I/O for input, but pututxline()
221       uses an unbuffered write to avoid  race  conditions  between  processes
222       trying to modify the utmpx and wtmpx files.
223
224
225       Applications  should not access the utmpx and wtmpx databases directly,
226       but should use these functions to ensure that these databases are main‐
227       tained consistently.
228

FILES

230       /var/adm/utmpx    user access and accounting information
231
232
233       /var/adm/wtmpx    history of user access and accounting information
234
235

ATTRIBUTES

237       See attributes(5) for descriptions of the following attributes:
238
239
240
241
242       ┌─────────────────────────────┬─────────────────────────────┐
243       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
244       ├─────────────────────────────┼─────────────────────────────┤
245       │Interface Stability          │See below.                   │
246       ├─────────────────────────────┼─────────────────────────────┤
247       │MT-Level                     │Unsafe                       │
248       └─────────────────────────────┴─────────────────────────────┘
249
250
251       The  endutxent(),  getutxent(), getutxid(), getutxline(), pututxline(),
252       and setutxent() functions are Standard.
253

SEE ALSO

255       getutent(3C),   ttyslot(3C),   wait(3C),    wait.h(3HEAD),    utmpx(4),
256       attributes(5), standards(5)
257

NOTES

259       The  most  current  entry  is  saved  in  a static structure.  Multiple
260       accesses require that it be copied before further accesses are made. On
261       each  call  to  either getutxid() or getutxline(), the routine examines
262       the static structure before performing more I/O. If the contents of the
263       static  structure  match what it is searching for, it looks no further.
264       For this reason, to use getutxline() to search for multiple occurrences
265       it  would  be  necessary  to zero out the static after each success, or
266       getutxline() would just return the same structure over and over  again.
267       There  is one exception to the rule about emptying the structure before
268       further reads are done.  The implicit read done by pututxline() (if  it
269       finds that it is not already at the correct place in the file) will not
270       hurt the contents of the static structure returned by the  getutxent(),
271       getutxid(),  or  getutxline()  routines,  if the user has just modified
272       those contents and passed the pointer back to pututxline().
273
274
275
276SunOS 5.11                        27 Jul 2004                    getutxent(3C)
Impressum