draft/man3/getpwent_r.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  21 .\" USA.
  22 .\"
  23 .\" Japanese Version Copyright (c) 2004 Yuichi SATO
  24 .\"         all rights reserved.
  25 .\" Translated Sun Aug  8 00:53:40 JST 2004
  26 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>
  27 .\"
  28 .TH GETPWENT_R 3 2010-10-21 "GNU" "Linux Programmer's Manual"
  29 .\"O .SH NAME
  30 .SH 名前
  31 .\"O getpwent_r, fgetpwent_r \- get passwd file entry reentrantly
  32 getpwent_r, fgetpwent_r \- パスワードファイルのエントリを
  33 リエントラントで取り出す
  34 .\"O .SH SYNOPSIS
  35 .SH 書式
  36 .nf
  37 .B #include <pwd.h>
  38 .sp
  39 .BI "int getpwent_r(struct passwd *" pwbuf ", char *" buf ,
  40 .br
  41 .BI "               size_t " buflen ", struct passwd **" pwbufp );
  42 .sp
  43 .BI "int fgetpwent_r(FILE *" fp ", struct passwd *" pwbuf ", char *" buf ,
  44 .br
  45 .BI "                size_t " buflen ", struct passwd **" pwbufp );
  46 .fi
  47 .sp
  48 .in -4n
  49 .\"O Feature Test Macro Requirements for glibc (see
  50 .\"O .BR feature_test_macros (7)):
  51 glibc 向けの機能検査マクロの要件
  52 .RB ( feature_test_macros (7)
  53 参照):
  54 .in
  55 .sp
  56 .BR getpwent_r (),
  57 _BSD_SOURCE || _SVID_SOURCE
  58 .br
  59 .BR fgetpwent_r ():
  60 _SVID_SOURCE
  61 .\"O .SH DESCRIPTION
  62 .SH 説明
  63 .\"O The functions
  64 .\"O .BR getpwent_r ()
  65 .\"O and
  66 .\"O .BR fgetpwent_r ()
  67 .\"O are the reentrant versions of
  68 .\"O .BR getpwent (3)
  69 .\"O and
  70 .\"O .BR fgetpwent (3).
  71 関数
  72 .BR getpwent_r ()
  73 と
  74 .BR fgetpwent_r ()
  75 は
  76 .BR getpwent (3)
  77 と
  78 .BR fgetpwent (3)
  79 のリエントラント (reentrant) 版である。
  80 .\"O The former reads the next passwd entry from the stream initialized by
  81 .\"O .BR setpwent (3).
  82 前者は、
  83 .BR setpwent (3)
  84 によって初期化されたストリームから、次のパスワードエントリを読み込む。
  85 .\"O The latter reads the next passwd entry from the stream
  86 .\"O .IR fp .
  87 後者は、ストリーム
  88 .I fp
  89 から次のパスワードエントリを読み込む。
  90 .PP
  91 .\"O The \fIpasswd\fP structure is defined in
  92 .\"O .I <pwd.h>
  93 .\"O as follows:
  94 \fIpasswd\fP 構造体は
  95 .I <pwd.h>
  96 において以下のように定義されている。
  97 .sp
  98 .in +4n
  99 .nf
 100 struct passwd {
 101 .\"O     char    *pw_name;      /* username */
 102 .\"O     char    *pw_passwd;    /* user password */
 103 .\"O     uid_t    pw_uid;       /* user ID */
 104 .\"O     gid_t    pw_gid;       /* group ID */
 105 .\"O     char    *pw_gecos;     /* user information */
 106 .\"O     char    *pw_dir;       /* home directory */
 107 .\"O     char    *pw_shell;     /* shell program */
 108     char    *pw_name;      /* ユーザ名 */
 109     char    *pw_passwd;    /* ユーザのパスワード */
 110     uid_t    pw_uid;       /* ユーザ ID */
 111     gid_t    pw_gid;       /* グループ ID */
 112     char    *pw_gecos;     /* ユーザ情報 */
 113     char    *pw_dir;       /* ホームディレクトリ */
 114     char    *pw_shell;     /* シェルプログラム */
 115 };
 116 .fi
 117 .in
 118 .PP
 119 .\"O For more information about the fields of this structure, see
 120 .\"O .BR passwd (5).
 121 この構造体のフィールドの詳細は
 122 .BR passwd (5)
 123 を参照のこと。
 124
 125 .\"O The nonreentrant functions return a pointer to static storage,
 126 .\"O where this static storage contains further pointers to user
 127 .\"O name, password, gecos field, home directory and shell.
 128 リエントラントでない関数は静的な格納領域へのポインタを返す。
 129 この静的な格納領域には、更にユーザ名・パスワード・gecos フィールド・
 130 ホームディレクトリ・シェルへのポインタが含まれる。
 131 .\"O The reentrant functions described here return all of that in
 132 .\"O caller-provided buffers.
 133 .\"O First of all there is the buffer
 134 .\"O .I pwbuf
 135 .\"O that can hold a \fIstruct passwd\fP.
 136 .\"O And next the buffer
 137 .\"O .I buf
 138 .\"O of size
 139 .\"O .I buflen
 140 .\"O that can hold additional strings.
 141 ここで説明されているリエントラント版の関数は、
 142 呼び出し側から提供されるバッファにユーザ名など全てを返す。
 143 最初の引き数として \fIstruct passwd\fP を保持できるバッファ
 144 .I pwbuf
 145 がある。
 146 次にその他の文字列を保持できるサイズ
 147 .I buflen
 148 のバッファ
 149 .I buf
 150 がある。
 151 .\"O The result of these functions, the \fIstruct passwd\fP read from the stream,
 152 .\"O is stored in the provided buffer
 153 .\"O .IR *pwbuf ,
 154 .\"O and a pointer to this \fIstruct passwd\fP is returned in
 155 .\"O .IR *pwbufp .
 156 これらの関数の結果 (ストリームから読み込まれた \fIstruct passwd\fP) は、
 157 提供されたバッファ
 158 .I *pwbuf
 159 に格納され、この \fIstruct passwd\fP へのポインタは
 160 .I *pwbufp
 161 に返される。
 162 .\"O .SH "RETURN VALUE"
 163 .SH 返り値
 164 .\"O On success, these functions return 0 and
 165 .\"O .I *pwbufp
 166 .\"O is a pointer to the \fIstruct passwd\fP.
 167 成功した場合、これらの関数は 0 を返し、
 168 .I *pwbufp
 169 は \fIstruct passwd\fP へのポインタとなる。
 170 エラーの場合、これらの関数はエラー値を返し、
 171 .I *pwbufp
 172 は NULL になる。
 173 .\"O .SH ERRORS
 174 .SH エラー
 175 .TP
 176 .B ENOENT
 177 .\"O No more entries.
 178 次のエントリがない。
 179 .TP
 180 .B ERANGE
 181 .\"O Insufficient buffer space supplied.
 182 .\"O Try again with larger buffer.
 183 十分なバッファ空間が与えられていない。
 184 もっと大きなバッファで再度実行すること。
 185 .\"O .SH "CONFORMING TO"
 186 .SH 準拠
 187 .\"O These functions are GNU extensions, done in a style resembling
 188 .\"O the POSIX version of functions like
 189 .\"O .BR getpwnam_r (3).
 190 これらの関数は GNU 拡張であり、POSIX 版の関数
 191 .BR getpwnam_r (3)
 192 の形式に似せてある。
 193 .\"O Other systems use prototype
 194 他のシステムでは以下のプロトタイプが使われている。
 195 .sp
 196 .nf
 197 .in +4n
 198 struct passwd *
 199 getpwent_r(struct passwd *pwd, char *buf, int buflen);
 200 .in
 201 .fi
 202 .sp
 203 .\"O or, better,
 204 より良いものでは、以下のようになっている。
 205 .sp
 206 .nf
 207 .in +4n
 208 int
 209 getpwent_r(struct passwd *pwd, char *buf, int buflen,
 210            FILE **pw_fp);
 211 .in
 212 .fi
 213 .\"O .SH NOTES
 214 .SH 注意
 215 .\"O The function
 216 .\"O .BR getpwent_r ()
 217 .\"O is not really reentrant since it shares the reading position
 218 .\"O in the stream with all other threads.
 219 関数
 220 .BR getpwent_r ()
 221 は本当のリエントラントではない。
 222 なぜなら、ストリームの読み込み位置を
 223 他の全てのスレッドと共有しているためである。
 224 .\"O .SH EXAMPLE
 225 .SH 例
 226 .nf
 227 #define _GNU_SOURCE
 228 #include <pwd.h>
 229 #include <stdio.h>
 230 #define BUFLEN 4096
 231
 232 int
 233 main(void)
 234 {
 235     struct passwd pw, *pwp;
 236     char buf[BUFLEN];
 237     int i;
 238
 239     setpwent();
 240     while (1) {
 241         i = getpwent_r(&pw, buf, BUFLEN, &pwp);
 242         if (i)
 243             break;
 244         printf("%s (%d)\etHOME %s\etSHELL %s\en", pwp\->pw_name,
 245                pwp\->pw_uid, pwp\->pw_dir, pwp\->pw_shell);
 246     }
 247     endpwent();
 248     exit(EXIT_SUCCESS);
 249 }
 250 .fi
 251 .\"O .\" perhaps add error checking - should use strerror_r
 252 .\" たぶんエラーチェックを追加して、strerror_r を使うべきだろう。
 253 .\" #include <errno.h>
 254 .\" #include <stdlib.h>
 255 .\"         if (i) {
 256 .\"               if (i == ENOENT)
 257 .\"                     break;
 258 .\"               printf("getpwent_r: %s", strerror(i));
 259 .\"               exit(EXIT_SUCCESS);
 260 .\"         }
 261 .\"O .SH "SEE ALSO"
 262 .SH 関連項目
 263 .BR fgetpwent (3),
 264 .BR getpw (3),
 265 .BR getpwent (3),
 266 .BR getpwnam (3),
 267 .BR getpwuid (3),
 268 .BR putpwent (3),
 269 .BR passwd (5)