SHADOW(3) Library Calls SHADOW(3)

.SH "NAME" shadow, getspnam - encrypted password file routines

.SH "SYNTAX"

.PP *#include <shadow.h>*

.PP *struct spwd \*getspent();*

.PP *struct spwd \*getspnam(char* *\*name);*

.PP *void setspent();*

.PP *void endspent();*

.PP *struct spwd \*fgetspent(FILE* *\*fp);*

.PP *struct spwd \*sgetspent(char* *\*cp);*

.PP *int putspent(struct spwd* *\*p,* *FILE* *\*fp);*

.PP *int lckpwdf();*

.PP *int ulckpwdf();*

.SH "DESCRIPTION"

.PP *shadow* manipulates the contents of the shadow password file, /etc/shadow. The structure in the *#include* file is:

```
struct spwd {


      char		*sp_namp; /* user login name */


      char		*sp_pwdp; /* encrypted password */


      long int		sp_lstchg; /* last password change */


      long int		sp_min; /* days until change allowed. */


      long int		sp_max; /* days before change required */


      long int		sp_warn; /* days warning for expiration */


      long int		sp_inact; /* days before account inactive */


      long int		sp_expire; /* date when account expires */


      unsigned long int	sp_flag; /* reserved for future use */
}


    
```

.PP The meanings of each field are:

• sp\_namp - pointer to null-terminated user name

.RE

• sp\_pwdp - pointer to null-terminated password

.RE

• sp\_lstchg - days since Jan 1, 1970 password was last changed

.RE

• sp\_min - days before which password may not be changed

.RE

• sp\_max - days after which password must be changed

.RE

• sp\_warn - days before password is to expire that user is warned of pending password expiration

.RE

• sp\_inact - days after password expires that account is considered inactive and disabled

.RE

• sp\_expire - days since Jan 1, 1970 when account will be disabled

.RE

• sp\_flag - reserved for future use

.RE

.SH "DESCRIPTION"

.PP *getspent*, *getspname*, *fgetspent*, and *sgetspent* each return a pointer to a *struct spwd*. *getspent* returns the next entry from the file, and *fgetspent* returns the next entry from the given stream, which is assumed to be a file of the proper format. *sgetspent* returns a pointer to a *struct spwd* using the provided string as input. *getspnam* searches from the current position in the file for an entry matching *name*.

.PP *setspent* and *endspent* may be used to begin and end, respectively, access to the shadow password file.

.PP The *lckpwdf* and *ulckpwdf* routines should be used to insure exclusive access to the /etc/shadow file. *lckpwdf* attempts to acquire a lock using *pw\_lock* for up to 15 seconds. It continues by attempting to acquire a second lock using *spw\_lock* for the remainder of the initial 15 seconds. Should either attempt fail after a total of 15 seconds, *lckpwdf* returns -1. When both locks are acquired 0 is returned.

.SH "DIAGNOSTICS"

.PP Routines return NULL if no more entries are available or if an error occurs during processing. Routines which have *int* as the return value return 0 for success and -1 for failure.

.SH "CAVEATS"

.PP These routines may only be used by the superuser as access to the shadow password file is restricted.

.SH "FILES"

.PP /etc/shadow

Secure user account information.

.RE

.SH "SEE ALSO"

.PP [**getpwent**(3)](/man/os/shadow/getpwent.3), [**shadow**(5)](/man/os/shadow/shadow.5).

10/26/2026 shadow-utils 4.20.3

---

Document: shadow(3) from shadow 4.20.3-r2 (Chainguard OS)
Source: https://github.com/shadow-maint/shadow