[linuxjm/LDP_man-pages.git] / draft / man3 / getutent.3

.\" Copyright 1995 Mark D. Roth (roth@uiuc.edu)
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.\" References consulted:
.\"     Linux libc source code
.\"     Solaris manpages
.\"
.\" Modified Thu Jul 25 14:43:46 MET DST 1996 by Michael Haardt
.\"     <michael@cantor.informatik.rwth-aachen.de>
.\"
.\" Japanese Version Copyright (c) 1998 NAKANO Takeo all rights reserved.
.\" Translated 1998-03-15, NAKANO Takeo <nakano@apm.seikei.ac.jp>
.\" Updated 2001-10-16, Kentaro Shirakata <argrath@ub32.org>
.\" Updated 2002-01-03, Kentaro Shirakata <argrath@ub32.org>
.\" Updated 2005-03-18, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
.\" Updated 2008-08-11, Akihiro MOTOKI, LDP v3.05
.\"
.TH GETUTENT 3 2008-06-29 "" "Linux Programmer's Manual"
.\"O .SH NAME
.SH 名前
.\"O getutent, getutid, getutline, pututline, setutent, endutent,
.\"O utmpname \- access utmp file entries
getutent, getutid, getutline, pututline, setutent, endutent, utmpname \-
utmp ファイルのエントリにアクセスする
.\"O .SH SYNOPSIS
.SH 書式
.B #include <utmp.h>
.sp
.B struct utmp *getutent(void);
.br
.BI "struct utmp *getutid(struct utmp *" ut );
.br
.BI "struct utmp *getutline(struct utmp *" ut );
.sp
.BI "struct utmp *pututline(struct utmp *" ut );
.sp
.B void setutent(void);
.br
.B void endutent(void);
.sp
.BI "int utmpname(const char *" file );
.\"O .SH DESCRIPTION
.SH 説明
.\"O New applications should use the POSIX.1-specified "utmpx" versions of
.\"O these functions; see CONFORMING TO.
新しいアプリケーションでは、これらの関数の "utmpx" 版を使用すべきである。
これらは POSIX.1 で規定されている。「準拠」の節を参照。

.\"O .BR utmpname ()
.\"O sets the name of the utmp-format file for the other utmp
.\"O functions to access.
.\"O If
.\"O .BR utmpname ()
.\"O is not used to set the filename
.\"O before the other functions are used, they assume \fB_PATH_UTMP\fP, as
.\"O defined in \fI<paths.h>\fP.
.BR utmpname ()
は、他の utmp 関数がアクセスする (utmp フォーマットの)
ファイルの名前を指定する。他の関数を使う前に
.BR utmpname ()
を使って
ファイル名の指定を行わなかった場合は、 \fI<path.h>\fP で
定義されている \fB_PATH_UTMP\fP がファイル名とみなされる。
.PP
.\"O .BR setutent ()
.\"O rewinds the file pointer to the beginning of the utmp file.
.\"O It is generally a good idea to call it before any of the other
.\"O functions.
.BR setutent ()
は、ファイルポインタを utmp ファイルの先頭に移動する。
一般的には、他の関数を使う前にこの関数を呼び出しておくと良いだろう。
.PP
.\"O .BR endutent ()
.\"O closes the utmp file.
.\"O It should be called when the user
.\"O code is done accessing the file with the other functions.
.BR endutent ()
は utmp ファイルをクローズする。ユーザーコードで
他の関数を使ってこのファイルにアクセスを行った時は、最後にこの関数を
呼び出すべきである。
.PP
.\"O .BR getutent ()
.\"O reads a line from the current file position in the utmp file.
.\"O It returns a pointer to a structure containing the fields of
.\"O the line.
.BR getutent ()
は utmp ファイルの現在のファイル位置から一行読み込み、
行の各フィールドの内容を収めた構造体へのポインタを返す。
.\"O The definition of this structure is shown in
.\"O .BR utmp (5).
この構造体の定義は
.BR utmp (5)
に書かれている。
.PP
.\"O .BR getutid ()
.\"O searches forward from the current file position in the utmp
.\"O file based upon \fIut\fP.
.\"O If \fIut\fP\->ut_type is one of \fBRUN_LVL\fP,
.\"O \fBBOOT_TIME\fP, \fBNEW_TIME\fP, or \fBOLD_TIME\fP,
.\"O .BR getutid ()
.\"O will
.\"O find the first entry whose \fIut_type\fP field matches \fIut\fP\->ut_type.
.\"O If \fIut\fP\->ut_type is one of \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP,
.\"O \fBUSER_PROCESS\fP, or \fBDEAD_PROCESS\fP,
.\"O .BR getutid ()
.\"O will find the
.\"O first entry whose
.\"O .I ut_id
.\"O field matches \fIut\fP\->ut_id.
.BR getutid ()
は、 utmp ファイル中の現在の位置から順方向
(末尾に向かう方向) へ \fIut\fP に基く検索を行う。 \fIut\fP\->ut_type が
\fBRUN_LVL\fP, \fBBOOT_TIME\fP, \fBNEW_TIME\fP, \fBOLD_TIME\fP の
いずれかなら、
.BR getutid ()
は \fBut_type\fP フィールドが
\fIut\fP\->ut_type に一致する最初のエントリを探す。
\fIut\fP\->ut_type が \fBINIT_PROCESS\fP, \fBLOGIN_PROCESS\fP,
\fBUSER_PROCESS\fP, \fBDEAD_PROCESS\fP のいずれかなら、
.BR getutid ()
は
.I ut_id
フィールドが \fIut\fP\->ut_id に
一致する最初のエントリを探す。
.PP
.\"O .BR getutline ()
.\"O searches forward from the current file position in the utmp file.
.\"O It scans entries whose
.\"O .I ut_type
.\"O is \fBUSER_PROCESS\fP
.\"O or \fBLOGIN_PROCESS\fP and returns the first one whose
.\"O .I ut_line
.\"O field
.\"O matches \fIut\->ut_line\fP.
.BR getutline ()
は、 utmp ファイルの現在の位置から末尾に向かって検索を行う。
.I ut_type
が \fBUSER_PROCESS\fP または \fBLOGIN_PROCESS\fP で、
.I ut_line
フィールドが \fIut\fP->ut_line にマッチする最初の行を返す。
.PP
.\"O .BR pututline ()
.\"O writes the
.\"O .I utmp
.\"O structure \fIut\fP into the utmp file.
.\"O It uses
.\"O .BR getutid ()
.\"O to search for the proper place in the file to insert
.\"O the new entry.
.\"O If it cannot find an appropriate slot for \fIut\fP,
.\"O .BR pututline ()
.\"O will append the new entry to the end of the file.
.BR pututline ()
は
.I utmp
構造体 \fIut\fP の内容を utmp ファイルに書き出す。
.BR pututline ()
は
.BR getutid ()
を用いて、新たなエントリを
挿入するのにふさわしい場所を探す。 \fIut\fP を挿入するふさわしい場所が
見つからない場合は、新たなエントリをファイルの末尾に追加する。
.\"O .SH "RETURN VALUE"
.SH 返り値
.\"O .BR getutent (),
.\"O .BR getutid (),
.\"O and
.\"O .BR getutline ()
.\"O return a pointer to a \fIstruct utmp\fP on success,
.\"O and NULL on failure (which includes the "record not found" case).
.\"O This \fIstruct utmp\fP is allocated in static storage, and may be
.\"O overwritten by subsequent calls.
.BR getutent (),
.BR getutid (),
.BR getutline ()
は、成功すると \fIstruct utmp\fP へのポインタを返す。
失敗すると NULL を返す (レコードが見つからなかった場合も失敗となる)。
この \fIstruct utmp\fP は静的な記憶領域に確保され、次にこれらの関数を
呼び出した際に上書きされるかもしれない。

.\"O On success
.\"O .BR pututline ()
.\"O returns
.\"O .IR ut ;
.\"O on failure, it returns NULL.
.BR pututline ()
は成功すると
.I ut
を返す。失敗すると NULL を返す。

.\"O .BR utmpname ()
.\"O returns 0 if the new name was successfully stored, or \-1 on failure.
.BR utmpname ()
は、新しい名前の格納に成功すると 0 を返し、失敗すると \-1 を返す。
.\"O .SH ERRORS
.SH エラー
.TP
.B ENOMEM
.\"O Out of memory.
メモリ不足。
.TP
.B ESRCH
.\"O Record not found.
レコードが見つからなかった。
.PP
.\"O .BR setutent (),
.\"O .BR pututline (),
.\"O and the
.\"O .B getut* ()
.\"O functions can also fail for the reasons described in
.\"O .BR open (2).
関数
.BR setutent (),
.BR pututline (),
.BR getut* ()
は
.BR open (2)
に書かれている理由でも失敗することがある。
.\"O .SH FILES
.SH ファイル
.\"O /var/run/utmp      database of currently logged-in users
.\"O .br
.\"O /var/log/wtmp      database of past user logins
/var/run/utmp     現在ログイン中のユーザーのデータベース
.br
/var/log/wtmp     過去のユーザーログインのデータベース
.\"O .SH "CONFORMING TO"
.SH 準拠
XPG2, SVr4.
.LP
.\"O In XPG2 and SVID 2 the function
.\"O .BR pututline ()
.\"O is documented
.\"O to return void, and that is what it does on many systems
.\"O (AIX, HP-UX, Linux libc5).
XPG2 と SVID 2 では、
.BR pututline ()
関数は値を返さないとされており、
(AIX, HP-UX, Linux libc5 などの) 多くのシステムではそうなっている。
.\"O HP-UX introduces a new function
.\"O .BR _pututline ()
.\"O with the prototype given above for
.\"O .BR pututline ()
.\"O (also found in Linux libc5).
HP-UX では、上述の
.BR pututline ()
と同じプロトタイプを持つ
新しい関数
.BR _pututline ()
が導入されている
(この関数は Linux libc5 にもある)。
.LP
.\"O All these functions are obsolete now on non-Linux systems.
現在では、Linux 以外のシステムでは、これらの関数は全て廃止されている。
.\"O POSIX.1-2001, following SUSv1,
.\"O does not have any of these functions, but instead uses
SUSv1 の後に出てきた POSIX.1-2001 では、もはやこれらの関数はなく、
代わりに以下のものを使う。
.sp
.B #include <utmpx.h>
.sp
.B struct utmpx *getutxent(void);
.br
.B struct utmpx *getutxid(const struct utmpx *);
.br
.B struct utmpx *getutxline(const struct utmpx *);
.br
.B struct utmpx *pututxline(const struct utmpx *);
.br
.B void setutxent(void);
.br
.B void endutxent(void);
.PP
.\"O These functions are provided by glibc,
.\"O and perform the same task as their equivalents without the "x", but use
.\"O .IR "struct utmpx" ,
.\"O defined on Linux to be the same as
.\"O .IR "struct utmp" .
.\"O For completeness, glibc also provides
.\"O .BR utmpxname (),
.\"O although this function is not specified by POSIX.1.
これらの関数は glibc により提供されており、
"x" がない関数と同じ処理を行うが、
.I "struct utmpx"
を使用する。
Linux では、この構造体の定義は
.I "struct utmp"
と同じになっている。
完全を期すために、glibc では
.BR utmpxname ()
も提供している。この関数は POSIX.1 では規定されていない。
.PP
.\"O On some other systems,
.\"O the \fIutmpx\fP structure is a superset of the \fIutmp\fP structure,
.\"O with additional fields, and larger versions of the existing fields,
.\"O and parallel files are maintained, often
.\"O .I /var/*/utmpx
.\"O and
.\"O .IR /var/*/wtmpx .
Linux 以外のシステムでは、
\fIutmpx\fP 構造体は \fIutmp\fP 構造体の上位集合 (superset) になっていて、
追加のフィールドがあったり、既存のフィールドのサイズが大きくなっていたり
するものもある。複数のファイルが使用されている場合もあり、多くの場合
.I /var/*/utmpx
と
.I /var/*/wtmpx
というファイルが使われる。
.LP
.\"O Linux glibc on the other hand does not use a parallel \fIutmpx\fP file
.\"O since its \fIutmp\fP structure is already large enough.
.\"O The functions \fBgetutxent\fP()
.\"O etc. are aliases for \fBgetutent\fP() etc.
一方、 Linux glibc では複数の \fIutmpx\fP ファイル は使われていない。
\fIutmp\fP 構造体が十分に大きいからである。
\fIgetutxent\fP() などの関数は \fIgetutent\fP() などの別名となっている。
.\"O .SH NOTES
.SH 注意
.\"O .SS Glibc Notes
.SS glibc での注意
.\"O The above functions are not thread-safe.
.\"O Glibc adds reentrant versions
上記の関数群はスレッド・セーフではない。
glibc にはリエントラント版 (reentrant) が追加されている。
.sp
.nf
.BR "#define _GNU_SOURCE" "    /* or _SVID_SOURCE or _BSD_SOURCE;
.\"O .RB "\&                          see " feature_test_macros(7) " */"
.RB "\&                          " feature_test_macros(7) " 参照 */"
.B #include <utmp.h>
.sp
.BI "int getutent_r(struct utmp *" ubuf ", struct utmp **" ubufp );
.sp
.BI "int getutid_r(struct utmp *" ut ,
.BI "              struct utmp *" ubuf ", struct utmp **" ubufp );
.sp
.BI "int getutline_r(struct utmp *" ut ,
.BI "                struct utmp *" ubuf ", struct utmp **" ubufp );
.fi
.sp
.\"O These functions are GNU extensions, analogs of the functions of the
.\"O same name without the _r suffix.
.\"O The
.\"O .I ubuf
.\"O argument gives these functions a place to store their result.
.\"O On success they return 0, and a pointer to the result is written in
.\"O .IR *ubufp .
.\"O On error these functions return \-1.
.\"O There are no utmpx equivalents of the above functions.
.\"O (POSIX.1 does not specify such functions.)
これらの関数は GNU での拡張であり、末尾の _r をとった名前の関数と
同様の機能を持つ。
.I ubuf
パラメータは結果を格納する場所を指定する。
成功すると 0 を返し、結果へのポインタを
.I *ubufp
に書き込む。エラーの場合 \-1 を返す。
上記の関数に対応する utmpx 版は存在しない
(POSIX.1 ではこれらの関数を規定されていない)。
.\"O .SH EXAMPLE
.SH 例
.\"O The following example adds and removes a utmp record, assuming it is run
.\"O from within a pseudo terminal.
.\"O For usage in a real application, you
.\"O should check the return values of
.\"O .BR getpwuid (3)
.\"O and
.\"O .BR ttyname (3).
以下の例では、 utmp のレコードの追加・削除を行っている。このコードは、
擬似端末 (pseudo terminal) から実行されることを想定している。
実際のアプリケーションでは
.BR getpwuid (3)
と
.BR ttyname (3)
の戻り値を検査するべきである。
.PP
.nf
#include <string.h>
#include <stdlib.h>
#include <pwd.h>
#include <unistd.h>
#include <utmp.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);
}
.fi
.\"O .SH "SEE ALSO"
.SH 関連項目
.BR getutmp (3),
.BR utmp (5)