release/man3/getutent.3

   1 .\" Copyright 1995 Mark D. Roth (roth@uiuc.edu)
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .\" References consulted:
  25 .\"     Linux libc source code
  26 .\"     Solaris manpages
  27 .\"
  28 .\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt
  29 .\"     <michael@cantor.informatik.rwth-aachen.de>
  30 .\"
  31 .\"*******************************************************************
  32 .\"
  33 .\" This file was generated with po4a. Translate the source file.
  34 .\"
  35 .\"*******************************************************************
  36 .\"
  37 .\" Japanese Version Copyright (c) 1998 NAKANO Takeo all rights reserved.
  38 .\" Translated 1998-03-15, NAKANO Takeo <nakano@apm.seikei.ac.jp>
  39 .\" Updated 2001-10-16, Kentaro Shirakata <argrath@ub32.org>
  40 .\" Updated 2002-01-03, Kentaro Shirakata <argrath@ub32.org>
  41 .\" Updated 2005-03-18, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  42 .\" Updated 2008-08-11, Akihiro MOTOKI, LDP v3.05
  43 .\" Updated 2012-05-29, Akihiro MOTOKI <amotoki@gmail.com>
  44 .\" Updated 2013-03-26, Akihiro MOTOKI <amotoki@gmail.com>
  45 .\" Updated 2013-07-22, Akihiro MOTOKI <amotoki@gmail.com>
  46 .\"
  47 .TH GETUTENT 3 2014\-08\-19 "" "Linux Programmer's Manual"
  48 .SH 名前
  49 getutent, getutid, getutline, pututline, setutent, endutent, utmpname \- utmp
  50 ファイルのエントリーにアクセスする
  51 .SH 書式
  52 \fB#include <utmp.h>\fP
  53 .sp
  54 \fBstruct utmp *getutent(void);\fP
  55 .br
  56 \fBstruct utmp *getutid(const struct utmp *\fP\fIut\fP\fB);\fP
  57 .br
  58 \fBstruct utmp *getutline(const struct utmp *\fP\fIut\fP\fB);\fP
  59 .sp
  60 \fBstruct utmp *pututline(const struct utmp *\fP\fIut\fP\fB);\fP
  61 .sp
  62 \fBvoid setutent(void);\fP
  63 .br
  64 \fBvoid endutent(void);\fP
  65 .sp
  66 \fBint utmpname(const char *\fP\fIfile\fP\fB);\fP
  67 .SH 説明
  68 新しいアプリケーションでは、これらの関数の "utmpx" 版を使用すべきである。 これらは POSIX.1 で規定されている。「準拠」の節を参照。
  69
  70 \fButmpname\fP()  は、他の utmp 関数がアクセスする (utmp フォーマットの)  ファイルの名前を指定する。他の関数を使う前に
  71 \fButmpname\fP()  を使って ファイル名の指定を行わなかった場合は、 \fI<path.h>\fP で 定義されている
  72 \fB_PATH_UTMP\fP がファイル名とみなされる。
  73 .PP
  74 \fBsetutent\fP()  は、ファイルポインターを utmp ファイルの先頭に移動する。
  75 一般的には、他の関数を使う前にこの関数を呼び出しておくと良いだろう。
  76 .PP
  77 \fBendutent\fP()  は utmp ファイルをクローズする。ユーザーコードで
  78 他の関数を使ってこのファイルにアクセスを行った時は、最後にこの関数を 呼び出すべきである。
  79 .PP
  80 \fBgetutent\fP()  は utmp ファイルの現在のファイル位置から一行読み込み、 行の各フィールドの内容を収めた構造体へのポインターを返す。
  81 この構造体の定義は \fButmp\fP(5)  に書かれている。
  82 .PP
  83 \fBgetutid\fP()  は、 utmp ファイル中の現在の位置から順方向 (末尾に向かう方向) へ \fIut\fP に基く検索を行う。
  84 \fIut\fP\->ut_type が \fBRUN_LVL\fP, \fBBOOT_TIME\fP, \fBNEW_TIME\fP, \fBOLD_TIME\fP の
  85 いずれかなら、 \fBgetutid\fP()  は \fBut_type\fP フィールドが \fIut\fP\->ut_type
  86 に一致する最初のエントリーを探す。 \fIut\fP\->ut_type が \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP,
  87 \fBUSER_PROCESS\fP, \fBDEAD_PROCESS\fP のいずれかなら、 \fBgetutid\fP()  は \fIut_id\fP フィールドが
  88 \fIut\fP\->ut_id に 一致する最初のエントリーを探す。
  89 .PP
  90 \fBgetutline\fP()  は、 utmp ファイルの現在の位置から末尾に向かって検索を行う。 \fIut_type\fP が
  91 \fBUSER_PROCESS\fP または \fBLOGIN_PROCESS\fP で、 \fIut_line\fP フィールドが \fIut\fP\->ut_line
  92 にマッチする最初の行を返す。
  93 .PP
  94 \fBpututline\fP()  は \fIutmp\fP 構造体 \fIut\fP の内容を utmp ファイルに書き出す。 \fBpututline\fP()  は
  95 \fBgetutid\fP()  を用いて、新たなエントリーを 挿入するのにふさわしい場所を探す。 \fIut\fP を挿入するふさわしい場所が
  96 見つからない場合は、新たなエントリーをファイルの末尾に追加する。
  97 .SH 返り値
  98 \fBgetutent\fP(), \fBgetutid\fP(), \fBgetutline\fP()  は、成功すると \fIstruct utmp\fP
  99 へのポインターを返す。 失敗すると NULL を返す (レコードが見つからなかった場合も失敗となる)。 この \fIstruct utmp\fP
 100 は静的な記憶領域に確保され、次にこれらの関数を 呼び出した際に上書きされるかもしれない。
 101
 102 \fBpututline\fP()  は成功すると \fIut\fP を返す。失敗すると NULL を返す。
 103
 104 \fButmpname\fP()  は、新しい名前の格納に成功すると 0 を返し、失敗すると \-1 を返す。
 105
 106 エラーが発生した場合、これらの関数は \fIerrno\fP にエラーの原因を示す値を設定する。
 107 .SH エラー
 108 .TP
 109 \fBENOMEM\fP
 110 メモリー不足。
 111 .TP
 112 \fBESRCH\fP
 113 レコードが見つからなかった。
 114 .PP
 115 関数 \fBsetutent\fP(), \fBpututline\fP(), \fBgetut*\fP()  は \fBopen\fP(2)
 116 に書かれている理由でも失敗することがある。
 117 .SH ファイル
 118 /var/run/utmp 現在ログイン中のユーザーのデータベース
 119 .br
 120 /var/log/wtmp 過去のユーザーログインのデータベース
 121 .SH 準拠
 122 XPG2, SVr4.
 123 .LP
 124 XPG2 と SVID 2 では、 \fBpututline\fP() 関数は値を返さないとされており、 (AIX, HP\-UX などの)
 125 多くのシステムではそうなっている。 HP\-UX では、上述の \fBpututline\fP() と同じプロトタイプを持つ 新しい関数
 126 \fB_pututline\fP() が導入されている。
 127 .LP
 128 現在では、Linux 以外のシステムでは、これらの関数は全て廃止されている。 SUSv1 の後に出てきた POSIX.1\-2001
 129 では、もはやこれらの関数はなく、 代わりに以下のものを使う。
 130 .sp
 131 \fB#include <utmpx.h>\fP
 132 .sp
 133 \fBstruct utmpx *getutxent(void);\fP
 134 .br
 135 \fBstruct utmpx *getutxid(const struct utmpx *);\fP
 136 .br
 137 \fBstruct utmpx *getutxline(const struct utmpx *);\fP
 138 .br
 139 \fBstruct utmpx *pututxline(const struct utmpx *);\fP
 140 .br
 141 \fBvoid setutxent(void);\fP
 142 .br
 143 \fBvoid endutxent(void);\fP
 144 .PP
 145 これらの関数は glibc により提供されており、 "x" がない関数と同じ処理を行うが、 \fIstruct utmpx\fP を使用する。 Linux
 146 では、この構造体の定義は \fIstruct utmp\fP と同じになっている。 完全を期すために、glibc では \fButmpxname\fP()
 147 も提供している。この関数は POSIX.1 では規定されていない。
 148 .PP
 149 Linux 以外のシステムでは、 \fIutmpx\fP 構造体は \fIutmp\fP 構造体の上位集合 (superset) になっていて、
 150 追加のフィールドがあったり、既存のフィールドのサイズが大きくなっていたり するものもある。複数のファイルが使用されている場合もあり、多くの場合
 151 \fI/var/*/utmpx\fP と \fI/var/*/wtmpx\fP というファイルが使われる。
 152 .LP
 153 一方、 Linux glibc では複数の \fIutmpx\fP ファイル は使われていない。
 154 \fIutmp\fP 構造体が十分に大きいからである。
 155 上記の名前に "x" が付いた関数は "x" が付いていない対応する関数の別名と
 156 なっている (例えば \fIgetutxent\fP() は \fIgetutent\fP() の別名である)。
 157 .SH 注意
 158 .SS "glibc での注意"
 159 上記の関数群はスレッドセーフではない。 glibc にはリエントラント版 (reentrant) が追加されている。
 160 .sp
 161 .nf
 162 \fB#define _GNU_SOURCE\fP    /* or _SVID_SOURCE or _BSD_SOURCE;
 163 \&                          \fBfeature_test_macros\fP(7) 参照 */
 164 \fB#include <utmp.h>\fP
 165 .sp
 166 \fBint getutent_r(struct utmp *\fP\fIubuf\fP\fB, struct utmp **\fP\fIubufp\fP\fB);\fP
 167 .sp
 168 \fBint getutid_r(struct utmp *\fP\fIut\fP\fB,\fP
 169 \fB              struct utmp *\fP\fIubuf\fP\fB, struct utmp **\fP\fIubufp\fP\fB);\fP
 170 .sp
 171 \fBint getutline_r(struct utmp *\fP\fIut\fP\fB,\fP
 172 \fB                struct utmp *\fP\fIubuf\fP\fB, struct utmp **\fP\fIubufp\fP\fB);\fP
 173 .fi
 174 .sp
 175 これらの関数は GNU での拡張であり、末尾の _r をとった名前の関数と 同様の機能を持つ。 \fIubuf\fP
 176 パラメーターは結果を格納する場所を指定する。 成功すると 0 を返し、結果へのポインターを \fI*ubufp\fP に書き込む。エラーの場合 \-1 を返す。
 177 上記の関数に対応する utmpx 版は存在しない (POSIX.1 ではこれらの関数を規定されていない)。
 178 .SH 例
 179 以下の例では、 utmp のレコードの追加・削除を行っている。このコードは、 擬似端末 (pseudo terminal)
 180 から実行されることを想定している。 実際のアプリケーションでは \fBgetpwuid\fP(3)  と \fBttyname\fP(3)
 181 の戻り値を検査するべきである。
 182 .PP
 183 .nf
 184 #include <string.h>
 185 #include <stdlib.h>
 186 #include <pwd.h>
 187 #include <unistd.h>
 188 #include <utmp.h>
 189
 190 int
 191 main(int argc, char *argv[])
 192 {
 193     struct utmp entry;
 194
 195     system("echo before adding entry:;who");
 196
 197     entry.ut_type = USER_PROCESS;
 198     entry.ut_pid = getpid();
 199     strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
 200     /* only correct for ptys named /dev/tty[pqr][0\-9a\-z] */
 201     strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
 202     time(&entry.ut_time);
 203     strcpy(entry.ut_user, getpwuid(getuid())\->pw_name);
 204     memset(entry.ut_host, 0, UT_HOSTSIZE);
 205     entry.ut_addr = 0;
 206     setutent();
 207     pututline(&entry);
 208
 209     system("echo after adding entry:;who");
 210
 211     entry.ut_type = DEAD_PROCESS;
 212     memset(entry.ut_line, 0, UT_LINESIZE);
 213     entry.ut_time = 0;
 214     memset(entry.ut_user, 0, UT_NAMESIZE);
 215     setutent();
 216     pututline(&entry);
 217
 218     system("echo after removing entry:;who");
 219
 220     endutent();
 221     exit(EXIT_SUCCESS);
 222 }
 223 .fi
 224 .SH 関連項目
 225 \fBgetutmp\fP(3), \fButmp\fP(5)
 226 .SH この文書について
 227 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
 228 である。プロジェクトの説明とバグ報告に関する情報は
 229 http://www.kernel.org/doc/man\-pages/ に書かれている。