diff options
Diffstat (limited to 'upstream/archlinux/man3p/getpwnam.3p')
| -rw-r--r-- | upstream/archlinux/man3p/getpwnam.3p | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/getpwnam.3p b/upstream/archlinux/man3p/getpwnam.3p new file mode 100644 index 00000000..33cedead --- /dev/null +++ b/upstream/archlinux/man3p/getpwnam.3p @@ -0,0 +1,248 @@ +'\" et +.TH GETPWNAM "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 +getpwnam, +getpwnam_r +\(em search user database for a name +.SH SYNOPSIS +.LP +.nf +#include <pwd.h> +.P +struct passwd *getpwnam(const char *\fIname\fP); +int getpwnam_r(const char *\fIname\fP, struct passwd *\fIpwd\fP, char *\fIbuffer\fP, + size_t \fIbufsize\fP, struct passwd **\fIresult\fP); +.fi +.SH DESCRIPTION +The +\fIgetpwnam\fR() +function shall search the user database for an entry with a matching +.IR name . +.P +The +\fIgetpwnam\fR() +function need not be thread-safe. +.P +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetpwnam\fR(). +If +\fIgetpwnam\fR() +returns a null pointer and +.IR errno +is non-zero, an error occurred. +.P +The +\fIgetpwnam_r\fR() +function shall update the +.BR passwd +structure pointed to by +.IR pwd +and store a pointer to that structure at the location pointed to by +.IR result . +The structure shall contain an entry from the user database with a +matching +.IR name . +Storage referenced by the structure is allocated from the memory +provided with the +.IR buffer +parameter, which is +.IR bufsize +bytes in size. A call to +.IR sysconf (_SC_GETPW_R_SIZE_MAX) +returns either \-1 without changing +.IR errno +or an initial value suggested for the size of this buffer. +A null pointer shall be returned at the location pointed to by +.IR result +on error or if the requested entry is not found. +.SH "RETURN VALUE" +The +\fIgetpwnam\fR() +function shall return a pointer to a +.BR "struct passwd" +with the structure as defined in +.IR <pwd.h> +with a matching entry if found. A null pointer shall be returned if the +requested entry is not found, or an error occurs. If the requested +entry was not found, +.IR errno +shall not be changed. On error, +.IR errno +shall be set to indicate the error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetpwent\fR(), +\fIgetpwnam\fR(), +or +\fIgetpwuid\fR(). +The returned pointer, and pointers within the structure, might +also be invalidated if the calling thread is terminated. +.P +The +\fIgetpwnam_r\fR() +function shall return zero on success or if the requested entry +was not found and no error has occurred. If an error has +occurred, an error number shall be returned to indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EIO +An I/O error has occurred. +.TP +.BR EINTR +A signal was caught during +\fIgetpwnam\fR(). +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.P +The +\fIgetpwnam_r\fR() +function may fail if: +.TP +.BR ERANGE +Insufficient storage was supplied via +.IR buffer +and +.IR bufsize +to contain the data to be referenced by the resulting +.BR passwd +structure. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Note that +.IR sysconf (_SC_GETPW_R_SIZE_MAX) +may return \-1 if there is no hard limit on the size of the buffer +needed to store all the groups returned. This example shows how an +application can allocate a buffer of sufficient size to work with +\fIgetpwnam_r\fR(). +.sp +.RS 4 +.nf + +long int initlen = sysconf(_SC_GETPW_R_SIZE_MAX); +size_t len; +if (initlen =\|= -1) + /* Default initial length. */ + len = 1024; +else + len = (size_t) initlen; +struct passwd result; +struct passwd *resultp; +char *buffer = malloc(len); +if (buffer =\|= NULL) + ...handle error... +int e; +while ((e = getpwnam_r("someuser", &result, buffer, len, &resultp)) + =\|= ERANGE) + { + size_t newlen = 2 * len; + if (newlen < len) + ...handle error... + len = newlen; + char *newbuffer = realloc(buffer, len); + if (newbuffer =\|= NULL) + ...handle error... + buffer = newbuffer; + } +if (e != 0) + ...handle error... +free (buffer); +.fi +.P +.RE +.SS "Getting an Entry for the Login Name" +.P +The following example uses the +\fIgetlogin\fR() +function to return the name of the user who logged in; this information +is passed to the +\fIgetpwnam\fR() +function to get the user database entry for that user. +.sp +.RS 4 +.nf + +#include <sys/types.h> +#include <pwd.h> +#include <unistd.h> +#include <stdio.h> +#include <stdlib.h> +\&... +char *lgn; +struct passwd *pw; +\&... +if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) { + fprintf(stderr, "Get of user information failed.\en"); exit(1); +} +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +Three names associated with the current process can be determined: +.IR getpwuid (\c +\fIgeteuid\fR()) +returns the name associated with the effective user ID of the process; +\fIgetlogin\fR() +returns the name associated with the current login activity; and +.IR getpwuid (\c +\fIgetuid\fR()) +returns the name associated with the real user ID of the process. +.P +The +\fIgetpwnam_r\fR() +function is thread-safe and returns values in a user-supplied buffer +instead of possibly using a static data area that may be overwritten by +each call. +.P +Portable applications should take into account that it is usual +for an implementation to return \-1 from +\fIsysconf\fR() +indicating that there is no maximum for _SC_GETPW_R_SIZE_MAX. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpwuid\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<pwd.h>\fP", +.IR "\fB<sys_types.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 . |