draft/man3/getgrent_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 Thu Jul 29 02:26:07 JST 2004
  26 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>
  27 .\"
  28 .TH GETGRENT_R 3 2010-10-21 "GNU" "Linux Programmer's Manual"
  29 .\"O .SH NAME
  30 .SH 名前
  31 .\"O getgrent_r, fgetgrent_r \- get group file entry reentrantly
  32 getgrent_r, fgetgrent_r \- グループファイルエントリをリエントラント (reentrant) に取り出す
  33 .\"O .SH SYNOPSIS
  34 .SH 書式
  35 .nf
  36 .B #include <grp.h>
  37 .sp
  38 .BI "int getgrent_r(struct group *" gbuf ", char *" buf ,
  39 .br
  40 .BI "               size_t " buflen ", struct group **" gbufp );
  41 .sp
  42 .BI "int fgetgrent_r(FILE *" fp ", struct group *" gbuf ", char *" buf ,
  43 .br
  44 .BI "                size_t " buflen ", struct group **" gbufp );
  45 .fi
  46 .sp
  47 .in -4n
  48 .\"O Feature Test Macro Requirements for glibc (see
  49 .\"O .BR feature_test_macros (7)):
  50 glibc 向けの機能検査マクロの要件
  51 .RB ( feature_test_macros (7)
  52 参照):
  53 .in
  54 .sp
  55 .BR getgrent_r ():
  56 _GNU_SOURCE
  57 .\" FIXME . The FTM requirements seem inconsistent here.  File a glibc bug?
  58 .br
  59 .BR fgetgrent_r ():
  60 _SVID_SOURCE
  61 .\"O .SH DESCRIPTION
  62 .SH 説明
  63 .\"O The functions
  64 .\"O .BR getgrent_r ()
  65 .\"O and
  66 .\"O .BR fgetgrent_r ()
  67 .\"O are the reentrant versions of
  68 .\"O .BR getgrent (3)
  69 .\"O and
  70 .\"O .BR fgetgrent (3).
  71 関数
  72 .BR getgrent_r ()
  73 と
  74 .BR fgetgrent_r ()
  75 は
  76 .BR getgrent (3)
  77 と
  78 .BR fgetgrent (3)
  79 のリエントラント版である。
  80 .\"O The former reads the next group entry from the stream initialized by
  81 .\"O .BR setgrent (3).
  82 前者は、
  83 .BR setgrent (3)
  84 によって初期化されたストリームから、次のグループファイルのエントリを読み込む。
  85 .\"O The latter reads the next group entry from the stream
  86 .\"O .IR fp .
  87 後者は、ストリーム
  88 .I fp
  89 から次のグループファイルのエントリを読み込む。
  90 .PP
  91 .\"O The \fIgroup\fP structure is defined in
  92 .\"O .I <grp.h>
  93 .\"O as follows:
  94 \fIgroup\fP 構造体は
  95 .I <grp.h>
  96 において以下のように定義されている:
  97 .sp
  98 .in +4n
  99 .nf
 100 struct group {
 101 .\"O     char    *gr_name;     /* group name */
 102 .\"O     char    *gr_passwd;   /* group password */
 103 .\"O     gid_t    gr_gid;      /* group ID */
 104 .\"O     char   **gr_mem;      /* group members */
 105     char    *gr_name;     /* グループ名 */
 106     char    *gr_passwd;   /* グループパスワード */
 107     gid_t    gr_gid;      /* グループ ID */
 108     char   **gr_mem;      /* グループメンバ */
 109 };
 110 .fi
 111 .in
 112 .PP
 113 .\"O For more information about the fields of this structure, see
 114 .\"O .BR group (5).
 115 この構造体のフィールドの詳細は
 116 .BR group (5)
 117 を参照のこと。
 118 .PP
 119 .\"O The nonreentrant functions return a pointer to static storage,
 120 .\"O where this static storage contains further pointers to group
 121 .\"O name, password and members.
 122 リエントラントでない関数は静的な格納領域へのポインタを返す。
 123 この静的な格納領域には、更にグループ名・パスワード・
 124 メンバへのポインタが含まれる。
 125 .\"O The reentrant functions described here return all of that in
 126 .\"O caller-provided buffers.
 127 .\"O First of all there is the buffer
 128 .\"O .I gbuf
 129 .\"O that can hold a \fIstruct group\fP.
 130 .\"O And next the buffer
 131 .\"O .I buf
 132 .\"O of size
 133 .\"O .I buflen
 134 .\"O that can hold additional strings.
 135 ここで説明されているリエントラントな関数は、
 136 呼び出し側から提供されるバッファにグループ名など全てを返す。
 137 最初の引き数として \fIstruct group\fP を保持できるバッファ
 138 .I gbuf
 139 がある。
 140 次にその他の文字列を保持できるサイズ
 141 .I buflen
 142 のバッファ
 143 .I buf
 144 がある。
 145 .\"O The result of these functions, the \fIstruct group\fP read from the stream,
 146 .\"O is stored in the provided buffer
 147 .\"O .IR *gbuf ,
 148 .\"O and a pointer to this \fIstruct group\fP is returned in
 149 .\"O .IR *gbufp .
 150 これらの関数の結果 (ストリームから読み込まれた \fIstruct group\fP) は、
 151 提供されたバッファ
 152 .IR *gbuf
 153 に格納され、この \fIstruct group\fP へのポインタは
 154 .IR *gbufp
 155 に返される。
 156 .\"O .SH "RETURN VALUE"
 157 .SH 返り値
 158 .\"O On success, these functions return 0 and
 159 .\"O .RI * gbufp
 160 .\"O is a pointer to the \fIstruct group\fP.
 161 成功した場合、これらの関数は 0 を返し、
 162 .RI * gbufp
 163 は \fIstruct group\fP へのポインタとなる。
 164 .\"O On error, these functions return an error value and
 165 .\"O .RI * gbufp
 166 .\"O is NULL.
 167 エラーの場合、これらの関数はエラー値を返し、
 168 .RI * gbufp
 169 は NULL になる。
 170 .\"O .SH ERRORS
 171 .SH エラー
 172 .TP
 173 .B ENOENT
 174 .\"O No more entries.
 175 次のエントリがない。
 176 .TP
 177 .B ERANGE
 178 .\"O Insufficient buffer space supplied.
 179 .\"O Try again with larger buffer.
 180 十分なバッファ空間が与えられていない。
 181 もっと大きなバッファで再度実行すること。
 182 .\"O .SH "CONFORMING TO"
 183 .SH 準拠
 184 .\"O These functions are GNU extensions, done in a style resembling
 185 .\"O the POSIX version of functions like
 186 .\"O .BR getpwnam_r (3).
 187 これらの関数は GNU 拡張であり、POSIX 版の関数
 188 .BR getpwnam_r (3)
 189 の形式に似せてある。
 190 .\"O Other systems use prototype
 191 他のシステムでは以下のプロトタイプが使われている。
 192 .sp
 193 .nf
 194 .in +4n
 195 struct group *getgrent_r(struct group *grp, char *buf,
 196                          int buflen);
 197 .in
 198 .fi
 199 .sp
 200 .\"O or, better,
 201 より良いものでは、以下のようになっている。
 202 .sp
 203 .nf
 204 .in +4n
 205 int getgrent_r(struct group *grp, char *buf, int buflen,
 206                FILE **gr_fp);
 207 .in
 208 .fi
 209 .\"O .SH NOTES
 210 .SH 注意
 211 .\"O The function
 212 .\"O .BR getgrent_r ()
 213 .\"O is not really reentrant since it shares the reading position
 214 .\"O in the stream with all other threads.
 215 関数
 216 .BR getgrent_r ()
 217 は本当のリエントラントではない。
 218 なぜなら、ストリームの読み込み位置を
 219 他の全てのスレッドと共有しているためである。
 220 .\"O .SH EXAMPLE
 221 .SH 例
 222 .nf
 223 #define _GNU_SOURCE
 224 #include <grp.h>
 225 #include <stdio.h>
 226 #include <stdlib.h>
 227 #define BUFLEN 4096
 228
 229 int
 230 main(void)
 231 {
 232     struct group grp, *grpp;
 233     char buf[BUFLEN];
 234     int i;
 235
 236     setgrent();
 237     while (1) {
 238         i = getgrent_r(&grp, buf, BUFLEN, &grpp);
 239         if (i)
 240             break;
 241         printf("%s (%d):", grpp\->gr_name, grpp\->gr_gid);
 242         for (i = 0; ; i++) {
 243             if (grpp\->gr_mem[i] == NULL)
 244                 break;
 245             printf(" %s", grpp\->gr_mem[i]);
 246         }
 247         printf("\en");
 248     }
 249     endgrent();
 250     exit(EXIT_SUCCESS);
 251 }
 252 .fi
 253 .\"O .\" perhaps add error checking - should use strerror_r
 254 .\" たぶんエラーチェックを追加して、strerror_r を使うべきだろう。
 255 .\" #include <errno.h>
 256 .\" #include <stdlib.h>
 257 .\"         if (i) {
 258 .\"               if (i == ENOENT)
 259 .\"                     break;
 260 .\"               printf("getgrent_r: %s", strerror(i));
 261 .\"               exit(EXIT_FAILURE);
 262 .\"         }
 263 .\"O .SH "SEE ALSO"
 264 .SH 関連項目
 265 .BR fgetgrent (3),
 266 .BR getgrent (3),
 267 .BR getgrgid (3),
 268 .BR getgrnam (3),
 269 .BR putgrent (3),
 270 .BR group (5)