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

FreeBSD Manual Pages


home | help
GETPWENT(3)		 BSD Library Functions Manual		   GETPWENT(3)

     getpwent, getpwent_r, getpwnam, getpwnam_r, getpwuid, getpwuid_r,
     setpassent, setpwent, endpwent -- password	database operations

     Standard C	Library	(libc, -lc)

     #include <pwd.h>

     struct passwd *

     getpwent_r(struct passwd *pw, char	*buffer, size_t	buflen,
	 struct	passwd **result);

     struct passwd *
     getpwnam(const char *name);

     getpwnam_r(const char *name, struct passwd	*pw, char *buffer,
	 size_t	buflen,	struct passwd **result);

     struct passwd *
     getpwuid(uid_t uid);

     getpwuid_r(uid_t uid, struct passwd *pw, char *buffer, size_t buflen,
	 struct	passwd **result);

     setpassent(int stayopen);



     These functions operate on	the password database which is described in
     passwd(5).	 Each entry in the database is defined by the structure	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 login class */
		   char	   *pw_gecos;	   /* general information */
		   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 user name pointed to by name or user id pointed to by uid re-
     spectively, always	returning the first one	encountered.  Identical	user
     names or user ids may result in undefined behavior.

     The getpwent() function sequentially reads	the password database and is
     intended for programs that	wish to	process	the complete list of users.

     The functions getpwnam_r(), getpwuid_r(), and getpwent_r()	act like their
     non re-entrant counterparts, updating the contents	of pw and storing a
     pointer to	that in	result,	and returning 0.  Storage used by pw is	allo-
     cated from	buffer,	which is buflen	bytes in size.	If the requested entry
     cannot be found, result will point	to NULL	and 0 will be returned.	 If an
     error occurs, a non-zero error number will	be returned and	result will
     point to NULL.  Calling getpwent_r() from multiple	threads	will result in
     each thread reading a disjoint portion of the password database.

     The setpassent() function accomplishes two	purposes.  First, it causes
     getpwent()	to "rewind" to the beginning of	the database.  Additionally,
     if	stayopen is non-zero, file descriptors are left	open, significantly
     speeding up subsequent accesses for all of	the functions.	(This latter
     functionality is unnecessary for getpwent() as it doesn't close its file
     descriptors by default.)

     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.

     The setpwent() function is	equivalent to setpassent() with	an argument of

     The endpwent() function closes any	open files.

     These functions have been written to "shadow" the password	file, e.g. al-
     low only certain programs to have access to the encrypted password.  If
     the process which calls them has an effective uid of 0, the encrypted
     password will be returned,	otherwise, the password	field of the returned
     structure will point to the string	`*'.

     The functions getpwent(), getpwnam(), and getpwuid(), return a valid
     pointer to	a passwd structure on success and a NULL pointer if the	entry
     was not found or an error occured.	 If an error occured, the global vari-
     able errno	is set to indicate the nature of the failure.  The
     setpassent() function returns 0 on	failure, setting the global variable
     errno to indicate the nature of the failure, and 1	on success.  The
     endpwent()	and setpwent() functions have no return	value.	The functions
     getpwnam_r(), getpwuid_r(), and getpwent_r() return 0 on success or entry
     not found,	and non-zero on	failure, setting the global variable errno to
     indicate the nature of the	failure.

     /etc/pwd.db	 The insecure password database	file
     /etc/spwd.db	 The secure password database file
     /etc/master.passwd	 The current password file
     /etc/passwd	 A Version 7 format password file

     The historic function setpwfile() which allowed the specification of al-
     ternative password	databases, has been deprecated and is no longer	avail-

     The following error codes may be set in errno for getpwent, getpwent_r,
     getpwnam, getpwnam_r, getpwuid, getpwuid_r, and setpassent:

     [EINTR]		A signal was caught during the database	search.

     [EIO]		An I/O error has occurred.

     [EMFILE]		The limit on open files	for this process has been

     [ENFILE]		The system limit on open files has been	reached.

     The following error code may be set in errno for getpwent_r, getpwnam_r,
     and getpwuid_r:

     [ERANGE]		The resulting struct passwd does not fit in the	space
			defined	by buffer and buflen

     Other errno values	may be set depending on	the specific database back-

     getlogin(2), getgrent(3), nsswitch.conf(5), passwd(5), passwd.conf(5),
     pwd_mkdb(8), vipw(8)

     The getpwnam() and	getpwuid(), functions conform to ISO/IEC 9945-1:1990
     ("POSIX.1").  The getpwnam_r() and	getpwuid_r() functions conform to IEEE
     Std 1003.1c-1995 ("POSIX.1").  The	endpwent(), getpwent(),	and setpwent()
     functions conform to X/Open Portability Guide Issue 4, Version 2
     ("XPG4.2")	and IEEE Std 1003.1-2004 ("POSIX.1") (XSI extension).

     The getpwent, getpwnam, getpwuid, setpwent, and endpwent functions	ap-
     peared in Version 7 AT&T UNIX.  The setpassent function appeared in
     4.3BSD-Reno.  The functions getpwnam_r() and getpwuid_r() appeared	in
     NetBSD 3.0.

     The functions getpwent(), getpwnam(), and getpwuid(), leave their results
     in	an internal static object and return a pointer to that object.	Subse-
     quent calls to any	of these functions will	modify the same	object.

     The functions getpwent(), endpwent(), setpassent(), and setpwent()	are
     fairly useless in a networked environment and should be avoided, if pos-
     sible.  getpwent()	makes no attempt to suppress duplicate information if
     multiple sources are specified in nsswitch.conf(5).

BSD				April 30, 2008				   BSD


Want to link to this manual page? Use this URL:

home | help