Manual Pages for UNIX Operating System command usage for man getspent_r

Standard C Library Functions                         getspnam(3C)



NAME
     getspnam,  getspnam_r,   getspent,   getspent_r,   setspent,
     endspent, fgetspent, fgetspent_r - get password entry

SYNOPSIS
     #include 

     struct spwd *getspnam(const char *name);


     struct spwd *getspnam_r(const char *name, struct spwd *result,
          char *buffer, int buflen);


     struct spwd *getspent(void);


     struct spwd *getspent_r(struct spwd *result, char *buffer,
          int buflen);


     void setspent(void);


     void endspent(void);


     struct spwd *fgetspent(FILE *fp);


     struct spwd *fgetspent_r(FILE *fp, struct spwd *result,
          char *buffer, int buflen);


DESCRIPTION
     These functions are used to obtain shadow password  entries.
     An  entry may come from any of the sources for shadow speci-
     fied in the /etc/nsswitch.conf file (see nsswitch.conf(4)).


     The getspnam() function searches for a shadow password entry
     with  the login name specified by the character string argu-
     ment name.


     The  setspent(), getspent(), and  endspent()  functions  are
     used to enumerate shadow password entries from the database.


     The setspent() function sets (or resets) the enumeration  to
     the  beginning  of the set of shadow password entries.  This
     function  should  be  called  before  the  first   call   to



SunOS 5.11          Last change: 10 Dec 2009                    1






Standard C Library Functions                         getspnam(3C)



     getspent().  Calls to getspnam() leave the enumeration posi-
     tion in an indeterminate state.


     Successive calls  to  getspent()  return  either  successive
     entries or NULL, indicating the end of the enumeration.


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


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

  Reentrant Interfaces
     The  getspnam(), getspent(), and fgetspent()  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  getspnam_r(), getspent_r(), and fgetspent_r() functions
     provide reentrant interfaces for these operations.


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


     Each reentrant interface takes  the  same  argument  as  its
     non-reentrant  counterpart,  as  well as the following addi-
     tional arguments.  The result argument must be a pointer  to
     a  struct  spwd  structure allocated by the caller.  On suc-
     cessful completion, the function returns the shadow password
     entry  in  this  structure.  The   buffer argument must be a
     pointer to a buffer supplied by the caller.  This buffer  is
     used  as storage space for the shadow password data.  All of
     the pointers within the returned struct spwd result point to
     data  stored  within  this  buffer  (see RETURN VALUES). The
     buffer must be large enough to hold all of the data  associ-
     ated  with  the  shadow  password entry. The buflen argument



SunOS 5.11          Last change: 10 Dec 2009                    2






Standard C Library Functions                         getspnam(3C)



     should give the size in bytes of  the  buffer  indicated  by
     buffer.


     For enumeration in multithreaded applications, the  position
     within  the enumeration is a process-wide property shared by
     all threads. The setspent() function may be used in  a  mul-
     tithreaded  application  but resets the enumeration position
     for all threads.  If multiple threads  interleave  calls  to
     getspent_r(), the threads will enumerate disjoint subsets of
     the shadow password database.


     Like its non-reentrant counterpart, getspnam_r() leaves  the
     enumeration position in an indeterminate state.

RETURN VALUES
     Password entries are represented by the struct  spwd  struc-
     ture defined in :

       struct spwd{
           char           *sp_namp;     /* login name */
           char           *sp_pwdp;     /* encrypted passwd */
           int            sp_lstchg;    /* date of last change */
           int            sp_min;       /* min days to passwd change */
           int            sp_max;       /* max days to passwd change*/
           int            sp_warn;      /* warning period */
           int            sp_inact;     /* max days inactive */
           int            sp_expire;    /* account expiry date */
           unsigned int   sp_flag;      /* not used */
       };



     See shadow(4) for more information on the interpretation  of
     this data.


     The  getspnam()and  getspnam_r()  functions  each  return  a
     pointer  to  a  struct  spwd if they successfully locate the
     requested entry; otherwise they return NULL.


     The  getspent(), getspent_r(), fgetspent(), and  fgetspent()
     functions  each  return  a  pointer to a struct spwd if they
     successfully enumerate an entry; otherwise they return NULL,
     indicating the end of the enumeration.


     The  getspnam(), getspent(), and fgetspent()  functions  use
     thread-specific  data  storage,  so  returned  data  must be
     copied before a subsequent call to any of these functions if



SunOS 5.11          Last change: 10 Dec 2009                    3






Standard C Library Functions                         getspnam(3C)



     the data is to be saved.


     When  the  pointer  returned  by  the  reentrant   functions
     getspnam_r(),  getspent_r(),  and fgetspent_r() is non-null,
     it is always equal to the result pointer that  was  supplied
     by the caller.

ERRORS
     The reentrant  functions   getspnam_r(),  getspent_r(),  and
     fgetspent_r()  will  return  NULL and set errno to ERANGE 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 interpretation of errno in multithreaded  applica-
     tions.

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



     ____________________________________________________________
   |        ATTRIBUTE TYPE       |        ATTRIBUTE VALUE      |
   | ____________________________|_____________________________|_
   |  MT-Level                   |  See "Reentrant  Interfaces"|
   |                             |  in DESCRIPTION.            |
   |_____________________________|_____________________________|


SEE ALSO
     passwd(1),     yppasswd(1),     Intro(3),      getlogin(3C),
     getpwnam(3C), nsswitch.conf(4), passwd(4), shadow(4), attri-
     butes(5)

WARNINGS
     The reentrant  interfaces  getspnam_r(),  getspent_r(),  and
     fgetspent_r() are included in this release on an uncommitted
     basis only, and are subject to change or removal  in  future
     minor releases.

NOTES
     When compiling  multithreaded  applications,  see  Intro(3),
     Notes  On  Multithreaded Applications, for information about
     the use of the _REENTRANT flag.


     Use   of   the   enumeration   interfaces   getspent()   and
     getspent_r()  is  not  recommended; enumeration is supported
     for the shadow file and NIS, but in general is not efficient
     and  may  not  be  supported  for all database sources.  The
     semantics  of   enumeration   are   discussed   further   in



SunOS 5.11          Last change: 10 Dec 2009                    4






Standard C Library Functions                         getspnam(3C)



     nsswitch.conf(4).


     Access to shadow password information may be restricted in a
     manner  depending on the database source being used.  Access
     to the /etc/shadow file is generally restricted to processes
     running  with  the  effective  uid  of the file owner or the
     {PRIV_FILE_DAC_READ} privilege.  Other database sources  may
     impose stronger or less stringent restrictions.


     Empty fields in the database source return -1 values for all
     fields  except sp_pwdp and sp_flag, where the value returned
     is 0.


     When NIS is used as the database  source,   the  information
     for  the  shadow  password  entries  is  obtained  from  the
     ``passwd.byname'' map. This map stores only the  information
     for the sp_namp and sp_pwdp fields of the struct spwd struc-
     ture. Shadow password entries obtained from NIS will contain
     the value -1 in the remainder of the fields.

































SunOS 5.11          Last change: 10 Dec 2009                    5