getspwent(3X)															     getspwent(3X)

NAME

       getspwent(),  getspwuid(),  getspwaid(),  getspwnam(), setspwent(), endspwent(), fgetspwent(), getspwent_r(), getspwuid_r(), getspwaid_r(),
       getspwnam_r(), setspwent_r(), endspwent_r(), fgetspwent_r() - get secure password file entry on trusted systems

SYNOPSIS

   Obsolescent Interfaces
       The following re-entrant interfaces are to be obsoleted:

DESCRIPTION

       These privileged routines provide access to the protected password database in a manner similar to the way getpwent(3C) routines handle the
       regular password file,

       These  routines	are particularly useful in situations where it is not necessary to get information from the regular password file.  getsp-
       went(3X) can be used on a trusted system to return the password, audit ID, and audit flag information.  Programs using these routines  must
       be linked with the security library,

       Note  that  routines  are  no longer supported.	They are temporarily available for backward compatibility.  New applications accessing the
       protected password database on trusted systems should use the routines.	See getprpwent(3).

       and each returns a pointer to an object of s_passwd structure.  The s_passwd structure is maintained for compatibility with existing  soft-
       ware and consists of five fields as follows:

       Since the s_passwd structure is declared in the header file, it is unnecessary to redeclare it.

       To  access  other fields in the protected password database that are not included in the s_passwd structure, use See getprpwent(3) for more
       information.

       When first called,  returns a pointer to each s_passwd structure obtained from the protected password database for each user  in  sequence.
			   Subsequent calls can be used to search the entire database.

       Searches for an entry that matches the specified
			   uid.  It then returns a pointer to the particular structure in which uid is found.

       Similarly searches for a numerical audit
			   ID  matching  aid and returns a pointer to the particular structure in which aid is found (see passwd(4) for details on
			   this field).

       Searches for an entry that matches the specified
			   name.  Returns a pointer to the particular structure in which name is found.

       Resets the protected password database pointer to the beginning of the
			   file to allow repeated searches.

       Should be called to close the protected password database file
			   when processing is complete.

       Is no longer supported. It is provided for those applications that
			   did not use

   Reentrant Interfaces
       and expect to be passed three extra parameters:

       1. The address of an s_passwd structure where the result will be stored;

       2. A buffer to store character strings (such as the password) to which fields in the s_passwd structure will point;

       3. The length of the user-supplied buffer.  A buffer length of 1024 is recommended.

       In addition to the above three parameters, requires a pointer to a variable.  and are to be used only in conjunction with and take the same
       pointer	to a variable as a parameter.  can be used to rewind or open the protected password database.  should be called when done to close
       the file.

       Note that the variable must be initialized to NULL before it is passed to or for the first time.  Thereafter it should not be  modified	in
       any way.

       and are to be obsoleted at a future date.

APPLICATION USAGE

       In  a  multithreaded  application,  these  routines  are safe to be called only from one dedicated thread.  These routines are not POSIX.1c
       async-cancel safe nor async-signal safe.

RETURN VALUE

       returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the  call-
       ing process is not zero.

       returns	a  -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length.  If the opera-
       tion is successful, 0 is returned.

WARNINGS

       The above routines use which causes them to increase the size of programs by more than might otherwise be expected.

       Since all information for and is contained in a static area, it must be copied to be saved.

       Network Information Service is not supported on trusted systems.

       The routines described in this manpage are no longer supported.	They are temporarily available for backward compatibility and  are  to	be
       obsoleted.

   Obsolescent Interfaces
       The following interfaces are to be obsoleted: and

       HP-UX 11i Version 3 is the last release to support trusted systems functionality.

EXAMPLES

       The following code excerpt counts the number of entries in the protected password database:

AUTHOR

       was developed by HP.

FILES

       Protected Password database

SEE ALSO

       ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), passwd(4).

								  TO BE OBSOLETED						     getspwent(3X)