1ENDUTXENT(3P)              POSIX Programmer's Manual             ENDUTXENT(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       endutxent, getutxent, getutxid,  getutxline,  pututxline,  setutxent  —
13       user accounting database functions
14

SYNOPSIS

16       #include <utmpx.h>
17
18       void endutxent(void);
19       struct utmpx *getutxent(void);
20       struct utmpx *getutxid(const struct utmpx *id);
21       struct utmpx *getutxline(const struct utmpx *line);
22       struct utmpx *pututxline(const struct utmpx *utmpx);
23       void setutxent(void);
24

DESCRIPTION

26       These functions shall provide access to the user accounting database.
27
28       The  getutxent()  function  shall  read  the  next  entry from the user
29       accounting database.  If the database is not  already  open,  it  shall
30       open it. If it reaches the end of the database, it shall fail.
31
32       The  getutxid() function shall search forward from the current point in
33       the database.  If the ut_type value of the utmpx structure  pointed  to
34       by  id  is BOOT_TIME, OLD_TIME, or NEW_TIME, then it shall stop when it
35       finds an entry with a matching ut_type value. If the ut_type  value  is
36       INIT_PROCESS,  LOGIN_PROCESS,  USER_PROCESS,  or  DEAD_PROCESS, then it
37       shall stop when it finds an entry whose type is one of these  four  and
38       whose  ut_id  member  matches  the  ut_id member of the utmpx structure
39       pointed to by id.  If the end of the  database  is  reached  without  a
40       match, getutxid() shall fail.
41
42       The  getutxline()  function shall search forward from the current point
43       in the database until it finds an entry of the  type  LOGIN_PROCESS  or
44       USER_PROCESS  which also has a ut_line value matching that in the utmpx
45       structure pointed to by line.  If the end of the  database  is  reached
46       without a match, getutxline() shall fail.
47
48       The  getutxid()  or getutxline() function may cache data. For this rea‐
49       son, to use getutxline() to search for multiple occurrences, the appli‐
50       cation  shall  zero  out the static data after each success, or getutx‐
51       line() may return a pointer to the same utmpx structure.
52
53       There is one exception to the rule about clearing the structure  before
54       further  reads  are done. The implicit read done by pututxline() (if it
55       finds that it is not already at the correct place in the user  account‐
56       ing database) shall not modify the static structure returned by getutx‐
57       ent(), getutxid(), or getutxline(), if  the  application  has  modified
58       this structure and passed the pointer back to pututxline().
59
60       For  all entries that match a request, the ut_type member indicates the
61       type of the entry. Other members of the entry shall contain  meaningful
62       data based on the value of the ut_type member as follows:
63
64  ┌───────────────┬─────────────────────────────────────────────────────────────────┐
65ut_type Member Other Members with Meaningful Data                
66  ├───────────────┼─────────────────────────────────────────────────────────────────┤
67  │EMPTY          │ No others                                                       │
68  │BOOT_TIME      │ ut_tv
69  │OLD_TIME       │ ut_tv
70  │NEW_TIME       │ ut_tv
71  │USER_PROCESS   │ ut_id, ut_user (login name of the user), ut_line, ut_pid, ut_tv
72  │INIT_PROCESS   │ ut_id, ut_pid, ut_tv
73  │LOGIN_PROCESS  │ ut_id,   ut_user  (implementation-defined  name  of  the  login │
74  │               │ process), ut_line, ut_pid, ut_tv
75  │DEAD_PROCESS   │ ut_id, ut_pid, ut_tv
76  └───────────────┴─────────────────────────────────────────────────────────────────┘
77       An implementation that provides extended security controls  may  impose
78       implementation-defined  restrictions  on  accessing the user accounting
79       database. In particular, the system may deny the existence of  some  or
80       all of the user accounting database entries associated with users other
81       than the caller.
82
83       If the process has appropriate privileges,  the  pututxline()  function
84       shall  write  out  the  structure into the user accounting database. It
85       shall search for a record  as  if  by  getutxid()  that  satisfies  the
86       request.  If  this  search  succeeds, then the entry shall be replaced.
87       Otherwise, a new entry shall be made at the end of the user  accounting
88       database.
89
90       The endutxent() function shall close the user accounting database.
91
92       The  setutxent() function shall reset the input to the beginning of the
93       database. This should be done before each search for a new entry if  it
94       is desired that the entire database be examined.
95
96       These functions need not be thread-safe.
97

RETURN VALUE

99       Upon  successful  completion, getutxent(), getutxid(), and getutxline()
100       shall return a pointer to a utmpx structure containing a  copy  of  the
101       requested  entry  in  the  user  accounting database. Otherwise, a null
102       pointer shall be returned.
103
104       The return value may point to a static area which is overwritten  by  a
105       subsequent call to getutxid() or getutxline().
106
107       Upon  successful  completion,  pututxline() shall return a pointer to a
108       utmpx structure containing a copy  of  the  entry  added  to  the  user
109       accounting database. Otherwise, a null pointer shall be returned.
110
111       The endutxent() and setutxent() functions shall not return a value.
112

ERRORS

114       No  errors  are  defined  for the endutxent(), getutxent(), getutxid(),
115       getutxline(), and setutxent() functions.
116
117       The pututxline() function may fail if:
118
119       EPERM  The process does not have appropriate privileges.
120
121       The following sections are informative.
122

EXAMPLES

124       None.
125

APPLICATION USAGE

127       The sizes of the arrays in the structure can be found using the  sizeof
128       operator.
129

RATIONALE

131       None.
132

FUTURE DIRECTIONS

134       None.
135

SEE ALSO

137       The Base Definitions volume of POSIX.1‐2017, <utmpx.h>
138
140       Portions  of  this text are reprinted and reproduced in electronic form
141       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
142       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
143       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
144       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
145       event of any discrepancy between this version and the original IEEE and
146       The  Open Group Standard, the original IEEE and The Open Group Standard
147       is the referee document. The original Standard can be  obtained  online
148       at http://www.opengroup.org/unix/online.html .
149
150       Any  typographical  or  formatting  errors that appear in this page are
151       most likely to have been introduced during the conversion of the source
152       files  to  man page format. To report such errors, see https://www.ker
153       nel.org/doc/man-pages/reporting_bugs.html .
154
155
156
157IEEE/The Open Group                  2017                        ENDUTXENT(3P)
Impressum