.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
.\" <mtk.manpages@gmail.com>
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
.\" References consulted:
.\" Linux libc source code
.\" Modified 2003-11-15 by aeb
.\" 2008-11-07, mtk, Added an example program for getpwnam_r().
.\"
-.TH GETPWNAM 3 2009-03-30 "GNU" "Linux Programmer's Manual"
+.TH GETPWNAM 3 2013-07-22 "GNU" "Linux Programmer's Manual"
.SH NAME
getpwnam, getpwnam_r, getpwuid, getpwuid_r \- get password file entry
.SH SYNOPSIS
that matches the user ID
.IR uid .
.PP
-The
-.BR getpwnam_r ()
-and
-.BR getpwuid_r ()
-functions obtain the same information, but store the retrieved
-.I passwd
-structure in the space pointed to by
-.IR pwd .
-This
-.I passwd
-structure contains pointers to strings, and these strings
-are stored in the buffer
-.I buf
-of size
-.IR buflen .
-A pointer to the result (in case of success) or NULL (in case no entry
-was found or an error occurred) is stored in
-.IR *result .
-.PP
The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows:
.sp
.in +4n
char *pw_passwd; /* user password */
uid_t pw_uid; /* user ID */
gid_t pw_gid; /* group ID */
- char *pw_gecos; /* real name */
+ char *pw_gecos; /* user information */
char *pw_dir; /* home directory */
char *pw_shell; /* shell program */
};
.fi
.in
.PP
-The maximum needed size for
+See
+.BR passwd (5)
+for more information about these fields.
+.PP
+The
+.BR getpwnam_r ()
+and
+.BR getpwuid_r ()
+functions obtain the same information as
+.BR getpwnam ()
+and
+.BR getpwuid (),
+but store the retrieved
+.I passwd
+structure in the space pointed to by
+.IR pwd .
+The string fields pointed to by the members of the
+.I passwd
+structure are stored in the buffer
.I buf
-can be found using
-.BR sysconf (3)
-with the argument
-.BR _SC_GETPW_R_SIZE_MAX .
-.SH "RETURN VALUE"
+of size
+.IR buflen .
+A pointer to the result (in case of success) or NULL (in case no entry
+was found or an error occurred) is stored in
+.IR *result .
+.PP
+The call
+
+ sysconf(_SC_GETPW_R_SIZE_MAX)
+
+returns either \-1, without changing
+.IR errno ,
+or an initial suggested size for
+.IR buf .
+(If this size is too small,
+the call fails with
+.BR ERANGE ,
+in which case the caller can retry with a larger buffer.)
+.SH RETURN VALUE
The
.BR getpwnam ()
and
.TP
.I /etc/passwd
local password database file
-.SH "CONFORMING TO"
+.SH ATTRIBUTES
+.SS Multithreading (see pthreads(7))
+The
+.BR getpwnam ()
+and
+.BR getpwuid ()
+functions are not thread-safe.
+.LP
+The
+.BR getpwnam_r ()
+and
+.BR getpwuid_r ()
+functions are thread-safe.
+.SH CONFORMING TO
SVr4, 4.3BSD, POSIX.1-2001.
+The
+.I pw_gecos
+field is not specified in POSIX, but is present on most implementations.
.SH NOTES
The formulation given above under "RETURN VALUE" is from POSIX.1-2001.
It does not call "not found" an error, and hence does not specify what value
should be left unchanged if an entry is not found.
Experiments on various
UNIX-like systems show that lots of different values occur in this
-situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM and probably others.
+situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others.
.\" more precisely:
.\" AIX 5.1 - gives ESRCH
.\" OSF1 4.0g - gives EWOULDBLOCK
exit(EXIT_SUCCESS);
}
.fi
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR endpwent (3),
.BR fgetpwent (3),
.BR getgrnam (3),
.BR putpwent (3),
.BR setpwent (3),
.BR passwd (5)
+.SH COLOPHON
+This page is part of release 3.65 of the Linux
+.I man-pages
+project.
+A description of the project,
+and information about reporting bugs,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.