GETGRNAM(3)

ИМЯ
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 <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

ОПИСАНИЕ
Функция getgrnam() возвращает указатель на структуру, содержащую разделённую на поля запись из базы данных групп (например, из локального файла групп /etc/group, NIS и LDAP), которая соответствует имени группы name.

Функция getgrgid() возвращает указатель на структуру, содержащую разделённую на поля запись из базы данных групп, которая соответствует идентификатору группы gid.

Структура group определена в <grp.h> следующим образом:

struct group {
    char   *gr_name;        /* имя группы */
    char   *gr_passwd;      /* пароль группы */
    gid_t   gr_gid;         /* ID группы */
    char  **gr_mem;         /* массив, указателей
                               имён членов группы, оканчивающийся NULL */
};

Подробней о полях этой структуры смотрите в group(5).

Функции getgrnam_r() и getgrgid_r() принимают ту же информацию что и getgrnam() и getgrgid(), но сохраняют полученную структуру group в пространство, указанное grp. Строковые поля членов структуры group сохраняются в буфере buf размера buflen. Указатель на результат (при успешном выполнении) или NULL (если записи отсутствуют или произошла ошибка) сохраняется в *result.

Вызов
    sysconf(_SC_GETGR_R_SIZE_MAX) возвращает или -1 без изменения errno или начальный предполагаемый размер buf (если этот размер мал, то вызов завершается ERANGE; в этом случае вызывающий может повторить вызов с большим буфером).

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функции getgrnam() и getgrgid() возвращают указатель на структуру group или NULL, если подходящих записей не найдено или возникла ошибка. При ошибке errno устанавливается в соответствующее значение. Если нужно проверять переменную errno после вызова, то перед этим нужно присвоить ей нулевое значение.

Возвращаемое значение может указывать на статическую область и может быть перезаписано при последующих вызовах getgrent(3), getgrnam() или getgrgid() (не передавайте полученный указатель free(3)).

При успешном выполнении getgrnam_r() и getgrgid_r() возвращают ноль, и устанавливают *result в pwd. Если совпадений не найдено, то эти функции возвращают 0 и сохраняют NULL в *result. При ошибке возвращается её номер и в *result сохраняется NULL.

ОШИБКИ

0 или ENOENT или ESRCH или EBADF или EPERM или …
    Указанное значение name или gid не найдено.

EINTR
    Поступил сигнал; смотрите signal(7).

EIO Ошибка ввода-вывода.

EMFILE
    Было достигнуто ограничение по количеству открытых файловых дескрипторов на процесс.

ENFILE
    Достигнуто максимальное количество открытых файлов в системе.

ENOMEM
    Недостаточно памяти для структуры group.

ERANGE
    Недостаточно места в буфере.

ФАЙЛЫ

/etc/group
    локальный файл базы данных групп

АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
Интерфейс | Атрибут | Значение
getgrnam() | Безвредность в нитях | MT-Unsafe race:grnam locale
getgrgid() | Безвредность в нитях | MT-Unsafe race:grgid locale
getgrnam_r(), getgrgid_r() | Безвредность в нитях | MT-Safe locale

СООТВЕТСТВИЕ СТАНДАРТАМ
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)