GETSPNAM - Linux手册页

时间:2019-08-20 18:01:18  来源:igfitidea点击:

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)。

InterfaceAttributeValue
getspnam()Thread safetyMT-Unsafe race:getspnam locale
getspent()Thread safetyMT-Unsafe race:getspent
race:spentbuf locale
setspent(),
endspent(),
getspent_r()
Thread safetyMT-Unsafe race:getspent locale
fgetspent()Thread safetyMT-Unsafe race:fgetspent
sgetspent()Thread safetyMT-Unsafe race:sgetspent
putspent(),
getspnam_r(),
sgetspent_r()
Thread safetyMT-Safe locale
lckpwdf(),
ulckpwdf(),
fgetspent_r()
Thread safetyMT-Safe

在上表中,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/