diff options
Diffstat (limited to 'upstream/archlinux/man3p/getpwuid.3p')
| -rw-r--r-- | upstream/archlinux/man3p/getpwuid.3p | 297 |
1 files changed, 297 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/getpwuid.3p b/upstream/archlinux/man3p/getpwuid.3p new file mode 100644 index 00000000..49f7ff93 --- /dev/null +++ b/upstream/archlinux/man3p/getpwuid.3p @@ -0,0 +1,297 @@ +'\" et +.TH GETPWUID "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 +getpwuid, +getpwuid_r +\(em search user database for a user ID +.SH SYNOPSIS +.LP +.nf +#include <pwd.h> +.P +struct passwd *getpwuid(uid_t \fIuid\fP); +int getpwuid_r(uid_t \fIuid\fP, struct passwd *\fIpwd\fP, char *\fIbuffer\fP, + size_t \fIbufsize\fP, struct passwd **\fIresult\fP); +.fi +.SH DESCRIPTION +The +\fIgetpwuid\fR() +function shall search the user database for an entry with a matching +.IR uid . +.P +The +\fIgetpwuid\fR() +function need not be thread-safe. +.P +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetpwuid\fR(). +If +\fIgetpwuid\fR() +returns a null pointer and +.IR errno +is set to non-zero, an error occurred. +.P +The +\fIgetpwuid_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 uid . +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 +\fIgetpwuid\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 +If successful, the +\fIgetpwuid_r\fR() +function shall return zero; otherwise, 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 +\fIgetpwuid\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 +\fIgetpwuid_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 +\fIgetpwuid_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 = getpwuid_r(42, &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 Root User" +.P +The following example gets the user database entry for the user with +user ID 0 (root). +.sp +.RS 4 +.nf + +#include <sys/types.h> +#include <pwd.h> +\&... +uid_t id = 0; +struct passwd *pwd; +.P +pwd = getpwuid(id); +.fi +.P +.RE +.SS "Finding the Name for the Effective User ID" +.P +The following example defines +.IR pws +as a pointer to a structure of type +.BR passwd , +which is used to store the structure pointer returned by the call to +the +\fIgetpwuid\fR() +function. The +\fIgeteuid\fR() +function shall return the effective user ID of the calling process; +this is used as the search criteria for the +\fIgetpwuid\fR() +function. The call to +\fIgetpwuid\fR() +shall return a pointer to the structure containing that user ID value. +.sp +.RS 4 +.nf + +#include <unistd.h> +#include <sys/types.h> +#include <pwd.h> +\&... +struct passwd *pws; +pws = getpwuid(geteuid()); +.fi +.P +.RE +.SS "Finding an Entry in the User Database" +.P +The following example uses +\fIgetpwuid\fR() +to search the user database for a user ID that was previously stored in +a +.BR stat +structure, then prints out the user name if it is found. If the user +is not found, the program prints the numeric value of the user ID for +the entry. +.sp +.RS 4 +.nf + +#include <sys/types.h> +#include <pwd.h> +#include <stdio.h> +\&... +struct stat statbuf; +struct passwd *pwd; +\&... +if ((pwd = getpwuid(statbuf.st_uid)) != NULL) + printf(" %-8.8s", pwd->pw_name); +else + printf(" %-8d", statbuf.st_uid); +.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 +\fIgetpwuid_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 "\fIgetpwnam\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIgetlogin\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 . |