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

名称

getgrnam，getgrnam_r，getgrgid，getgrgid_r-获取组文件条目

语法

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

struct group *getgrnam(const char *name);

struct group *getgrgid(gid_t gid);

int getgrnam_r(const char *name, struct group *grp,
          char *buf, size_t buflen, struct group **result);

int getgrgid_r(gid_t gid, struct group *grp,
          char *buf, size_t buflen, struct group **result);

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

getgrnam_r()，getgrgid_r()：

_POSIX_C_SOURCE || / * Glibc版本

说明

getgrnam()函数返回一个指向包含与组名称相匹配的组数据库(例如本地组文件/ etc / group，NIS和LDAP)中记录的细分字段的结构的指针。

getgrgid()函数返回一个指向结构的指针，该结构包含与组ID gid匹配的组数据库中记录的中断字段。

组结构定义如下：

struct group {
    char   *gr_name;        /* group name */
    char   *gr_passwd;      /* group password */
    gid_t   gr_gid;         /* group ID */
    char  **gr_mem;         /* NULL-terminated array of pointers
                               to names of group members */
};

有关此结构的字段的更多信息，请参见group(5)。

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

通话

sysconf(_SC_GETGR_R_SIZE_MAX)

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

返回值

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

返回值可能指向静态区域，并且可能随后被getgrent(3)，getgrgid()或getgrnam()调用而覆盖。 (不要将返回的指针传递给free(3)。)

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

错误说明

0or ENOENTor ESRCHor EBADFor EPERMor ...

找不到给定的名称或名称。

EINTR

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

EIO

I / O错误。

EMFILE

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

ENFILE

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

ENOMEM

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

ERANGE

提供的缓冲区空间不足。

文件

/etc/group

本地组数据库文件

属性

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

遵循规范

POSIX.1-2001，POSIX.1-2008，SVr4、4.3BSD。

备注

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

另外参见

endgrent(3)，fgetgrent(3)，getgrent(3)，getpwnam(3)，setgrent(3)，group(5)

出版信息

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