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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
       #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-
       flen);

       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);

   Standard conforming
       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);

DESCRIPTION
       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 uid parameter.

       The setpwent(), getpwent(), and endpwent() functions are	used  to  enu-
       merate password entries from the	database. The setpwent() function sets
       (or resets) the enumeration to the beginning of the set of password en-
       tries.	This  function should be called	before the first call to getp-
       went(). Calls to	getpwnam() and getpwuid() leave	the enumeration	 posi-
       tion  in	 an indeterminate state. Successive calls to getpwent()	return
       either successive entries or a null pointer, 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 but 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  getpwnam(),	 getpwuid(), getpwent(), and fgetpwent() functions use
       thread-specific data storage that is reused in  each  call  to  one  of
       these  functions	 by  the  same thread, making them safe	to use but not
       recommeded for 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 in-
       terfaces, however, use buffers supplied by the caller to	store returned
       results instead of using	thread-specific	data that can  be  overwritten
       by  each	call. They are safe for	use in both single-threaded and	multi-
       threaded	applications.

       Each reentrant interface	takes the same parameters as its non-reentrant
       counterpart,  as	 well  as the following	additional parameters. The pwd
       parameter must be a pointer to a	struct passwd structure	 allocated  by
       the caller. On successful completion, the function returns the password
       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 pointers within the returned	struct passwd pwd point	to data	stored
       within  this  buffer;  see  passwd  Structure below. The	buffer must be
       large enough to hold all	the data associated with the  password	entry.
       The  parameter buflen (or bufsize for the standard-conforming versions;
       see standards(5)) should	give the size in bytes of buffer. The  maximum
       size   needed   for   this   buffer   can   be	determined   with  the
       {_SC_GETPW_R_SIZE_MAX} sysconf(3C) parameter.  The  standard-conforming
       versions	 place	a  pointer to the modified pwd structure in the	result
       parameter, instead of returning a pointer to  this  structure.  A  null
       pointer is returned at the location pointed to by result	on error or if
       the requested entry is not found.

       For enumeration in multithreaded	applications, the position within  the
       enumeration is a	process-wide property shared by	all threads. The setp-
       went() function can 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.

   passwd Structure
       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).

RETURN VALUES
       The getpwnam(), getpwnam_r(), getpwuid(),  and  getpwuid_r()  functions
       each  return  a	pointer	to a struct passwd if they successfully	locate
       the requested entry. A null pointer is returned if the requested	 entry
       is  not	found,	or an error occurs. On error, errno is set to indicate
       the error. Upon successful completion (including	the case when the  re-
       quested	entry  is not found), the standard-conforming functions	getpw-
       nam_r() and getpwuid_r()	return 0. Otherwise, an	error  number  is  re-
       turned 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 a null pointer on end-of-file or	error.
       On error, errno is set to indicate the error.

       See Intro(2) for	the proper usage and interpretation of errno in	multi-
       threaded	applications.

       The  getpwnam(),	 getpwuid(), getpwent(), and fgetpwent() functions use
       thread-specific data 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.

       Applications  wishing to	check for error	situations should set errno to
       0 before	calling	getpwnam(),  getpwnam_r(),  getpwuid(),	 getpwuid_r(),
       getpwent(),  getpwent_r(),  fgetpwent(),	 and  fgetpwent_r().  If these
       functions return	a null pointer and errno is  non-zero,	an  error  oc-
       curred.

ERRORS
       The  getpwent_r(),  fgetpwent(),	 and fgetpwent_r() functions will fail
       if:

       EIO	An I/O error has occurred.

       ERANGE	Insufficient storage was supplied by  buffer  and  bufsize  to
		contain	 the  data  to	be  referenced by the resulting	passwd
		structure.

       The getpwent_r()	function will fail if:

       EMFILE	There are {OPEN_MAX} file descriptors currently	 open  in  the
		calling	process.

       ENFILE	The maximum allowable number of	files is currently open	in the
		system.

       The getpwnam(),	getpwnam_r(),  getpwuid(),  getpwuid_r(),  getpwent(),
       setpwent(), and endpwent() functions may	fail if:

       EIO	An I/O error has occurred.

       The getpwnam(), getpwnam_r(), getpwuid(), getpwuid_r(), getpwent(), and
       setpwent() functions may	fail if:

       EMFILE	There are {OPEN_MAX} file descriptors currently	 open  in  the
		calling	process.

       ENFILE	The maximum allowable number of	files is currently open	in the
		system.

       The getpwnam(), getpwnam_r(), getpwuid(),  and  getpwuid_r()  functions
       may fail	if:

       EINTR	A signal was caught during the execution of the	function call.

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

       ERANGE	Insufficient  storage  was  supplied  by buffer	and bufsize to
		contain	the data to be	referenced  by	the  resulting	passwd
		structure.

USAGE
       Three names associated with the current process can be determined: get-
       pwuid(geteuid())	returns	the name associated with the effective user ID
       of the process; getlogin() returns the name associated with the current
       login activity; and getpwuid(getuid()) returns the name associated with
       the real	user ID	of the process.

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |See below.		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |See Reentrant Interfaces in  |
       |			     |DESCRIPTION.		   |
       +-----------------------------+-----------------------------+

       The endpwent(),	getpwent(),   getpwnam(),   getpwnam_r(),  getpwuid(),
       getpwuid_r(), and setpwent() functions  are Standard.

SEE ALSO
       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)

NOTES
       When compiling multithreaded programs, see Intro(3).

       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	might not be supported for all
       database	sources.  The semantics	of enumeration are  discussed  further
       in nsswitch.conf(4).

       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 might	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,	causing	the user to appear unknown to the sys-
       tem.

       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 might not be	supported in future releases. New applications and li-
       braries should use the standard-conforming interface.

       For  POSIX.1c-conforming	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.10			  5 Apr	2004			  getpwnam(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | ATTRIBUTES | SEE ALSO | NOTES

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

home | help