ИМЯ

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 и, возможно, другие.

ИМЯ