endutxent.3p (6627B)
- '\" et
- .TH ENDUTXENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- endutxent,
- getutxent,
- getutxid,
- getutxline,
- pututxline,
- setutxent
- \(em user accounting database functions
- .SH SYNOPSIS
- .LP
- .nf
- #include <utmpx.h>
- .P
- void endutxent(void);
- struct utmpx *getutxent(void);
- struct utmpx *getutxid(const struct utmpx *\fIid\fP);
- struct utmpx *getutxline(const struct utmpx *\fIline\fP);
- struct utmpx *pututxline(const struct utmpx *\fIutmpx\fP);
- void setutxent(void);
- .fi
- .SH DESCRIPTION
- These functions shall provide access to the user accounting database.
- .P
- The
- \fIgetutxent\fR()
- function shall read the next entry from the user accounting database.
- If the database is not already open, it shall open it. If it reaches
- the end of the database, it shall fail.
- .P
- The
- \fIgetutxid\fR()
- function shall search forward from the current point in the database.
- If the
- .IR ut_type
- value of the
- .BR utmpx
- structure pointed to by
- .IR id
- is BOOT_TIME, OLD_TIME, or NEW_TIME, then it shall stop when it finds
- an
- entry with a matching
- .IR ut_type
- value. If the
- .IR ut_type
- value is INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS,
- or DEAD_PROCESS, then it shall stop when it finds an entry whose type
- is one of these four and whose
- .IR ut_id
- member matches the
- .IR ut_id
- member of the
- .BR utmpx
- structure pointed to by
- .IR id .
- If the end of the database is reached without a match,
- \fIgetutxid\fR()
- shall fail.
- .P
- The
- \fIgetutxline\fR()
- function shall search forward from the current point in the database
- until it finds an entry of the type LOGIN_PROCESS or USER_PROCESS which
- also has a
- .IR ut_line
- value matching that in the
- .BR utmpx
- structure pointed to by
- .IR line .
- If the end of the database is reached without a match,
- \fIgetutxline\fR()
- shall fail.
- .P
- The
- \fIgetutxid\fR()
- or
- \fIgetutxline\fR()
- function may cache data. For this reason, to use
- \fIgetutxline\fR()
- to search for multiple occurrences, the application shall zero out the
- static data after each success, or
- \fIgetutxline\fR()
- may return a pointer to the same
- .BR utmpx
- structure.
- .P
- There is one exception to the rule about clearing the structure before
- further reads are done. The implicit read done by
- \fIpututxline\fR()
- (if it finds that it is not already at the correct place in the user
- accounting database) shall not modify the static structure returned by
- \fIgetutxent\fR(),
- \fIgetutxid\fR(),
- or
- \fIgetutxline\fR(),
- if the application has modified this structure and passed the
- pointer back to
- \fIpututxline\fR().
- .P
- For all entries that match a request, the
- .IR ut_type
- member indicates the type of the entry. Other members of the entry
- shall contain meaningful data based on the value of the
- .IR ut_type
- member as follows:
- .TS
- box center tab(!);
- cB | cB
- l | l.
- ut_type Member!Other Members with Meaningful Data
- _
- EMPTY!No others
- BOOT_TIME!\fIut_tv\fP
- OLD_TIME!\fIut_tv\fP
- NEW_TIME!\fIut_tv\fP
- USER_PROCESS!\fIut_id\fP, \fIut_user\fP (login name of the user), \fIut_line\fP, \fIut_pid\fP, \fIut_tv\fP
- INIT_PROCESS!\fIut_id\fP, \fIut_pid\fP, \fIut_tv\fP
- LOGIN_PROCESS!T{
- .IR ut_id ,
- .IR ut_user
- (implementation-defined name of the login process),
- .IR ut_line ,
- .IR ut_pid ,
- .IR ut_tv
- T}
- DEAD_PROCESS!\fIut_id\fP, \fIut_pid\fP, \fIut_tv\fP
- .TE
- .P
- An implementation that provides extended security controls may impose
- implementation-defined restrictions on accessing the user accounting
- database. In particular, the system may deny the existence of some or
- all of the user accounting database entries associated with users other
- than the caller.
- .P
- If the process has appropriate privileges, the
- \fIpututxline\fR()
- function shall write out the structure into the user accounting
- database. It shall search for a record as if by
- \fIgetutxid\fR()
- that satisfies the request. If this search succeeds, then the entry
- shall be replaced. Otherwise, a new entry shall be made at the end of
- the user accounting database.
- .P
- The
- \fIendutxent\fR()
- function shall close the user accounting database.
- .P
- The
- \fIsetutxent\fR()
- function shall reset the input to the beginning of the database. This
- should be done before each search for a new entry if it is desired that
- the entire database be examined.
- .P
- These functions need not be thread-safe.
- .SH "RETURN VALUE"
- Upon successful completion,
- \fIgetutxent\fR(),
- \fIgetutxid\fR(),
- and
- \fIgetutxline\fR()
- shall return a pointer to a
- .BR utmpx
- structure containing a copy of the requested entry in the user
- accounting database. Otherwise, a null pointer shall be returned.
- .P
- The return value may point to a static area which is overwritten by a
- subsequent call to
- \fIgetutxid\fR()
- or
- \fIgetutxline\fR().
- .P
- Upon successful completion,
- \fIpututxline\fR()
- shall return a pointer to a
- .BR utmpx
- structure containing a copy of the entry added to the user accounting
- database. Otherwise, a null pointer shall be returned.
- .P
- The
- \fIendutxent\fR()
- and
- \fIsetutxent\fR()
- functions shall not return a value.
- .SH ERRORS
- No errors are defined for the
- \fIendutxent\fR(),
- \fIgetutxent\fR(),
- \fIgetutxid\fR(),
- \fIgetutxline\fR(),
- and
- \fIsetutxent\fR()
- functions.
- .P
- The
- \fIpututxline\fR()
- function may fail if:
- .TP
- .BR EPERM
- The process does not have appropriate privileges.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- The sizes of the arrays in the structure can be found using the
- .IR sizeof
- operator.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<utmpx.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .