diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3p/endutxent.3p')
| -rw-r--r-- | upstream/mageia-cauldron/man3p/endutxent.3p | 240 |
1 files changed, 240 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3p/endutxent.3p b/upstream/mageia-cauldron/man3p/endutxent.3p new file mode 100644 index 00000000..1e944e4f --- /dev/null +++ b/upstream/mageia-cauldron/man3p/endutxent.3p @@ -0,0 +1,240 @@ +'\" 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 . |