Man page - endutent(3)

Packages contains this manual

Available languages:

en fr pl ja ru de

Manual

GETUTENT

名 前
書 式
説 明
返 り 値
エ ラ ー
フ ァ イ ル
属 性
準 拠
注 意
glibc で の 注 意
例
関 連 項 目
こ の 文 書 に つ い て

名 前

getutent, getutid, getutline, pututline, setutent, endutent, utmpname - utmp フ ァ イ ル の エ ン ト リ ー に ア ク セ ス す る

書 式

#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 * file );

説 明

新 し い ア プ リ ケ ー シ ョ ン で は 、 こ れ ら の 関 数 の "utmpx" 版 を 使 用 す べ き で あ る 。 こ れ ら は POSIX.1 で 規 定 さ れ て い る 。 「 準 拠 」 の 節 を 参 照 。

utmpname () は 、 他 の utmp 関 数 が ア ク セ ス す る (utmp フ ォ ー マ ッ ト の ) フ ァ イ ル の 名 前 を 指 定 す る 。 他 の 関 数 を 使 う 前 に utmpname () を 使 っ て フ ァ イ ル 名 の 指 定 を 行 わ な か っ た 場 合 は 、 <path.h> で 定 義 さ れ て い る _PATH_UTMP が フ ァ イ ル 名 と み な さ れ る 。

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 フ ァ イ ル に 書 き 出 す 。 pututline () は getutid () を 用 い て 、 新 た な エ ン ト リ ー を 挿 入 す る の に ふ さ わ し い 場 所 を 探 す 。 ut を 挿 入 す る ふ さ わ し い 場 所 が 見 つ か ら な い 場 合 は 、 新 た な エ ン ト リ ー を フ ァ イ ル の 末 尾 に 追 加 す る 。

返 り 値

getutent (), getutid (), getutline () は 、 成 功 す る と struct utmp へ の ポ イ ン タ ー を 返 す 。 失 敗 す る と NULL を 返 す (レ コ ー ド が 見 つ か ら な か っ た 場 合 も 失 敗 と な る )。 こ の struct utmp は 静 的 な 記 憶 領 域 に 確 保 さ れ 、 次 に こ れ ら の 関 数 を 呼 び 出 し た 際 に 上 書 き さ れ る か も し れ な い 。

pututline () は 成 功 す る と ut を 返 す 。 失 敗 す る と NULL を 返 す 。

utmpname () は 、 新 し い 名 前 の 格 納 に 成 功 す る と 0 を 返 し 、 失 敗 す る と -1 を 返 す 。

エ ラ ー が 発 生 し た 場 合 、 こ れ ら の 関 数 は errno に エ ラ ー の 原 因 を 示 す 値 を 設 定 す る 。

エ ラ ー

ENOMEM

メ モ リ ー 不 足 。

ESRCH

レ コ ー ド が 見 つ か ら な か っ た 。

関 数 setutent (), pututline (), getut* () は open (2) に 書 か れ て い る 理 由 で も 失 敗 す る こ と が あ る 。

フ ァ イ ル

/var/run/utmp

現 在 ロ グ イ ン 中 の ユ ー ザ ー の デ ー タ ベ ー ス

/var/log/wtmp

ユ ー ザ ー ロ グ イ ン の 履 歴 デ ー タ ベ ー ス

属 性

こ の 節 で 使 用 さ れ て い る 用 語 の 説 明 に つ い て は 、 attributes (7) を 参 照 。

Image grohtml-17780-1.png

In the above table, utent in race:utent signifies that if any of the functions setutent (), getutent (), getutid (), getutline (), pututline (), utmpname (), or endutent () are used in parallel in different threads of a program, then data races could occur.

準 拠

XPG2, SVr4.

XPG2 と SVID 2 で は 、 pututline () 関 数 は 値 を 返 さ な い と さ れ て お り 、 (AIX, HP-UX な ど の ) 多 く の シ ス テ ム で は そ う な っ て い る 。 HP-UX で は 、 上 述 の pututline () と 同 じ プ ロ ト タ イ プ を 持 つ 新 し い 関 数 _pututline () が 導 入 さ れ て い る 。

現 在 で は 、 Linux 以 外 の シ ス テ ム で は 、 こ れ ら の 関 数 は 全 て 廃 止 さ れ て い る 。 SUSv1 の 後 に 出 て き た POSIX.1-2001 と POSIX.1-2008 で は 、 も は や こ れ ら の 関 数 は な く 、 代 わ り に 以 下 の も の を 使 う 。

#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 で は 規 定 さ れ て い な い 。

Linux 以 外 の シ ス テ ム で は 、 utmpx 構 造 体 は utmp 構 造 体 の 上 位 集 合 (superset) に な っ て い て 、 追 加 の フ ィ ー ル ド が あ っ た り 、 既 存 の フ ィ ー ル ド の サ イ ズ が 大 き く な っ て い た り す る も の も あ る 。 複 数 の フ ァ イ ル が 使 用 さ れ て い る 場 合 も あ り 、 多 く の 場 合 /var/*/utmpx と /var/*/wtmpx と い う フ ァ イ ル が 使 わ れ る 。

一 方 、 Linux glibc で は 複 数 の utmpx フ ァ イ ル は 使 わ れ て い な い 。 utmp 構 造 体 が 十 分 に 大 き い か ら で あ る 。 上 記 の 名 前 に "x" が 付 い た 関 数 は "x" が 付 い て い な い 対 応 す る 関 数 の 別 名 と な っ て い る (例 え ば getutxent () は getutent () の 別 名 で あ る )。

注 意

glibc で の 注 意

上 記 の 関 数 群 は ス レ ッ ド セ ー フ で は な い 。 glibc に は リ エ ン ト ラ ン ト 版 (reentrant) が 追 加 さ れ て い る 。

#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 の レ コ ー ド の 追 加 ・ 削 除 を 行 っ て い る 。 こ の コ ー ド は 、 擬 似 端 末 (pseudo terminal) か ら 実 行 さ れ る こ と を 想 定 し て い る 。 実 際 の ア プ リ ケ ー シ ョ ン で は getpwuid (3) と ttyname (3) の 戻 り 値 を 検 査 す る べ き で あ る 。

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

int
main(int argc, char *argv[])
{
struct utmp entry;

system("echo before adding entry:;who");

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"));
time(&entry.ut_time);
strcpy(entry.ut_user, getpwuid(getuid())->pw_name);
memset(entry.ut_host, 0, UT_HOSTSIZE);
entry.ut_addr = 0;
setutent();
pututline(&entry);

system("echo after adding entry:;who");

entry.ut_type = DEAD_PROCESS;
memset(entry.ut_line, 0, UT_LINESIZE);
entry.ut_time = 0;
memset(entry.ut_user, 0, UT_NAMESIZE);
setutent();
pututline(&entry);

system("echo after removing entry:;who");

endutent();
exit(EXIT_SUCCESS);
}

関 連 項 目

getutmp (3), utmp (5)

こ の 文 書 に つ い て

こ の man ペ ー ジ は Linux man-pages プ ロ ジ ェ ク ト の リ リ ー ス 5.10 の 一 部 で あ る 。 プ ロ ジ ェ ク ト の 説 明 と バ グ 報 告 に 関 す る 情 報 は https://www.kernel.org/doc/man-pages/ に 書 か れ て い る 。