getpwuid.3p (7621B)
- '\" 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 .