getpwnam(3)

НАИМЕНОВАНИЕ
getpwnam, getpwnam_r, getpwuid, getpwuid_r - получает записи из файла паролей

БИБЛИОТЕКА
Стандартная библиотека языка C (libc, -lc)

ОБЗОР
#include <sys/types.h>
#include <pwd.h>

struct passwd *getpwnam(const char *name);
struct passwd *getpwuid(uid_t uid);

int getpwnam_r(const char *restrict name, struct passwd *restrict pwd,
               char buf[restrict .buflen], size_t buflen,
               struct passwd **restrict result);
int getpwuid_r(uid_t uid, struct passwd *restrict pwd,
               char buf[restrict .buflen], size_t buflen,
               struct passwd **restrict result);

    Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

getpwnam_r(), getpwuid_r():
    _POSIX_C_SOURCE
        || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_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; в этом случае вызывающий может повторить вызов с большим буфером).

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
The getpwnam() and getpwuid() functions return a pointer to a passwd structure, or NULL if the matching entry is not found or an error occurs. If an error occurs, errno is set to indicate the error. If one wants to check errno after the call, it should be set to zero before the call.

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

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

ОШИБКИ

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

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

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

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

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

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

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

ПРИМЕЧАНИЕ
The user password database mostly refers to /etc/passwd. However, with recent systems it also refers to network wide databases using NIS, LDAP and other local files as configured in /etc/nsswitch.conf.

ФАЙЛЫ

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

/etc/nsswitch.conf
    System Databases and Name Service Switch configuration file

АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
Интерфейс | Атрибут | Значение
getpwnam() | Безвредность в нитях | MT-Unsafe race:pwnam locale
getpwuid() | Безвредность в нитях | MT-Unsafe race:pwuid locale
getpwnam_r(), getpwuid_r() | Безвредность в нитях | MT-Safe locale

ВЕРСИИ
Поле pw_gecos не указано в POSIX, но присутствует в большинстве реализаций.

СТАНДАРТЫ
POSIX.1-2008.

ИСТОРИЯ
POSIX.1-2001, SVr4, 4.3BSD.

ПРИМЕЧАНИЯ
Описание «ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ», приведённого выше, взято из 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 <errno.h>
    #include <pwd.h>
    #include <stdint.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <unistd.h>

    int
    main(int argc, char *argv[])
    {
        struct passwd pwd;
        struct passwd *result;
        char *buf;
        long 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: %jd\n", pwd.pw_gecos,
               (intmax_t) pwd.pw_uid);
        exit(EXIT_SUCCESS);
    }

СМОТРИТЕ ТАКЖЕ
endpwent(3), fgetpwent(3), getgrnam(3), getpw(3), getpwent(3), getspnam(3), putpwent(3), setpwent(3), nsswitch.conf(5), passwd(5)

ПЕРЕВОД
Русский перевод этой страницы руководства разработал(и) Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, Vladislav <ivladislavefimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru>, Иван Павлов <pavia00@gmail.com> и Kirill Rekhov <krekhov.dev@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских переводчиков (<debian-l10n-russian@lists.debian.org>).