.\" 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$
.Dd September 20, 1994
.Dt GETPWENT 3
.Os
.Sh 名称
.Nm getpwent ,
.Nm getpwnam ,
.Nm getpwuid ,
.Nm setpassent ,
.Nm setpwent ,
.Nm endpwent
.Nd パスワードデータベースを操作
.Sh 書式
.Fd #include <sys/types.h>
.Fd #include <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
は与えられたユーザ
uid
を、それぞれパスワードデータベースで検索し、常に最初に出会った
エントリを返します。
.Pp
.Fn getpwent
関数はパスワードデータベースを順次読み込みます。ユーザの完全
リストを処理したいプログラム向きです。
.Pp
.Fn setpassent
関数は
2 つの目的を遂行します。まず
.Fn getpwent
にデータベースの最初へ
``rewind'' (リワインド)
させます。さらに
.Fa stayopen
がゼロ
でなければ、ファイル記述子をオープンしたままにします。これらルーチン
すべての以後のアクセスが、このためきわめて高速化されます。
(ただし
.Fn getpwent
の場合、デフォルトで記述子をクローズしないので後者の機能性は
不要です。)
.Pp
プログラム実行中に更新されるとデータベースが古くなるので、長時間実行
プログラムでファイル記述子をオープンしたままにすることは危険です。
.Pp
.Fn setpwent
関数は、引数ゼロを持つ
.Fn setpassent
と同じです。
.Pp
.Fn endpwent
関数は、オープンしているファイルをすべてクローズします。
.Pp
これらのルーチンは、パスワードファイルを
``shadow'' (シャドウ)
する目的で
書かれました。たとえば、暗号化パスワードにアクセスできるプログラムが
限定できるようにです。たとえば、これらを呼び出す処理の
uid
が有効な
0 ならばパスワードを返し、その他の場合は構造体のパスワードフィールドに、
ストリング
.Ql *
を示して返します。
.Sh YP/NIS の相互作用
.Xr yp 4
パスワード
データベースが使用可能な場合、ローカルのデータベースに
要求されたパスワードエントリが見付からないと、
.Fn getpwnam
および
.Fn getpwuid
関数はそれぞれ、
YP
マップ
.Dq Li passwd.byname
および
.Dq Li passwd.byuid
を使用します。
.Xr passwd 5
で記述されたとおりに全体マップが使用可能ならば、
.Fn getpwent
関数は
YP
マップ
.Dq Li passwd.byname
を通ります。
.Sh 戻り値
関数
.Fn getpwent
、
.Fn getpwnam
および
.Fn getpwuid
は、いずれも成功すると、
 passwd
構造体の有効なポインタを返します。エンドオブファイルに到達するか
エラーが発生した場合は、
null
ポインタが返ります。
.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
は、それぞれの結果を内部の
静的オブジェクトに残し、そのオブジェクトのポインタを返します。後に続く同じ
関数の呼び出しは、この同じオブジェクトを改変します。