1getutxent(3C) Standard C Library Functions getutxent(3C)
2
6 getutxent, getutxid, getutxline, pututxline, setutxent, endutxent, utm‐
7 pxname, getutmp, getutmpx, updwtmp, updwtmpx - user accounting database
8 functions
9
11 #include <utmpx.h>
12 struct utmpx *getutxent(void);
14 struct utmpx *getutxid(const struct utmpx *id);
17 struct utmpx *getutxline(const struct utmpx *line);
20 struct utmpx *pututxline(const struct utmpx *utmpx);
23 void setutxent(void);
26 void endutxent(void);
29 int utmpxname(const char *file);
32 void getutmp(struct utmpx *utmpx, struct utmp *utmp);
35 void getutmpx(struct utmp *utmp, struct utmpx *utmpx);
38 void updwtmp(char *wfile, struct utmp *utmp);
41 void updwtmpx(char *wfilex, struct utmpx *utmpx);
44
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 The utmpx structure contains the following members:
53 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 The exit_status structure includes the following members:
74 short e_termination; /* termination status */
76 short e_exit; /* exit status */
77 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 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 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 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 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 endutxent()
123 The endutxent() function closes the currently open database.
124 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 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 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 updwtmp()
149 The updwtmp() function can be used in two ways.
150 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 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 updwtmpx()
163 The updwtmpx() function writes the contents of the utmpx structure
164 pointed to by utmpx to the database.
165 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 u->ut_exit.e_termination = WTERMSIG(process->p_exit)
176 u->ut_exit.e_exit = WEXITSTATUS(process->p_exit)
177 See wait.h(3HEAD) for descriptions of the WTERMSIG and WEXITSTATUS
181 macros.
182 The ut_session member is not acted upon by the operating system. It is
185 used by applications interested in creating utmpx entries.
186 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
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 The return value may point to a static area which is overwritten by a
205 subsequent call to getutxid () or getutxline().
206 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 The endutxent() and setutxent() functions return no value.
214 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
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 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
230 /var/adm/utmpx user access and accounting information
231 /var/adm/wtmpx history of user access and accounting information
234
237 See attributes(5) for descriptions of the following attributes:
238 ┌─────────────────────────────┬─────────────────────────────┐
243 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
244 ├─────────────────────────────┼─────────────────────────────┤
245 │Interface Stability │See below. │
246 ├─────────────────────────────┼─────────────────────────────┤
247 │MT-Level │Unsafe │
248 └─────────────────────────────┴─────────────────────────────┘
249 The endutxent(), getutxent(), getutxid(), getutxline(), pututxline(),
252 and setutxent() functions are Standard.
253
255 getutent(3C), ttyslot(3C), wait(3C), wait.h(3HEAD), utmpx(4),
256 attributes(5), standards(5)
257
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().
273SunOS 5.11 27 Jul 2004 getutxent(3C)