| blob | 76b25cec9c4c0bcc111ce4c7b85d4219bd006ff8 |
1 '\" te
2 .\" Copyright 1989 AT&T Copyright (c) 1998, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH GETUTENT 3C "April 9, 2016"
7 .SH NAME
8 getutent, getutid, getutline, pututline, setutent, endutent, utmpname \- user
9 accounting database functions
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #include <utmp.h>
15 \fBstruct utmp *\fR\fBgetutent\fR(\fBvoid\fR);
16 .fi
18 .LP
19 .nf
20 \fBstruct utmp *\fR\fBgetutid\fR(\fBconst struct utmp *\fR\fIid\fR);
21 .fi
23 .LP
24 .nf
25 \fBstruct utmp *\fR\fBgetutline\fR(\fBconst struct utmp *\fR\fIline\fR);
26 .fi
28 .LP
29 .nf
30 \fBstruct utmp *\fR\fBpututline\fR(\fBconst struct utmp *\fR\fIutmp\fR);
31 .fi
33 .LP
34 .nf
35 \fBvoid\fR \fBsetutent\fR(\fBvoid\fR);
36 .fi
38 .LP
39 .nf
40 \fBvoid\fR \fBendutent\fR(\fBvoid\fR);
41 .fi
43 .LP
44 .nf
45 \fBint\fR \fButmpname\fR(\fBconst char *\fR\fIfile\fR);
46 .fi
48 .SH DESCRIPTION
49 .LP
50 These functions provide access to the user accounting database, \fButmp\fR.
51 Entries in the database are described by the definitions and data structures in
52 \fB<utmp.h>\fR\&.
53 .sp
54 .LP
55 The \fButmp\fR structure contains the following members:
56 .sp
57 .in +2
58 .nf
59 char ut_user[8]; /* user login name */
60 char ut_id[4]; /* /sbin/inittab id */
61 /* (usually line #) */
62 char ut_line[12]; /* device name (console, lnxx) */
63 short ut_pid; /* process id */
64 short ut_type; /* type of entry */
65 struct exit_status ut_exit; /* exit status of a process */
66 /* marked as DEAD_PROCESS */
67 time_t ut_time; /* time entry was made */
68 .fi
69 .in -2
71 .sp
72 .LP
73 The structure \fBexit_status\fR includes the following members:
74 .sp
75 .in +2
76 .nf
77 short e_termination; /* termination status */
78 short e_exit; /* exit status */
79 .fi
80 .in -2
82 .SS "\fBgetutent()\fR"
83 .LP
84 The \fBgetutent()\fR function reads in the next entry from a \fButmp\fR
85 database. If the database is not already open, it opens it. If it reaches the
86 end of the database, it fails.
87 .SS "\fBgetutid()\fR"
88 .LP
89 The \fBgetutid()\fR function searches forward from the current point in the
90 \fButmp\fR database until it finds an entry with a \fBut_type\fR matching
91 \fIid\fR->\fBut_type\fR if the type specified is \fBRUN_LVL\fR,
92 \fBBOOT_TIME\fR, \fBDOWN_TIME\fR, \fBOLD_TIME\fR, or \fBNEW_TIME\fR. If the
93 type specified in \fIid\fR is \fBINIT_PROCESS\fR, \fBLOGIN_PROCESS\fR,
94 \fBUSER_PROCESS\fR, or \fBDEAD_PROCESS\fR, then \fBgetutid()\fR will return a
95 pointer to the first entry whose type is one of these four and whose
96 \fBut_id\fR member matches \fIid\fR->\fBut_id\fR. If the end of database is
97 reached without a match, it fails.
98 .SS "\fBgetutline()\fR"
99 .LP
100 The \fBgetutline()\fR function searches forward from the current point in the
101 \fButmp\fR database until it finds an entry of the type \fBLOGIN_PROCESS\fR or
102 \fBut_line\fR string matching the \fIline\fR->\fBut_line\fR string. If the end
103 of database is reached without a match, it fails.
104 .SS "\fBpututline()\fR"
105 .LP
106 The \fBpututline()\fR function writes the supplied \fButmp\fR structure into
107 the \fButmp\fR database. It uses \fBgetutid()\fR to search forward for the
108 proper place if it finds that it is not already at the proper place. It is
109 expected that normally the user of \fBpututline()\fR will have searched for the
110 proper entry using one of these functions. If so, \fBpututline()\fR will
111 not search. If \fBpututline()\fR does not find a matching slot for the new
112 entry, it will add a new entry to the end of the database. It returns a
113 pointer to the \fButmp\fR structure. When called by a non-root user,
114 \fBpututline()\fR invokes a \fBsetuid()\fR root program to verify and write the
115 entry, since the \fButmp\fR database is normally writable only by root. In
116 this event, the \fBut_name\fR member must correspond to the actual user name
117 associated with the process; the \fBut_type\fR member must be either
118 \fBUSER_PROCESS\fR or \fBDEAD_PROCESS\fR; and the \fBut_line\fR member must be
119 a device special file and be writable by the user.
120 .SS "\fBsetutent()\fR"
121 .LP
122 The \fBsetutent()\fR function resets the input stream to the beginning. This
123 reset should be done before each search for a new entry if it is desired that
124 the entire database be examined.
125 .SS "\fBendutent()\fR"
126 .LP
127 The \fBendutent()\fR function closes the currently open database.
128 .SS "\fButmpname()\fR"
129 .LP
130 The \fButmpname()\fR function allows the user to change the name of the
131 database file examined to another file. If the file does not exist, this will
132 not be apparent until the first attempt to reference the file is made. The
133 \fButmpname()\fR function does not open the file but closes the old file if it
134 is currently open and saves the new file name.
135 .SH RETURN VALUES
136 .LP
137 A null pointer is returned upon failure to read, whether for permissions or
138 having reached the end of file, or upon failure to write. If the file name
139 given is longer than 79 characters, \fButmpname()\fR returns \fB0\fR.
140 Otherwise, it returns \fB1\fR.
141 .SH USAGE
142 .LP
143 These functions use buffered standard I/O for input, but \fBpututline()\fR uses
144 an unbuffered non-standard write to avoid race conditions between processes
145 trying to modify the \fButmp\fR and \fBwtmp\fR databases.
146 .sp
147 .LP
148 Applications should not access the \fButmp\fR and \fBwtmp\fR databases
149 directly, but should use these functions to ensure that these databases are
150 maintained consistently. Using these functions, however, may cause applications
151 to fail if user accounting data cannot be represented properly in the
152 \fButmp\fR structure (for example, on a system where PIDs can exceed 32767).
153 Use the functions described on the \fBgetutxent\fR(3C) manual page instead.
154 .SH ATTRIBUTES
155 .LP
156 See \fBattributes\fR(5) for descriptions of the following attributes:
157 .sp
159 .sp
160 .TS
161 box;
162 c | c
163 l | l .
164 ATTRIBUTE TYPE ATTRIBUTE VALUE
165 _
166 MT-Level Unsafe
167 .TE
169 .SH SEE ALSO
170 .LP
171 \fBgetutxent\fR(3C), \fBttyslot\fR(3C), \fButmpx\fR(4), \fBattributes\fR(5)
172 .SH NOTES
173 .LP
174 The most current entry is saved in a static structure. Multiple accesses
175 require that it be copied before further accesses are made. On each call to
176 either \fBgetutid()\fR or \fBgetutline()\fR, the function examines the static
177 structure before performing more I/O. If the contents of the static structure
178 match what it is searching for, it looks no further. For this reason, to use
179 \fBgetutline()\fR to search for multiple occurrences, it would be necessary to
180 zero out the static area after each success, or \fBgetutline()\fR would just
181 return the same structure over and over again. There is one exception to the
182 rule about emptying the structure before further reads are done. The implicit
183 read done by \fBpututline()\fR (if it finds that it is not already at the
184 correct place in the file) will not hurt the contents of the static structure
185 returned by the \fBgetutent()\fR, \fBgetutid()\fR or \fBgetutline()\fR
186 functions, if the user has just modified those contents and passed the pointer
187 back to \fBpututline()\fR.