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

FreeBSD Manual Pages


home | help
getpwnam(3C)		 Standard C Library Functions		  getpwnam(3C)

       getpwnam, getpwnam_r, getpwent, getpwent_r, getpwuid, getpwuid_r, setp-
       went, endpwent, fgetpwent, fgetpwent_r -	get password entry

       #include	<pwd.h>

       struct passwd *getpwnam(const char *name);

       struct passwd *getpwnam_r(const char *name, struct  passwd  *pwd,  char
       *buffer,	int buflen);

       struct passwd *getpwent(void);

       struct  passwd  *getpwent_r(struct  passwd  *pwd, char *buffer, int bu-

       struct passwd *getpwuid(uid_t uid);

       struct passwd *getpwuid_r(uid_t uid, struct passwd *pwd,	char  *buffer,
       int buflen);

       void setpwent(void);

       void endpwent(void);

       struct passwd *fgetpwent(FILE *f);

       struct  passwd  *fgetpwent_r(FILE *f, struct passwd *pwd, char *buffer,
       int buflen);

       cc [ flag...] file... -D_POSIX_PTHREAD_SEMANTICS	[ library... ]

       int getpwnam_r(const char *name,	 struct	 passwd	 *pwd,	char  *buffer,
       size_t bufsize, struct passwd **result);

       int getpwuid_r(uid_t uid, struct	passwd *pwd, char *buffer, size_t buf-
       size, struct passwd **result);

       These functions are used	to obtain password entries. Entries  can  come
       from  any of the	sources	for passwd specified in	the /etc/nsswitch.conf
       file (see nsswitch.conf(4)).

       The getpwnam() function searches	for a password entry  with  the	 login
       name specified by the character string parameter	name.

       The  getpwuid()	function  searches  for	a password entry with the (nu-
       meric) user ID specified	by the parameter uid.

       The  setpwent(),	getpwent(), and	endpwent() functions are used to  enu-
       merate  password	entries	from the database. setpwent() sets (or resets)
       the enumeration to the beginning	of the set of password entries.	  This
       function	should be called before	the first call to getpwent(). Calls to
       getpwnam() and getpwuid() leave the enumeration position	in an indeter-
       minate  state.  Successive calls	to getpwent() return either successive
       entries or NULL,	indicating the end of the enumeration.

       The endpwent() function may be called to	indicate that the  caller  ex-
       pects  to  do  no further password retrieval operations;	the system may
       then  close the password	file, deallocate resources it was  using,  and
       so  forth.   It	is still allowed, but possibly less efficient, for the
       process to call more password functions after calling endpwent().

       The fgetpwent() function, unlike	the other functions  above,  does  not
       use nsswitch.conf; it reads and parses the next line from the stream f,
       which is	assumed	to have	the format of the passwd file.	See passwd(4).

   Reentrant Interfaces
       The functions getpwnam(), getpwuid(), getpwent(), and  fgetpwent()  use
       static  storage	that is	reused in each call, making these routines un-
       safe for	use in multithreaded applications.

       The parallel functions getpwnam_r(),  getpwuid_r(),  getpwent_r(),  and
       fgetpwent_r() provide reentrant interfaces for these operations.

       Each  reentrant	interface performs the same operation as its non-reen-
       trant counterpart, named	by removing the	"_r"  suffix.	The  reentrant
       interfaces,  however,  use  buffers supplied by the caller to store re-
       turned results, and  are	safe for use in	both single-threaded and  mul-
       tithreaded applications.

       Each reentrant interface	takes the same parameters as its non-reentrant
       counterpart, as well as the following additional	parameters.   The  pa-
       rameter pwd must	be a pointer to	a struct passwd	structure allocated by
       the caller.  On successful completion, the function returns  the	 pass-
       word  entry  in	this structure.	The parameter buffer is	a pointer to a
       buffer supplied by the caller, used as storage space for	 the  password
       data.   All of the pointers within the returned struct passwd pwd point
       to data stored within this buffer; see RETURN VALUES. The  buffer  must
       be  large  enough to hold all the data associated with the password en-
       try.  The parameter buflen (or bufsize  for  the	 POSIX	versions;  see
       standards(5))  should  give the size in bytes of	buffer.	The POSIX ver-
       sions place a pointer to	the modified pwd structure in the  result  pa-
       rameter,	instead	of returning a pointer to this structure.

       For  enumeration	in multithreaded applications, the position within the
       enumeration is a	process-wide property shared by	all threads. The setp-
       went()  function	 may be	used in	a multithreaded	application but	resets
       the enumeration position	for all	threads.  If multiple  threads	inter-
       leave  calls  to	getpwent_r(), the threads will enumerate disjoint sub-
       sets of the password database.

       Like their non-reentrant	counterparts,  getpwnam_r()  and  getpwuid_r()
       leave the enumeration position in an indeterminate state.

       Password	entries	are represented	by the struct passwd structure defined
       in <pwd.h>:

       struct passwd {
	   char	*pw_name;      /* user's login name */
	   char	*pw_passwd;    /* no longer used */
	   uid_t pw_uid;       /* user's uid */
	   gid_t pw_gid;       /* user's gid */
	   char	*pw_age;       /* not used */
	   char	*pw_comment;   /* not used */
	   char	*pw_gecos;     /* typically user's full	name */
	   char	*pw_dir;       /* user's home dir */
	   char	*pw_shell;     /* user's login shell */

       The pw_passwd member should not be used as the encrypted	 password  for
       the user; use getspnam()	or getspnam_r()	instead.  See  getspnam(3C).

       The  getpwnam(),	 getpwnam_r(),	getpwuid(), and	getpwuid_r() functions
       each return a pointer to	a struct passwd	if  they  successfully	locate
       the  requested  entry; otherwise	they return NULL. Upon successful com-
       pletion (including the case when	the requested entry is not found), the
       POSIX  functions	 getpwnam_r() and getpwuid_r() return 0. Otherwise, an
       error number is returned	to indicate the	error.

       The getpwent(), getpwent_r(), fgetpwent(), and fgetpwent_r()  functions
       each return a pointer to	a struct passwd	if they	successfully enumerate
       an entry; otherwise they	return NULL, indicating	the end	of the enumer-

       The  getpwnam(),	 getpwuid(), getpwent(), and fgetpwent() functions use
       static storage, so returned data	must be	 copied	 before	 a  subsequent
       call to any of these functions if the data is to	be saved.

       When the	pointer	returned by the	reentrant functions getpwnam_r(), get-
       pwuid_r(), getpwent_r(),	and fgetpwent_r() is non-null,	it  is	always
       equal to	the pwd	pointer	that was supplied by the caller.

       The  reentrant functions	 getpwnam_r(), getpwuid_r(), getpwent_r(), and
       fgetpwent_r() will return NULL and set errno to ERANGE (or in the  case
       of  POSIX functions getpwnam_r()	and getpwuid_r() return	the ERANGE er-
       ror) if the length of the buffer	supplied by caller is not large	enough
       to store	the result.  See Intro(2) for the proper usage and interpreta-
       tion of errno in	multithreaded applications.

       Applications that use the interfaces described on this manual page can-
       not  be linked statically, since	the implementations of these functions
       employ dynamic loading and linking of shared objects at run time.

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |MT-Level		     |See "Reentrant  Interfaces"  |
       |			     |in DESCRIPTION.		   |

       nispasswd(1),  passwd(1), yppasswd(1), Intro(2),	Intro(3), cuserid(3C),
       getgrnam(3C), getlogin(3C), getspnam(3C), nsswitch.conf(4),  passwd(4),
       shadow(4), attributes(5), standards(5)

       When  compiling	multithreaded  programs, see Intro(3), Notes On	Multi-
       threaded	Applications.

       Use of the enumeration interfaces getpwent() and	getpwent_r()  is  dis-
       couraged;  enumeration is supported for the passwd file,	NIS, and NIS+,
       but in general is not efficient and may not be supported	for all	 data-
       base  sources.	The  semantics of enumeration are discussed further in

       Previous	releases allowed the use of `+'	and `-'	entries	in /etc/passwd
       to  selectively	include	 and exclude NIS entries. The primary usage of
       these `+/-' entries is superseded by the	name service  switch,  so  the
       `+/-' form may not be supported in future releases.

       If  required,  the `+/-'	functionality can still	be obtained for	NIS by
       specifying compat as the	source for passwd.

       If the `+/-' functionality is required in conjunction with NIS+,	 spec-
       ify  both compat	as the source for passwd and nisplus as	the source for
       the pseudo-database passwd_compat. See passwd(4), shadow(4),  and  nss-
       witch.conf(4) for details.

       If  the `+/-' is	used, both /etc/shadow and /etc/passwd should have the
       same `+'	and `-'	entries	to ensure consistency between the password and
       shadow databases.

       If  a  password	entry from any of the sources contains an empty	uid or
       gid field, that entry will be ignored by	the files, NIS , and NIS+ name
       service switch backends.	 This will cause the user to appear unknown to
       the system.

       If a password entry contains an empty gecos, home directory,  or	 shell
       field, getpwnam() and getpwnam_r() return a pointer to a	null string in
       the respective field of the passwd structure.

       If the shell field is empty, login(1) automatically assigns the default
       shell.  See login(1).

       Solaris	2.4  and  earlier  releases provided definitions of the	getpw-
       nam_r() and getpwuid_r()	functions as specified in  POSIX.1c  Draft  6.
       The  final POSIX.1c standard changed the	interface for these functions.
       Support for the Draft 6 interface is provided  for  compatibility  only
       and  may	 not be	supported in future releases. New applications and li-
       braries should use the POSIX standard interface.

       For POSIX.1c-compliant applications, the	 _POSIX_PTHREAD_SEMANTICS  and
       _REENTRANT   flags   are	  automatically	 turned	 on  by	 defining  the
       _POSIX_C_SOURCE flag with a value >= 199506L.

SunOS 5.9			  18 May 1999			  getpwnam(3C)


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

home | help