.\" Copyright (c) 1988, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     From: @(#)getpwent.3	8.2 (Berkeley) 12/11/93
.\" %FreeBSD: src/lib/libc/gen/getpwent.3,v 1.11.2.4 2001/12/14 18:33:51 ru Exp %
.\" $FreeBSD$
.\"
.Dd September 20, 1994
.Dt GETPWENT 3
.Os
.Sh 名称
.Nm getpwent ,
.Nm getpwnam ,
.Nm getpwuid ,
.Nm setpassent ,
.Nm setpwent ,
.Nm endpwent
.Nd パスワードデータベースを操作
.Sh ライブラリ
.Lb libc
.Sh 書式
.In sys/types.h
.In pwd.h
.Ft struct passwd *
.Fn getpwent void
.Ft struct passwd *
.Fn getpwnam "const char *login"
.Ft struct passwd *
.Fn getpwuid "uid_t uid"
.Ft int
.Fn setpassent "int  stayopen"
.Ft void
.Fn setpwent void
.Ft void
.Fn endpwent void
.Sh 解説
これらの関数は、
.Xr passwd 5
に記述されたパスワードデータベースファイルを
操作します。データベースの各エントリは、インクルードファイル
.Aq Pa pwd.h
にある構造体
.Ar passwd
で定義されます。次の通りです。
.Bd -literal -offset indent
struct passwd {
	char	*pw_name;	/* ユーザ名 */
	char	*pw_passwd;	/* 暗号化されたパスワード */
	uid_t	pw_uid;		/* ユーザ uid */
	gid_t	pw_gid;		/* ユーザ gid */
	time_t	pw_change;	/* パスワードの変更時刻 */
	char	*pw_class;	/* ユーザアクセスクラス */
	char	*pw_gecos;	/* ハネウエルログイン情報 */
	char	*pw_dir;	/* ホームディレクトリ */
	char	*pw_shell;	/* デフォルトのシェル */
	time_t	pw_expire;	/* アカウント有効期限 */
	int	pw_fields;	/* 内部フィールド: 充てんフィールド */
};
.Ed
.Pp
関数
.Fn getpwnam
は与えられたログイン名を、
.Fn getpwuid
は与えられたユーザ ID を
それぞれパスワードデータベースで検索し、常に最初に遭遇した
エントリを返します。
.Pp
.Fn getpwent
関数はパスワードデータベースを順次読み込みます。ユーザの完全な
リストを処理したいプログラム向きです。
.Pp
.Fn setpassent
関数は
2 つの目的を果たすものです。まず
.Fn getpwent
関数がデータベースの最初へ「巻き戻す (rewind)」
ようにします。さらに
.Fa stayopen
が 0
でなければ、ファイル記述子をオープンしたままにします。
これにより、これらのルーチンに対するその後のアクセスすべてが
極めて高速化されます
(ただし
.Fn getpwent
の場合、デフォルトでファイル記述子をクローズしないので
後者の機能は不要です)。
.Pp
長時間実行されているプログラムでファイル記述子をオープンした
ままにしておくのは危険です。なぜなら、プログラムが実行されて
いる間にデータベースが更新されると、オープンしたままにしている
データベースは古い物になってしまうからです。
.Pp
.Fn setpwent
関数は、引数を 0 にした
.Fn setpassent
と同じです。
.Pp
.Fn endpwent
関数は、オープンしているファイルをすべてクローズします。
.Pp
これらのルーチンは、パスワードファイルを
「隠す (shadow)」目的で
書かれました。たとえば、暗号化パスワードにアクセスできる
プログラムを限定できるようにです。これらのルーチンを
呼び出すプロセスの有効ユーザ ID が 0 ならば暗号化パスワードを返し、
その他の場合は戻り値である構造体のパスワードフィールドは
ストリング
.Ql *
を指すようになります。
.Sh YP/NIS の相互作用
.Xr yp 4
パスワード
データベースが使用可能な場合、ローカルのデータベースに
要求されたパスワードエントリが見つからないと、
.Fn getpwnam
および
.Fn getpwuid
関数はそれぞれ、
.Dq Li passwd.byname
および
.Dq Li passwd.byuid
YP マップを使用します。
.Xr passwd 5
で記述されているようにマップ全体が使用可能である場合は、
.Fn getpwent
関数は
YP マップ
.Dq Li passwd.byname
を一通り読みます。
.Sh 戻り値
関数
.Fn getpwent ,
.Fn getpwnam
および
.Fn getpwuid
は、いずれも成功すると、
passwd 構造体への有効なポインタを返します。
ファイルの終端に到達するか、もしくはエラーが発生した場合は
ヌルポインタを返します。
.Fn setpassent
関数は、失敗した場合は 0 を、成功した場合は
1 を返します。
.Fn endpwent
および
.Fn setpwent
関数の戻り値はありません。
.Sh 関連ファイル
.Bl -tag -width /etc/master.passwd -compact
.It Pa /etc/pwd.db
安全ではないパスワードデータベースファイル
.It Pa /etc/spwd.db
安全なパスワードデータベースファイル
.It Pa /etc/master.passwd   
現在のパスワードファイル
.It Pa /etc/passwd
Version 7
形式のパスワードファイル
.El
.Sh 関連項目
.Xr getlogin 2 ,
.Xr getgrent 3 ,
.Xr yp 4 ,
.Xr passwd 5 ,
.Xr pwd_mkdb 8 ,
.Xr vipw 8
.Sh 歴史
.Fn getpwent ,
.Fn getpwnam ,
.Fn getpwuid ,
.Fn setpwent
および
.Fn endpwent
関数は、
.At v7
ではじめて登場しました。
.Fn setpassent
関数は
.Bx 4.3 Reno
で登場しました。
.Sh 互換性
歴史的な理由で存在していた、
代替パスワードデータベースの規格を許した関数
.Xr setpwfile 3
は非推奨になっており、もう使用できません。
.Sh バグ
関数
.Fn getpwent ,
.Fn getpwnam
および
.Fn getpwuid
は、呼び出し結果を内部の静的オブジェクトに残し、
そのオブジェクトを指すポインタを返します。その後、
同じ関数を呼び出すと、同じオブジェクトを変更していきます。