setpwent man page on OpenIndiana

Man page or keyword search:  
man Server   20441 pages
apropos Keyword Search (all sections)
Output format
OpenIndiana logo
[printable version]

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

       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 bufsize, 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
       (numeric) 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
       entries.	 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
       expects 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
       recommended 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
       interfaces,  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 multithreaded 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.

       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 non-
       reentrant  functions  return  a	null pointer and errno is non-zero, an
       error occurred.

       The standard-conforming functions  getpwnam_r()	and  getpwuid_r()  can
       return 0 even on an error, particularly in the case where the requested
       entry is not found. The application needs to check the return value and
       that the pwd pointer is non-null. Otherwise, an error value 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 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.

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	     │Committed				       │
       ├─────────────────────────────┼─────────────────────────────────────────┤
       │MT-Level		     │See Reentrant Interfaces in DESCRIPTION. │
       ├─────────────────────────────┼─────────────────────────────────────────┤
       │Standard		     │See below.			       │
       └─────────────────────────────┴─────────────────────────────────────────┘

       For endpwent(),	getpwent(),   getpwnam(),   getpwnam_r(),  getpwuid(),
       getpwuid_r(), and setpwent(), see standards(5).

SEE ALSO
       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 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  nss‐
       witch.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 `+/-' 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 and NIS name service
       switch backends, causing 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 might not be supported in future  releases.	New  applications  and
       libraries 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.11			  10 Dec 2009			  getpwnam(3C)
[top]

List of man pages available for OpenIndiana

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net