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

NAME

6       getutent, getutid, getutline, pututline, setutent, endutent, utmpname -
7       user accounting database functions
8

SYNOPSIS

10       #include <utmp.h>
11
12       struct utmp *getutent(void);
13
14
15       struct utmp *getutid(const struct utmp *id);
16
17
18       struct utmp *getutline(const struct utmp *line);
19
20
21       struct utmp *pututline(const struct utmp *utmp);
22
23
24       void setutent(void);
25
26
27       void endutent(void);
28
29
30       int utmpname(const char *file);
31
32

DESCRIPTION

34       These functions provide access to the user accounting  database,  utmp.
35       Entries  in  the  database  are  described  by the definitions and data
36       structures in <utmp.h>.
37
38
39       The utmp structure contains the following members:
40
41         char                ut_user[8];   /* user login name */
42         char                ut_id[4];     /* /sbin/inittab id */
43                                           /* (usually line #) */
44         char                ut_line[12];  /* device name (console, lnxx) */
45         short               ut_pid;       /* process id */
46         short               ut_type;      /* type of entry */
47         struct exit_status  ut_exit;      /* exit status of a process */
48                                           /* marked as DEAD_PROCESS */
49         time_t              ut_time;      /* time entry was made */
50
51
52
53       The structure exit_status includes the following members:
54
55         short   e_termination;   /* termination status */
56         short   e_exit;          /* exit status */
57
58
59   getutent()
60       The getutent() function reads in the next entry from a  utmp  database.
61       If  the  database  is not already open, it opens it.  If it reaches the
62       end of the database, it fails.
63
64   getutid()
65       The getutid() function searches forward from the current point  in  the
66       utmp  database  until  it  finds  an  entry  with  a  ut_type  matching
67       id->ut_type if the type specified  is  RUN_LVL,  BOOT_TIME,  DOWN_TIME,
68       OLD_TIME,  or  NEW_TIME.  If  the type specified in id is INIT_PROCESS,
69       LOGIN_PROCESS,  USER_PROCESS,  or  DEAD_PROCESS,  then  getutid()  will
70       return a pointer to the first entry whose type is one of these four and
71       whose ut_id member matches id->ut_id. If the end of database is reached
72       without a match, it fails.
73
74   getutline()
75       The getutline() function searches forward from the current point in the
76       utmp database until it finds an entry  of  the  type  LOGIN_PROCESS  or
77       ut_line  string  matching the line->ut_line string. If the end of data‐
78       base is reached without a match, it fails.
79
80   pututline()
81       The pututline() function writes the supplied utmp  structure  into  the
82       utmp  database.   It  uses  getutid()  to search forward for the proper
83       place if it finds that it is not already at the proper  place.   It  is
84       expected  that  normally the user of pututline() will have searched for
85       the proper entry using one of the these functions.  If so,  pututline()
86       will  not search.  If pututline() does not find a matching slot for the
87       new entry, it will add a new entry to the  end  of  the  database.   It
88       returns  a  pointer  to  the  utmp structure. When called by a non-root
89       user, pututline() invokes a setuid() root program to verify  and  write
90       the  entry,  since the utmp database is normally writable only by root.
91       In this event, the ut_name member must correspond to  the  actual  user
92       name  associated  with  the process; the  ut_type member must be either
93       USER_PROCESS or DEAD_PROCESS; and the ut_line member must be  a  device
94       special file and be writable by the user.
95
96   setutent()
97       The setutent() function resets the input stream to the beginning.  This
98       reset should be done before each search  for  a  new  entry  if  it  is
99       desired that the entire database be examined.
100
101   endutent()
102       The endutent() function closes the currently open database.
103
104   utmpname()
105       The utmpname() function allows the user to change the name of the data‐
106       base file examined to another file.  If the file does not  exist,  this
107       will  not  be apparent until the first attempt to reference the file is
108       made.  The utmpname() function does not open the file  but  closes  the
109       old file if it is currently open and saves the new file name.
110

RETURN VALUES

112       A  null  pointer  is returned upon failure to read, whether for permis‐
113       sions or having reached the end of file, or upon failure to  write.  If
114       the file name given is longer than 79 characters, utmpname() returns 0.
115       Otherwise, it returns 1.
116

USAGE

118       These functions use buffered standard I/O for  input,  but  pututline()
119       uses  an unbuffered non-standard write to avoid race conditions between
120       processes trying to modify the utmp and wtmp databases.
121
122
123       Applications should not access the utmp and  wtmp  databases  directly,
124       but should use these functions to ensure that these databases are main‐
125       tained consistently. Using these functions, however, may cause applica‐
126       tions to fail if user accounting data cannot be represented properly in
127       the utmp structure (for example, on a  system  where  PIDs  can  exceed
128       32767).   Use  the functions described on the getutxent(3C) manual page
129       instead.
130

ATTRIBUTES

132       See attributes(5) for descriptions of the following attributes:
133
134
135
136
137       ┌─────────────────────────────┬─────────────────────────────┐
138       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
139       ├─────────────────────────────┼─────────────────────────────┤
140       │MT-Level                     │Unsafe                       │
141       └─────────────────────────────┴─────────────────────────────┘
142

SEE ALSO

144       getutxent(3C), ttyslot(3C), utmpx(4), attributes(5)
145

NOTES

147       The most current entry  is  saved  in  a  static  structure.   Multiple
148       accesses require that it be copied before further accesses are made. On
149       each call to either getutid() or getutline(), the function examines the
150       static  structure  before  performing  more I/O. If the contents of the
151       static structure match what it is searching for, it looks  no  further.
152       For this reason, to use getutline() to search for multiple occurrences,
153       it would be necessary to zero out the static area after  each  success,
154       or  getutline()  would  just  return  the  same structure over and over
155       again. There is one exception to the rule about emptying the  structure
156       before  further  reads are done.  The implicit read done by pututline()
157       (if it finds that it is not already at the correct place in  the  file)
158       will  not  hurt  the  contents  of the static structure returned by the
159       getutent(), getutid() or getutline() functions, if the  user  has  just
160       modified those contents and passed the pointer back to pututline().
161
162
163
164SunOS 5.11                        27 Oct 1998                     getutent(3C)
Impressum