getspnam

ИМЯ

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[.buflen], size_t buflen, struct spwd **spbufp);
int getspnam_r(const char *name, struct spwd *spbuf,
               char buf[.buflen], size_t buflen, struct spwd **spbufp);

int fgetspent_r(FILE *stream, struct spwd *spbuf,
               char buf[.buflen], size_t buflen, struct spwd **spbufp);
int sgetspent_r(const char *s, struct spwd *spbuf,
               char buf[.buflen], 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;  /* зарезервировано */
};

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

The functions that return a pointer return NULL if no more entries are available or if an error occurs during processing. The functions which have int as the return value return 0 for success and -1 for failure, with errno set to indicate the error.

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

При успешном выполнении реентерабельные функции возвращают 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)

ПЕРЕВОД

Русский перевод этой страницы руководства был сделан Azamat Hackimov <[email protected]>, Dmitry Bolkhovskikh <[email protected]>, Vladislav <[email protected]>, Yuri Kozlov <[email protected]> и Иван Павлов <[email protected]>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на [email protected]

5 февраля 2023 г.

Linux man-pages 6.03