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

名称

getpwnam，getpwnam_r，getpwuid，getpwuid_r-获取密码文件条目

语法

#include <sys/types.h>
#include <pwd.h>

struct passwd *getpwnam(const char *name);

struct passwd *getpwuid(uid_t uid);

int getpwnam_r(const char *name, struct passwd *pwd,
               char *buf, size_t buflen, struct passwd **result);

int getpwuid_r(uid_t uid, struct passwd *pwd,
               char *buf, size_t buflen, struct passwd **result);

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

getpwnam_r()，getpwuid_r()：

_POSIX_C_SOURCE || / * Glibc版本

说明

getpwnam()函数返回一个指向结构的指针，该结构包含与用户名匹配的密码数据库中记录的中断字段(例如本地密码文件/ etc / passwd，NIS和LDAP)。

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

passwd结构的定义如下：

struct passwd {
    char   *pw_name;       /* username */
    char   *pw_passwd;     /* user password */
    uid_t   pw_uid;        /* user ID */
    gid_t   pw_gid;        /* group ID */
    char   *pw_gecos;      /* user information */
    char   *pw_dir;        /* home directory */
    char   *pw_shell;      /* shell program */
};

有关这些字段的更多信息，请参见passwd(5)。

getpwnam_r()和getpwuid_r()函数获得与getpwnam()和getpwuid()相同的信息，但是将检索到的passwd结构存储在pwd指向的空间中。 passwd结构的成员所指向的字符串字段存储在大小为buflen的缓冲区buf中。指向结果的指针(如果成功)或NULL(如果未找到条目或发生错误)存储在* result中。

通话

sysconf(_SC_GETPW_R_SIZE_MAX)

返回-1(不更改errno)或buf的初始建议大小。 (如果此大小太小，则调用将以ERANGE失败，在这种情况下，调用方可以使用更大的缓冲区重试。)

返回值

getpwnam()和getpwuid()函数返回指向passwd结构的指针，如果找不到匹配的条目或发生错误，则返回NULL。如果发生错误，则会正确设置errno。如果要在通话后检查errno，则应在通话前将其设置为零。

返回值可能指向静态区域，并且可能被后续对getpwent(3)，getpwnam()或getpwuid()的调用覆盖。 (不要将返回的指针传递给free(3)。)

成功时，getpwnam_r()和getpwuid_r()返回零，并将* result设置为pwd。如果找不到匹配的密码记录，这些函数将返回0并将NULL存储在* result中。如果发生错误，则返回错误号，并将NULL存储在* result中。

错误说明

0or ENOENTor ESRCHor EBADFor EPERMor ...

找不到给定的名称或uid。

EINTR

捕获到信号；参见signal(7)。

EIO

I / O错误。

EMFILE

已达到打开文件描述符数量的每个进程限制。

ENFILE

已达到系统范围内打开文件总数的限制。

ENOMEM

内存不足，无法分配passwd结构。

ERANGE

提供的缓冲区空间不足。

文件

/etc/passwd

本地密码数据库文件

属性

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

遵循规范

POSIX.1-2001，POSIX.1-2008，SVr4、4.3BSD。在POSIX中未指定pw_gecos字段，但是在大多数实现中都存在。

备注

上面在"返回值"下给出的公式来自POSIX.1-2001。它不会调用"未找到"错误，因此不会指定errno在这种情况下可能具有的值。但这使得无法识别错误。有人可能会争辩说，根据POSIX，如果找不到条目，​​则errno应该保持不变。在各种类似UNIX的系统上进行的实验表明，在这种情况下，会出现很多不同的值：0，ENOENT，EBADF，ESRCH，EWOULDBLOCK，EPERM以及其他可能的值。

pw_dir字段包含用户的初始工作目录的名称。登录程序使用此字段的值来初始化登录外壳程序的HOME环境变量。想要确定其用户主目录的应用程序应检查HOME的值(而不是getpwuid(getuid())-> pw_dir值)，因为这允许用户在登录会话期间修改其"主目录"概念。要确定另一个用户的(初始)主目录，必须使用getpwnam(username)-> pw_dir或类似名称。

示例

下面的程序演示了如何使用getpwnam_r()来查找作为命令行参数提供的用户名的完整用户名和用户ID。

#include <pwd.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <errno.h>

int
main(int argc, char *argv[])
{
    struct passwd pwd;
    struct passwd *result;
    char *buf;
    size_t bufsize;
    int s;

    if (argc != 2) {
        fprintf(stderr, "Usage: %s username\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
    if (bufsize == -1)          /* Value was indeterminate */
        bufsize = 16384;        /* Should be more than enough */

    buf = malloc(bufsize);
    if (buf == NULL) {
        perror("malloc");
        exit(EXIT_FAILURE);
    }

    s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result);
    if (result == NULL) {
        if (s == 0)
            printf("Not found\n");
        else {
            errno = s;
            perror("getpwnam_r");
        }
        exit(EXIT_FAILURE);
    }

    printf("Name: %s; UID: %ld\n", pwd.pw_gecos, (long) pwd.pw_uid);
    exit(EXIT_SUCCESS);
}

另外参见

endpwent(3)，fgetpwent(3)，getgrnam(3)，getpw(3)，getpwent(3)，getspnam(3)，putpwent(3)，setpwent(3)，passwd(5)

出版信息

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