getspent(S)

getspent, getspent_r, getspnam, getspnam_r, setspent, endspent, fgetspent, fgetspent_r -- manipulate shadow password file

Synopsis

   #include <shadow.h>
   
   struct spwd getspent (void);
   

   int getspent_r (struct spwd sp, char buf,
   	size_t len, struct spwd ptr);
   

   struct spwd getspnam (const char name);
   

   int getspnam_r (const char name, struct spwd sp,
   	char buf, size_t len, struct spwd ptr);
   

   int lckpwdf (void);
   

   int ulckpwdf (void);
   

   void setspent (void);
   

   void endspent (void);
   

   struct spwd fgetspent (FILE fp);
   

   int fgetspent_r (FILE fp, struct spwd sp,
   	char buf, size_t len, struct spwd ptr);

Description

getspnam- return pointer to shadow password file entry matching name

getspnam_r- fill in shadow password file entry matching name

fgetspent- return pointer to shadow password entry from next in stream

fgetspent_r- fill in shadow password entry from next in stream

getspent- return pointer to next shadow password entry

getspent_r- fill in spwd structure from next shadow password entry

setspent- rewind shadow password file for repeated searches

endspent- close the shadow password file

lckpwdf- lock password file

ulckpwdf- unlock password file

The getspent and getspnam routines each return a pointer to an object with the following structure containing the broken-out fields of a line in the /etc/shadow file. Each line in the file contains a ``shadow password'' structure, declared in the shadow.h header file:

   struct spwd {
   	char	sp_namp;
   	char	sp_pwdp;
   	long	sp_lstchg;
   	long	sp_min;
   	long	sp_max;
   	long	sp_warn;
   	long	sp_inact;
   	long	sp_expire;
   	unsigned long	sp_flag;
   };

The corresponding reentrant routines getspent_r, and getspnam_r each return zero, set the pointer pointed-to by ptr to be the address of the structure pointed-to by sp, and fill in the structure whose address was passed as sp if there is either a next entry (for getspent_r) or a matching entry (for getspnam_r). Otherwise, they set the pointer pointed-to by ptr to be null and return zero if no entry was found, or a nonzero errno-code if some error occurred. The buf argument points to the start of an array of at least len bytes into which these routines may read the input line and thus store the strings pointed-to by the filled-in structure. If insufficient space is provided, they fail, returning ERANGE.

The getspent routine when first called returns a pointer to the first spwd structure in the file; thereafter, it returns a pointer to the next spwd structure in the file; so successive calls can be used to search the entire file. The same is true for the getspent_r routine except that the objects filled-in are provided by the caller. Note that getspent_r shares the ``current location'' in the file with getspent.

The getspnam routine searches from the beginning of the file until a login name matching name is found, and returns a pointer to the particular structure in which it was found. The same is true for the getspnam_r routine except that the objects filled-in are provided by the caller.

These routines populate the sp_min, sp_max, sp_lstchg, sp_warn, sp_inact, or sp_expire field with -1 or the sp_flag field with 0 if the corresponding field in /etc/shadow is empty.

The nonreentrant routines return a null pointer if end-of-file is encountered on reading, or when an error occurs. In the latter case, errno is set to indicate the error. In particular, errno is set to EINVAL if a malformed entry is processed.

/etc/security/ia/.pwd.lock is the lock file. It is used to coordinate modification access to the password files /etc/passwd and /etc/shadow. lckpwdf and ulckpwdf are routines that are used to gain modification access to the password files, through the lock file. A process first uses lckpwdf to lock the lock file, thereby gaining exclusive rights to modify the /etc/passwd or /etc/shadow password file. Upon completing modifications, a process should release the lock on the lock file via ulckpwdf. This mechanism prevents simultaneous modification of the password files.

lckpwdf attempts to lock the file /etc/security/ia/.pwd.lock within 15 seconds. If unsuccessful, for example, /etc/security/ia/.pwd.lock is already locked, it returns -1. If successful, a return code other than -1 is returned.

ulckpwdf attempts to unlock the file /etc/security/ia/.pwd.lock. If unsuccessful, for example, /etc/security/ia/.pwd.lock is already unlocked, it returns -1. If successful, it returns 0.

A call to the setspent routine has the effect of rewinding the shadow password file to allow repeated searches. The endspent routine may be called to close the shadow password file when processing is complete.

The fgetspent routine returns a pointer to the next spwd structure in the stream fp, which matches the format of /etc/shadow. The same is true for the fgetspent_r routine except that the objects filled-in are provided by the caller.

Files

/etc/shadow,
/etc/passwd,
/etc/security/ia/.pwd.lock

Return values

getspent, getspnam, lckpwdf, ulckpwdf, and fgetspent return a null pointer on EOF or error.

getspent_r, getspnam_r, and fgetspent_r return zero on EOF or a nonzero errno-code on error.

Diagnostics

getspent, getspnam, fgetspent, setspent, and endspent return the following values if the corresponding conditions are detected:

ENOMEM: sufficient space for the entry cannot be allocated.

getspent_r, getspnam_r, and fgetspent_r return the following value if the corresponding condition is detected:

ERANGE: Insufficient storage was supplied in the len bytes of buf to contain the data to be referenced by the resulting shadow password structure.

References

getpwent(S), putpwent(S), putspent(S), nsdispatch(S)

Notices

This routine is for internal use only; compatibility is not guaranteed.

Except for fgetspent and fgetspent_r, these routines use NSS (Name Service Switch) to decide how to process the requested operations. See nsdispatch(S).

For fgetspent, getspent, getspnam, setspent, and endspent, all information is contained in a thread-specific buffers so that calls from separate threads will not interfere. Subsequent calls from the same thread will reuse these buffers, so information must be copied if it is to be saved. Moreover, getspent and getspent_r share the thread-specific current location in the shadow password file.