getutent(3)

НАИМЕНОВАНИЕ
getutent, getutid, getutline, pututline, setutent, endutent, utmpname - доступ к записям файла utmp

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

СИНТАКСИС
#include <utmp.h>

struct utmp *getutent(void);
struct utmp *getutid(const struct utmp *ut);
struct utmp *getutline(const struct utmp *ut);

struct utmp *pututline(const struct utmp *ut);

void setutent(void);
void endutent(void);

int utmpname(const char *path);

ОПИСАНИЕ
New applications should use the POSIX.1-specified "utmpx" versions of these functions; see STANDARDS.

utmpname() sets the pathname of the utmp-format file for the other utmp functions to access. If utmpname() is not used to set the pathname before the other functions are used, they assume _PATH_UTMP, as defined in <paths.h>.

Функция setutent() переносит указатель начало файла utmp. Вообще, оптимальным вариантом считается вызывать эту функцию перед вызовом остальных.

Функция endutent() закрывает файл utmp. Она должна быть вызвана, когда будет завершена работа с файлом посредством других функций.

Функция getutent() считывает строку, начиная с текущей позиции файла в файле utmp. Она возвращает указатель на структуру, содержащую поля этой строки. Определение структуры приведено в utmp(5).

Функция getutid() производит прямой поиск, начиная с текущей позиции файла в файле utmp, основываясь на данных ut. Если значение ut->ut_type равно RUN_LVL, BOOT_TIME, NEW_TIME или OLD_TIME, то getutid() найдёт первую запись, поле ut_type которой совпадает с ut->ut_type. Если ut->ut_type равно INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS или DEAD_PROCESS, то getutid() найдёт первую запись, поле ut_id которой совпадает с ut->ut_id.

Функция getutline() производит прямой поиск, начиная с текущей позиции файла в файле utmp. Она просматривает записи, у которых поле ut_type совпадает с USER_PROCESS или LOGIN_PROCESS, и возвращает первую запись, поле ut_line которой совпадает с ut->ut_line.

Функция pututline() записывает структуру utmp ut в файл utmp. Для поиска места в файле, необходимого для вставки новой записи, используется getutid() . Если такое место не найдено, то pututline() добавит запись в конец файла.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
getutent(), getutid(), and getutline() return a pointer to a struct utmp on success, and NULL on failure (which includes the "record not found" case). This struct utmp is allocated in static storage, and may be overwritten by subsequent calls.

При успешном выполнении pututline() возвращает ut; при ошибке возвращается NULL.

При успешном назначении нового имени функция utmpname() возвращает 0 и -1 при ошибке.

On failure, these functions errno set to indicate the error.

ОШИБКИ

ENOMEM
    Не хватает памяти.

ESRCH
    Запись не найдена.

Функции setutent(), pututline() и getut*() также могут завершиться с ошибкой по причинам, описанным в open(2).

ФАЙЛЫ

/var/run/utmp
    база данных пользователей, находящихся в системе в данный момент

/var/log/wtmp
    база данных предыдущих пользовательских входов в систему

АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
Интерфейс | Атрибут | Значение
getutent() | Безвредность в нитях | MT-Unsafe init race:utent race:utentbuf sig:ALRM timer
getutid(), getutline() | Безвредность в нитях | MT-Unsafe init race:utent sig:ALRM timer
pututline() | Безвредность в нитях | MT-Unsafe race:utent sig:ALRM timer
setutent(), endutent(), utmpname() | Безвредность в нитях | MT-Unsafe race:utent

В приведённой выше таблице utent в race:utent означает, что если в нескольких нитях программы одновременно используются функции setutent(), getutent(), getutid(), getutline(), pututline(), utmpname() или endutent(), то может возникнуть состязательность по данным.

СТАНДАРТЫ
Отсутствуют.

ИСТОРИЯ
XPG2, SVr4.

Согласно XPG2 и SVID 2 функция pututline() возвращает тип void и такое поведение можно встретить во многих системах (AIX, HP-UX). В HP-UX представлена новая функция _pututline() с прототипом приведённым выше для pututline().

Эти функции являются устаревшими в не Linux системах. POSIX.1-2001 и POSIX.1-2008, следуя SUSv1, не содержит эти функции, вместо них используются

        #include <utmpx.h>

    struct utmpx *getutxent(void);
    struct utmpx *getutxid(const struct utmpx *);
    struct utmpx *getutxline(const struct utmpx *);
    struct utmpx *pututxline(const struct utmpx *);
    void setutxent(void);
    void endutxent(void);

Эти функции предоставляются glibc и выполняют те же задачи что и их аналоги без «x»", но используют struct utmpx, определённую в Linux подобно struct utmp. Для завершённости, в glibc также есть utmpxname(), хотя эта функция отсутствует в POSIX.1.

В некоторых других системах структура utmpx представляет собой utmp с дополнительными полями и увеличенными размерами одинаковых полей, а также параллельно обслуживаются обе версии файлов, часто /var/*/utmpx и /var/*/wtmpx.

С другой стороны, в Linux glibc не используется второй файл utmpx, так как её структура utmp имеет достаточный размер. Функции с «x», перечисленные выше, являются просто псевдонимами их аналогов без «x» (например, getutxent() псевдоним getutent()).

ПРИМЕЧАНИЯ

  Замечания по glibc
The above functions are not thread-safe. glibc adds reentrant versions

#include <utmp.h>

int getutent_r(struct utmp *ubuf, struct utmp **ubufp);
int getutid_r(struct utmp *ut,
              struct utmp *ubuf, struct utmp **ubufp);
int getutline_r(struct utmp *ut,
                struct utmp *ubuf, struct utmp **ubufp);

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

getutent_r(), getutid_r(), getutline_r():
    _GNU_SOURCE
        || /* Since glibc 2.19: */ _DEFAULT_SOURCE
        || /* glibc <= 2.19: */    _SVID_SOURCE || _BSD_SOURCE

Эти функции являются расширениями GNU, они аналогичны функциям с тем же именем без суффикса _r. В аргумент ubuf, передаваемый этим функциям, помещается результат. При успешном выполнении они возвращают 0 и указатель на результат записывается в *ubufp. При ошибке эти функции возвращают -1. Среди этих функций отсутствует эквиваленты utmpx (в POSIX.1 такие функции отсутствуют).

ПРИМЕРЫ
Нижеследующий пример добавляет и удаляет запись utmp, предполагается, что программа запущена с псевдотерминала. Для использования в реальном приложении необходимо проверять значения, возвращаемые getpwuid(3) и ttyname(3).

    #include <err.h>
    #include <pwd.h>
    #include <stdlib.h>
    #include <string.h>
    #include <time.h>
    #include <unistd.h>
    #include <utmp.h>

    int
    main(void)
    {
        struct utmp entry;

        if (system("echo before adding entry:;who") == -1)
            err(EXIT_FAILURE, "system");

        entry.ut_type = USER_PROCESS;
        entry.ut_pid = getpid();
        strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
        /* only correct for ptys named /dev/tty[pqr][0-9a-z] */
        strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
        entry.ut_time = time(NULL);
        strcpy(entry.ut_user, getpwuid(getuid())->pw_name);
        memset(entry.ut_host, 0, UT_HOSTSIZE);
        entry.ut_addr = 0;
        setutent();
        if (pututline(&entry) == NULL)
            err(EXIT_FAILURE, "pututline");

        if (system("echo after adding entry:;who") == -1)
            err(EXIT_FAILURE, "system");

        entry.ut_type = DEAD_PROCESS;
        memset(entry.ut_line, 0, UT_LINESIZE);
        entry.ut_time = 0;
        memset(entry.ut_user, 0, UT_NAMESIZE);
        setutent();
        if (pututline(&entry) == NULL)
            err(EXIT_FAILURE, "pututline");

        if (system("echo after removing entry:;who") == -1)
            err(EXIT_FAILURE, "system");

        endutent();
        exit(EXIT_SUCCESS);
    }

СМОТРИТЕ ТАКЖЕ
getutmp(3), utmp(5)

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

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

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