Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GETPWNAM(3)	       FreeBSD Library Functions Manual		   GETPWNAM(3)

NAME
     getpwnam, getpwuid, getpwnam_r, getpwuid_r, getpwnam_shadow,
     getpwuid_shadow, setpassent -- password database operations

SYNOPSIS
     #include <pwd.h>

     struct passwd *
     getpwnam(const char *login);

     struct passwd *
     getpwuid(uid_t uid);

     int
     getpwnam_r(const char *login, struct passwd *pwstore, char	*buf,
	 size_t	bufsize, struct	passwd **result);

     int
     getpwuid_r(uid_t uid, struct passwd *pwstore, char	*buf, size_t bufsize,
	 struct	passwd **result);

     struct passwd *
     getpwnam_shadow(const char	*login);

     struct passwd *
     getpwuid_shadow(uid_t uid);

     int
     setpassent(int stayopen);

DESCRIPTION
     These functions operate on	the password database file which is described
     in	passwd(5).  Each entry in the database is defined by the structure
     struct passwd found in the	include	file <pwd.h>:

	   struct passwd {
		   char	   *pw_name;	   /* user name	*/
		   char	   *pw_passwd;	   /* encrypted	password */
		   uid_t   pw_uid;	   /* user uid */
		   gid_t   pw_gid;	   /* user gid */
		   time_t  pw_change;	   /* password change time */
		   char	   *pw_class;	   /* user access class	*/
		   char	   *pw_gecos;	   /* Honeywell	login info */
		   char	   *pw_dir;	   /* home directory */
		   char	   *pw_shell;	   /* default shell */
		   time_t  pw_expire;	   /* account expiration */
	   };

     The functions getpwnam() and getpwuid() search the	password database for
     the given login name or user ID, respectively, always returning the first
     one encountered.

     The getpwnam_r() and getpwuid_r() functions both update the passwd	struc-
     ture pointed to by	pwstore	and store a pointer to that structure at the
     location pointed to by result.  The structure is filled with an entry
     from the password database	with a matching	name or	uid.  Storage refer-
     enced by the passwd structure will	be allocated from the memory provided
     with the buf parameter, which is bufsiz characters	in size.  The maximum
     size needed for this buffer can be	determined with
     sysconf(_SC_GETPW_R_SIZE_MAX).

     setpassent() accomplishes two purposes.  First, it	causes getpwent(3) to
     "rewind" to the beginning of the database.	 Additionally, if stayopen is
     non-zero, file descriptors	are left open, significantly speeding up sub-
     sequent accesses for the lookup routines.	These file descriptors can be
     closed by a call to endpwent(3).

     It	is dangerous for long-running programs to keep the file	descriptors
     open as the database will become out of date if it	is updated while the
     program is	running.  However the file descriptors are automatically
     closed when execve(2) is called.

     These routines have been written to "shadow" the password file, that is,
     allow only	certain	programs to have access	to the encrypted password.
     The default functions will	not return the true encrypted password,	but
     instead only the string `*'.  If the process which	calls them has an ef-
     fective UID of 0 or has the "_shadow" group in its	group vector, and
     wishes to access the encrypted password, it should	use the
     getpwnam_shadow() and getpwuid_shadow() functions.

   YP support
     If	YP is active, the functions getpwnam() and getpwnam_r()	also use the
     master.passwd.byname YP map (if available)	or the passwd.byname YP	map;
     and the functions getpwuid() and getpwuid_r() also	use the
     master.passwd.byuid YP map	(if available) or the passwd.byuid YP map.
     This is in	addition to the	passwd file, and respects the order of both
     normal and	YP entries in the passwd file.

RETURN VALUES
     The functions getpwnam(), getpwnam_shadow(), getpwuid(), and
     getpwuid_shadow() return a	pointer	to a passwd structure if a match is
     found or a	null pointer if	no match is found or an	error occurs.  Subse-
     quent calls to getpwent(),	getpwnam(), getpwnam_shadow(), getpwuid() or
     getpwuid_shadow() may invalidate the returned pointer or overwrite	the
     contents of the passwd structure it points	to.

     The functions getpwnam_r()	and getpwuid_r() update	result to point	to
     pwstore if	a match	is found or set	it to NULL if no match is found	or an
     error occurs.  They return	0 on success, even if no match is found, or an
     error number if an	error occurs; see ERRORS.

     The setpassent() function returns 0 on failure or 1 on success.

FILES
     /etc/pwd.db	 insecure password database file
     /etc/spwd.db	 secure	password database file
     /etc/master.passwd	 current password file
     /etc/passwd	 legacy	password file

ERRORS
     The getpwnam_r() and getpwuid_r() functions may fail if:

     [ERANGE]		The storage supplied via buf and bufsize is too	small
			and cannot contain all the strings to be returned in
			pwstore.

     The getpwnam(), getpwnam_r(), getpwuid(), and getpwuid_r()	functions may
     also fail for any of the errors specified for dbopen(3) and its get()
     routine.

     If	YP is active, they may also fail due to	errors caused by the YP	sub-
     system.

SEE ALSO
     getlogin(2), getgrent(3), getgrouplist(3),	getpwent(3), pw_dup(3),
     sysconf(3), passwd(5), Makefile.yp(8), pwd_mkdb(8), vipw(8), yp(8)

STANDARDS
     The getpwnam(), getpwnam_r(), getpwuid(), and getpwuid_r()	functions are
     compliant with the	IEEE Std 1003.1-2008 ("POSIX.1") specification.

     YP	support	and the	setpassent() function are extensions to	that specifi-
     cation.

HISTORY
     A predecessor to getpwuid(), getpw(), first appeared in Version 4 AT&T
     UNIX.  The	getpwnam() and getpwuid() functions appeared in	Version	7 AT&T
     UNIX, setpassent()	in 4.3BSD-Reno,	and getpwnam_shadow() and
     getpwuid_shadow() in OpenBSD 5.9.

FreeBSD	13.0			August 21, 2018			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | FILES | ERRORS | SEE ALSO | STANDARDS | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getpwnam&sektion=3&manpath=OpenBSD+6.9>

home | help