GETSPNAM(3)

ИМЯ
getspnam, getspnam_r, getspent, getspent_r, setspent, endspent, fgetspent, fgetspent_r, sgetspent, sgetspent_r, putspent, lckpwdf, ulckpwdf - получение записи из теневого файла паролей

ОБЗОР
/* Основной API теневого файла паролей */
#include <shadow.h>

struct spwd *getspnam(const char *name);

struct spwd *getspent(void);

void setspent(void);

void endspent(void);

struct spwd *fgetspent(FILE *stream);

struct spwd *sgetspent(const char *s);

int putspent(const struct spwd *p, FILE *stream);

int lckpwdf(void);

int ulckpwdf(void);
/* Расширение GNU */
#include <shadow.h>

int getspent_r(struct spwd *spbuf,
        char *buf, size_t buflen, struct spwd **spbufp);

int getspnam_r(const char *name, struct spwd *spbuf,
        char *buf, size_t buflen, struct spwd **spbufp);

int fgetspent_r(FILE *stream, struct spwd *spbuf,
        char *buf, size_t buflen, struct spwd **spbufp);

int sgetspent_r(const char *s, struct spwd *spbuf,
        char *buf, size_t buflen, struct spwd **spbufp);

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

getspent_r(), getspnam_r(), fgetspent_r(), sgetspent_r():
    начиная с glibc 2.19:
        _DEFAULT_SOURCE
    в glibc 2.19 и старее:
        _BSD_SOURCE || _SVID_SOURCE

ОПИСАНИЕ
В давние времена считалось, что хранить зашифрованные пароли в открытом доступе достаточно безопасно. Со временем компьютеры стали быстрее, а люди - более обеспокоенными проблемами безопасности, и данный подход стал неприемлемым. Джулиан Франс Хог (Julianne Frances Haugh) реализовал набор программ для теневых паролей, который хранит зашифрованные пароли в базе данных теневых паролей (например в локальном файле теневых паролей /etc/shadow, NIS или LDAP), доступной для чтения только root.

Описанные ниже функции соответствуют аналогами для традиционной базы паролей (см. getpwnam(3) and getpwent(3)).

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

Функция getspent() возвращает указатель на следующую запись в базе данных теневых паролей. Положение во входном потоке инициализируется с помощью setspent(). После выполнения чтения программа может вызвать endspent() для освобождения ресурсов.

Функция fgetspent() подобна getspent() но использует заданный поток вместо неявного открытия с помощью setspent().

Функция sgetspent() разбирает передаваемую строку s в структуру spwd.

Функция putspent() записывает в stream содержимое передаваемой структуры spwd *p в виде текстовой строки в формате файла теневых паролей. Строковые записи со значением NULL и числовые записи со значением -1 записываются как пустые строки.

Функция lckpwdf() предназначена для защиты базы данных теневых паролей при одновременном многочисленном доступе. Она пытается захватить блокировку и возвращает 0 при успешном выполнении и -1 при ошибке (блокировка не получена в течении 15 секунд). Функция ulckpwdf() освобождает блокировку. Заметим, что это не защищает при прямом доступе к файлу теневых паролей. О блокировке будут уведомлены только программы, использующие lckpwdf().

Эти функции возникли в исходном программном интерфейсе. Они широко используются.

  Реентерабельные версии
По аналогии с реентерабельными функциями для базы данных паролей, в glibc также есть реентерабельные функции для базы данных теневых паролей. Функция getspnam_r() подобна getspnam(), но хранит выбранную структуру теневого пароля в пространстве, на которое указывает spbuf. Данная структура теневого пароля содержит указатели на строки и эти строки хранятся в буфере buf размером buflen. Указатель на результат (при успешном выполнении) или NULL (в случае отсутствия записи или ошибки) сохраняется в *spbufp.

Функции getspent_r(), fgetspent_r() и sgetspent_r() подобны их нереентерабельным аналогам.

Некоторые не-glibc системы также содержат функции с такими именами, но, чаще всего, с другими прототипами.

  Структура
Структура теневого пароля определена в <shadow.h>:

    struct spwd {
        char *sp_namp;     /* имя пользователя */
        char *sp_pwdp;     /* зашифрованный пароль */
        long  sp_lstchg;   /* дата последнего изменения
                          в днях начиная с 1970-01-01 00:00:00 +0000 (UTC)) */
        long  sp_min;      /* мин. кол-во дней между сменой */
        long  sp_max;      /* макс. кол-во дней между сменой */
        long  sp_warn;     /* кол-во дней до истечения срока действия пароля
                              для предупреждения пользователя */
        long  sp_inact;    /* кол-во дней до истечения срока действия пароля,
                              после запись блокируется */
        long  sp_expire;   /* дата устаревания учётной записи
                          в днях начиная с 1970-01-01 00:00:00 +0000 (UTC)) */
        unsigned long sp_flag;  /* зарезервировано */
    };

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функции, которые возвращают указатель, возвращают NULL, если элементы закончились или произошла ошибка во время обработки. Функции, которые возвращают значение с типом int, возвращают 0 при успешном выполнении и -1 при ошибке, записывая в errno причину ошибки.

У нереентерабельных функций возвращаемое значение может указывать на статическую область и может быть перезаписано последующими вызовами этих функций.

При успешном выполнении реентерабельные функции возвращают 0. В случае ошибки возвращается номер ошибки.

ОШИБКИ

EACCES
    Вызывающий не имеет прав доступа к файлу теневых паролей.

ERANGE
    Указанный буфер слишком мал.

ФАЙЛЫ

/etc/shadow
    файл, содержащий базу локальных теневых паролей

/etc/.pwd.lock
    файл блокировки

При включении файла <paths.h> определяется константа _PATH_SHADOW, в которой хранится путь к файлу теневых паролей.

АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
Интерфейс | Атрибут | Значение
getspnam() | Безвредность в нитях | MT-Unsafe race:getspnam locale
getspent() | Безвредность в нитях | MT-Unsafe race:getspent race:spentbuf locale
setspent(), endspent(), getspent_r() | Безвредность в нитях | MT-Unsafe race:getspent locale
fgetspent() | Безвредность в нитях | MT-Unsafe race:fgetspent
sgetspent() | Безвредность в нитях | MT-Unsafe race:sgetspent
putspent(), getspnam_r(), sgetspent_r() | Безвредность в нитях | MT-Safe locale
lckpwdf(), ulckpwdf(), fgetspent_r() | Безвредность в нитях | MT-Safe

В приведённой выше таблице getspent в race:getspent означает, что если в нескольких нитях программы одновременно используются функции setspent(), getspent(), getspent_r() или endspent(), то может возникнуть состязательность по данным.

СООТВЕТСТВИЕ СТАНДАРТАМ
База данных теневых паролей и её программный интерфейс не описаны в POSIX.1. Однако, во многих системах есть похожий программный интерфейс.

СМОТРИТЕ ТАКЖЕ
getgrnam(3), getpwnam(3), getpwnam_r(3), shadow(5)