diff options
Diffstat (limited to 'man-pages-posix-2013/man3p/getpwnam.3p')
| -rw-r--r-- | man-pages-posix-2013/man3p/getpwnam.3p | 241 |
1 files changed, 241 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man3p/getpwnam.3p b/man-pages-posix-2013/man3p/getpwnam.3p new file mode 100644 index 0000000..5d47101 --- /dev/null +++ b/man-pages-posix-2013/man3p/getpwnam.3p @@ -0,0 +1,241 @@ +'\" et +.TH GETPWNAM "3P" 2013 "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 \(mi1 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. 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(). +.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 \(mi1 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 +\fB +long int initlen = sysconf(_SC_GETPW_R_SIZE_MAX); +size_t len; +if (initlen =\|= \(mi1) + /* 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 \fR +.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 +\fB +#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 \fR +.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 \(mi1 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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html . + +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 . |