Linux程序员手册 第3部分
更新日期： 2017-09-15

名称

getspnam，getspnam_r，getspent，getspent_r，setspent，endsed，fgetspent，fgetspent_r，sgetspent，sgetspent_r，putspent，lckpwdf，ulckpwdf-获取影子密码文件条目

语法

/* General shadow password file API */
#include <shadow.h>

struct spwd *getspnam(const char *name);

struct spwd *getspent(void);

void setspent(void);

void endspent(void);

struct spwd *fgetspent(FILE *stream);

struct spwd *sgetspent(const char *s);

int putspent(const struct spwd *p, FILE *stream);

int lckpwdf(void);

int ulckpwdf(void);

/* GNU extension */
#include <shadow.h>

int getspent_r(struct spwd *spbuf,
        char *buf, size_t buflen, struct spwd **spbufp);

int getspnam_r(const char *name, struct spwd *spbuf,
        char *buf, size_t buflen, struct spwd **spbufp);

int fgetspent_r(FILE *stream, struct spwd *spbuf,
        char *buf, size_t buflen, struct spwd **spbufp);

int sgetspent_r(const char *s, struct spwd *spbuf,
        char *buf, size_t buflen, struct spwd **spbufp);

glibc的功能测试宏要求(请参阅feature_test_macros(7))：

getspent_r()，getspnam_r()，fgetspent_r()，sgetspent_r()：
从glibc 2.19开始：
_DEFAULT_SOURCE
Glibc 2.19及更早版本：
_BSD_SOURCE _SVID_SOURCE

说明

很久以前，在密码文件中公开显示加密密码被认为是安全的。当计算机变得越来越快，人们对安全性有了更多的了解时，这不再是可以接受的。 Julianne Frances Haugh实现了影子密码套件，该套件将加密密码保留在影子密码数据库中(例如，本地影子密码文件/ etc / shadow，NIS和LDAP)，只能由root读取。

下面描述的功能类似于传统密码数据库的功能(例如，请参见getpwnam(3)和getpwent(3))。

getspnam()函数返回一个指向结构的指针，该结构包含影子密码数据库中与用户名匹配的记录的细分字段。

getspent()函数返回一个指向影子密码数据库中下一个条目的指针。输入流中的位置由setspent()初始化。完成阅读后，程序可以调用endsend()，以便可以释放资源。

fgetspent()函数类似于getspent()，但是使用提供的流，而不是setspent()隐式打开的流。

sgetspent()函数将提供的字符串s解析为结构spwd。

putspent()函数以影子密码文件格式将提供的struct spwd * p的内容作为文本行写入流中。值为NULL的字符串条目和值为-1的数字条目被写为空字符串。

lckpwdf()函数用于防止对影子密码数据库进行多次同时访问。它尝试获取锁，并在成功时返回0，或在失败时返回-1(在15秒内未获得锁)。 ulckpwdf()函数再次释放锁定。请注意，没有针对直接访问影子密码文件的保护措施。只有使用lckpwdf()的程序才会注意到该锁定。

这些功能构成了原始的影子API。它们广泛可用。

Reentrant versions

与密码数据库的可重入功能类似，glibc也具有影子密码数据库的可重入功能。 getspnam_r()函数类似于getspnam()，但将检索到的影子密码结构存储在spbuf指向的空间中。该影子密码结构包含指向字符串的指针，并且这些字符串存储在大小为buflen的缓冲区buf中。指向结果的指针(如果成功)或NULL(如果未找到条目或发生错误)存储在* spbufp中。

函数getspent_r()，fgetspent_r()和sgetspent_r()类似地类似于其不可重入的对应函数。

一些非glibc系统也具有带有这些名称的功能，通常具有不同的原型。

Structure

影子密码结构定义如下：

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 */
};

返回值

如果没有更多可用的条目或在处理过程中发生错误，则返回指针的函数将返回NULL。以int作为返回值的函数返回0表示成功，返回-1表示失败，其中设置errno表示错误原因。

对于非重入函数，返回值可能指向静态区域，并且可能被后续调用这些函数所覆盖。

可重入函数成功返回零。发生错误时，将返回错误编号。

错误说明

EACCES

呼叫者无权访问影子密码文件。

ERANGE

提供的缓冲区太小。

文件

/etc/shadow

本地影子密码数据库文件

/etc/.pwd.lock

锁文件

包含文件将常量_PATH_SHADOW定义为影子密码文件的路径名。

属性

有关本节中使用的术语的说明，请参见attribute(7)。

在上表中，race中的getspent：getspent表示，如果在程序的不同线程中并行使用setpent()，getspent()，getspent_r()或endsend()中的任何函数，则可能发生数据争用。

遵循规范

影子密码数据库及其关联的API在POSIX.1中未指定。但是，许多其他系统提供了类似的API。

另外参见

getgrnam(3)，getpwnam(3)，getpwnam_r(3)，shadow(5)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。