ОБЗОР

#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 >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE || _POSIX_SOURCE

ОПИСАНИЕ

Функция getpwnam() возвращает указатель на структуру, содержащую разделённую на поля запись из базы данных паролей (например, из локального файла паролей /etc/passwd, NIS и LDAP), которая соответствует имени пользователя name.

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

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

struct passwd {
    char   *pw_name;       /* имя пользователя */
    char   *pw_passwd;     /* пароль пользователя */
    uid_t   pw_uid;        /* идентификатор пользователя */
    gid_t   pw_gid;        /* идентификатор группы */
    char   *pw_gecos;      /* информация о пользователе */
    char   *pw_dir;        /* домашний каталог */
    char   *pw_shell;      /* программная оболочка */
};

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

Функции getpwnam_r() и getpwuid_r() принимают ту же информацию что и getpwnam() и getpwuid(), но сохраняют полученную структуру passwd в пространство, указанное pwd. Строковые поля членов структуры passwd сохраняются в буфере buf размера buflen. Указатель на результат (при успешном выполнении) или 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. При ошибке возвращается её номер и в *result сохраняется NULL.

ФАЙЛЫ

/etc/passwd

файл, содержащий локальную базу паролей

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

Интерфейс	Атрибут	Значение
getpwnam()	безвредность в нитях	небезопасно (MT-Unsafe race:pwnam locale)
getpwuid()	безвредность в нитях	небезопасно (MT-Unsafe race:pwuid locale)
getpwnam_r(), getpwuid_r()	безвредность в нитях	безвредно (MT-Safe locale)

СООТВЕТСТВИЕ СТАНДАРТАМ

POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. Поле pw_gecos не определено в стандарте POSIX, но присутствует в большинстве реализаций.

ЗАМЕЧАНИЯ

Описание «ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ», приведённого выше, взято из POSIX.1-2001. В нём «не найдено» не считается ошибкой и поэтому не указано, каким может быть значение errno в этом случае. Но это делает невозможным определить тип ошибки. Из описание POSIX можно посчитать, что errno не должно измениться, если запись не найдена. Эксперименты в различных UNIX-подобных системах показывают, что в этой ситуации возвращается много разных значений: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM и, возможно, другие.

В поле pw_dir содержится имя первого рабочего каталога пользователя. Программы входа используют это значение для инициализации переменной окружения HOME для регистрационной оболочки. Приложение, которое хочет определить имя домашнего каталога пользователя должно проверять значение HOME (а не значение getpwuid(getuid())->pw_dir), так как это позволяет пользователю изменять их понятие о «домашнем каталоге» в течении сеанса. Для определения (начального) домашнего каталога другого пользователя необходимо использовать getpwnam("имя пользователя")->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, "Использование: %s имя\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
    if (bufsize == -1)          /* значение не указано */
        bufsize = 16384;        /* должно быть достаточно */
    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("Не найдено\n");
        else {
            errno = s;
            perror("getpwnam_r");
        }
        exit(EXIT_FAILURE);
    }
    printf("Имя: %s; UID: %ld\n", pwd.pw_gecos, (long) pwd.pw_uid);
    exit(EXIT_SUCCESS);
}