+++ /dev/null
-.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) and
-.\" Walter Harms (walter.harms@informatik.uni-oldenburg.de)
-.\"
-.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
-.\" Distributed under GPL
-.\" %%%LICENSE_END
-.\"
-.TH GETSPNAM 3 2015-01-22 "GNU" "Linux Programmer's Manual"
-.SH NAME
-getspnam, getspnam_r, getspent, getspent_r, setspent, endspent,
-fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent,
-lckpwdf, ulckpwdf \- get shadow password file entry
-.SH SYNOPSIS
-.nf
-/* General shadow password file API */
-.br
-.B #include <shadow.h>
-.sp
-.BI "struct spwd *getspnam(const char *" name );
-.sp
-.B struct spwd *getspent(void);
-.sp
-.B void setspent(void);
-.sp
-.B void endspent(void);
-.sp
-.BI "struct spwd *fgetspent(FILE *" stream );
-.sp
-.BI "struct spwd *sgetspent(const char *" s );
-.sp
-.BI "int putspent(const struct spwd *" p ", FILE *" stream );
-.sp
-.B int lckpwdf(void);
-.sp
-.B int ulckpwdf(void);
-.sp
-/* GNU extension */
-.br
-.B #include <shadow.h>
-.sp
-.BI "int getspent_r(struct spwd *" spbuf ,
-.br
-.BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp );
-.sp
-.BI "int getspnam_r(const char *" name ", struct spwd *" spbuf ,
-.br
-.BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp );
-.sp
-.BI "int fgetspent_r(FILE *" stream ", struct spwd *" spbuf ,
-.br
-.BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp );
-.sp
-.BI "int sgetspent_r(const char *" s ", struct spwd *" spbuf ,
-.br
-.BI " char *" buf ", size_t " buflen ", struct spwd **" spbufp );
-.fi
-.sp
-.in -4n
-Feature Test Macro Requirements for glibc (see
-.BR feature_test_macros (7)):
-.in
-.sp
-.ad l
-.BR getspent_r (),
-.BR getspnam_r (),
-.BR fgetspent_r (),
-.BR sgetspent_r ():
-.RS 4
-_BSD_SOURCE || _SVID_SOURCE
-.RE
-.ad b
-.SH DESCRIPTION
-Long ago it was considered safe to have encrypted passwords openly
-visible in the password file.
-When computers got faster and people
-got more security-conscious, this was no longer acceptable.
-Julianne Frances Haugh implemented the shadow password suite
-that keeps the encrypted passwords in
-the shadow password database
-(e.g., the local shadow password file
-.IR /etc/shadow ,
-NIS, and LDAP),
-readable only by root.
-.LP
-The functions described below resemble those for
-the traditional password database
-(e.g., see
-.BR getpwnam (3)
-and
-.BR getpwent (3)).
-.\" FIXME . I've commented out the following for the
-.\" moment. The relationship between PAM and nsswitch.conf needs
-.\" to be clearly documented in one place, which is pointed to by
-.\" the pages for the user, group, and shadow password functions.
-.\" (Jul 2005, mtk)
-.\"
-.\" This shadow password setup has been superseded by PAM
-.\" (pluggable authentication modules), and the file
-.\" .I /etc/nsswitch.conf
-.\" now describes the sources to be used.
-.LP
-The
-.BR getspnam ()
-function returns a pointer to a structure containing
-the broken-out fields of the record in the shadow password database
-that matches the username
-.IR name .
-.LP
-The
-.BR getspent ()
-function returns a pointer to the next entry in the shadow password
-database.
-The position in the input stream is initialized by
-.BR setspent ().
-When done reading, the program may call
-.BR endspent ()
-so that resources can be deallocated.
-.\" some systems require a call of setspent() before the first getspent()
-.\" glibc does not
-.LP
-The
-.BR fgetspent ()
-function is similar to
-.BR getspent ()
-but uses the supplied stream instead of the one implicitly opened by
-.BR setspent ().
-.LP
-The
-.BR sgetspent ()
-function parses the supplied string
-.I s
-into a struct
-.IR spwd .
-.LP
-The
-.BR putspent ()
-function writes the contents of the supplied struct
-.I spwd
-.I *p
-as a text line in the shadow password file format to
-.IR stream .
-String entries with value NULL and numerical entries with value \-1
-are written as an empty string.
-.LP
-The
-.BR lckpwdf ()
-function is intended to protect against multiple simultaneous accesses
-of the shadow password database.
-It tries to acquire a lock, and returns 0 on success,
-or \-1 on failure (lock not obtained within 15 seconds).
-The
-.BR ulckpwdf ()
-function releases the lock again.
-Note that there is no protection against direct access of the shadow
-password file.
-Only programs that use
-.BR lckpwdf ()
-will notice the lock.
-.LP
-These were the functions that formed the original shadow API.
-They are widely available.
-.\" Also in libc5
-.\" SUN doesn't have sgetspent()
-.SS Reentrant versions
-Analogous to the reentrant functions for the password database, glibc
-also has reentrant functions for the shadow password database.
-The
-.BR getspnam_r ()
-function is like
-.BR getspnam ()
-but stores the retrieved shadow password structure in the space pointed to by
-.IR spbuf .
-This shadow password structure contains pointers to strings, and these strings
-are stored in the buffer
-.I buf
-of size
-.IR buflen .
-A pointer to the result (in case of success) or NULL (in case no entry
-was found or an error occurred) is stored in
-.IR *spbufp .
-.LP
-The functions
-.BR getspent_r (),
-.BR fgetspent_r (),
-and
-.BR sgetspent_r ()
-are similarly analogous to their nonreentrant counterparts.
-.LP
-Some non-glibc systems also have functions with these names,
-often with different prototypes.
-.\" SUN doesn't have sgetspent_r()
-.SS Structure
-The shadow password structure is defined in \fI<shadow.h>\fP as follows:
-.sp
-.in +4n
-.nf
-struct spwd {
- char *sp_namp; /* Login name */
- char *sp_pwdp; /* Encrypted password */
- long sp_lstchg; /* Date of last change
- (measured in days since
- 1970-01-01 00:00:00 +0000 (UTC)) */
- long sp_min; /* Min # of days between changes */
- long sp_max; /* Max # of days between changes */
- long sp_warn; /* # of days before password expires
- to warn user to change it */
- long sp_inact; /* # of days after password expires
- until account is disabled */
- long sp_expire; /* Date when account expires
- (measured in days since
- 1970-01-01 00:00:00 +0000 (UTC)) */
- unsigned long sp_flag; /* Reserved */
-};
-.fi
-.in
-.SH RETURN VALUE
-The functions that return a pointer return NULL if no more entries
-are available or if an error occurs during processing.
-The functions which have \fIint\fP as the return value return 0 for
-success and \-1 for failure, with
-.I errno
-set to indicate the cause of the error.
-.LP
-For the nonreentrant functions, the return value may point to static area,
-and may be overwritten by subsequent calls to these functions.
-.LP
-The reentrant functions return zero on success.
-In case of error, an error number is returned.
-.SH ERRORS
-.TP
-.B EACCES
-The caller does not have permission to access the shadow password file.
-.TP
-.B ERANGE
-Supplied buffer is too small.
-.SH FILES
-.TP
-.I /etc/shadow
-local shadow password database file
-.TP
-.I /etc/.pwd.lock
-lock file
-.LP
-The include file
-.I <paths.h>
-defines the constant
-.B _PATH_SHADOW
-to the pathname of the shadow password file.
-.SH CONFORMING TO
-The shadow password database and its associated API are
-not specified in POSIX.1-2001.
-However, many other systems provide a similar API.
-.SH SEE ALSO
-.BR getgrnam (3),
-.BR getpwnam (3),
-.BR getpwnam_r (3),
-.BR shadow (5)
-.SH COLOPHON
-This page is part of release 3.79 of the Linux
-.I man-pages
-project.
-A description of the project,
-information about reporting bugs,
-and the latest version of this page,
-can be found at
-\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
