manual/LDP_man-pages/release/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 .SH 名前
  30 getgrent_r, fgetgrent_r \- グループファイルエントリをリエントラント (reentrant) に取り出す
  31 .SH 書式
  32 .nf
  33 .B #include <grp.h>
  34 .sp
  35 .BI "int getgrent_r(struct group *" gbuf ", char *" buf ,
  36 .br
  37 .BI "               size_t " buflen ", struct group **" gbufp );
  38 .sp
  39 .BI "int fgetgrent_r(FILE *" fp ", struct group *" gbuf ", char *" buf ,
  40 .br
  41 .BI "                size_t " buflen ", struct group **" gbufp );
  42 .fi
  43 .sp
  44 .in -4n
  45 glibc 向けの機能検査マクロの要件
  46 .RB ( feature_test_macros (7)
  47 参照):
  48 .in
  49 .sp
  50 .BR getgrent_r ():
  51 _GNU_SOURCE
  52 .\" FIXME . The FTM requirements seem inconsistent here.  File a glibc bug?
  53 .br
  54 .BR fgetgrent_r ():
  55 _SVID_SOURCE
  56 .SH 説明
  57 関数
  58 .BR getgrent_r ()
  59 と
  60 .BR fgetgrent_r ()
  61 は
  62 .BR getgrent (3)
  63 と
  64 .BR fgetgrent (3)
  65 のリエントラント版である。
  66 前者は、
  67 .BR setgrent (3)
  68 によって初期化されたストリームから、次のグループファイルのエントリを読み込む。
  69 後者は、ストリーム
  70 .I fp
  71 から次のグループファイルのエントリを読み込む。
  72 .PP
  73 \fIgroup\fP 構造体は
  74 .I <grp.h>
  75 において以下のように定義されている:
  76 .sp
  77 .in +4n
  78 .nf
  79 struct group {
  80     char    *gr_name;     /* グループ名 */
  81     char    *gr_passwd;   /* グループパスワード */
  82     gid_t    gr_gid;      /* グループ ID */
  83     char   **gr_mem;      /* グループメンバ */
  84 };
  85 .fi
  86 .in
  87 .PP
  88 この構造体のフィールドの詳細は
  89 .BR group (5)
  90 を参照のこと。
  91 .PP
  92 リエントラントでない関数は静的な格納領域へのポインタを返す。
  93 この静的な格納領域には、更にグループ名・パスワード・
  94 メンバへのポインタが含まれる。
  95 ここで説明されているリエントラントな関数は、
  96 呼び出し側から提供されるバッファにグループ名など全てを返す。
  97 最初の引き数として \fIstruct group\fP を保持できるバッファ
  98 .I gbuf
  99 がある。
 100 次にその他の文字列を保持できるサイズ
 101 .I buflen
 102 のバッファ
 103 .I buf
 104 がある。
 105 これらの関数の結果 (ストリームから読み込まれた \fIstruct group\fP) は、
 106 提供されたバッファ
 107 .IR *gbuf
 108 に格納され、この \fIstruct group\fP へのポインタは
 109 .IR *gbufp
 110 に返される。
 111 .SH 返り値
 112 成功した場合、これらの関数は 0 を返し、
 113 .RI * gbufp
 114 は \fIstruct group\fP へのポインタとなる。
 115 エラーの場合、これらの関数はエラー値を返し、
 116 .RI * gbufp
 117 は NULL になる。
 118 .SH エラー
 119 .TP
 120 .B ENOENT
 121 次のエントリがない。
 122 .TP
 123 .B ERANGE
 124 十分なバッファ空間が与えられていない。
 125 もっと大きなバッファで再度実行すること。
 126 .SH 準拠
 127 これらの関数は GNU 拡張であり、POSIX 版の関数
 128 .BR getpwnam_r (3)
 129 の形式に似せてある。
 130 他のシステムでは以下のプロトタイプが使われている。
 131 .sp
 132 .nf
 133 .in +4n
 134 struct group *getgrent_r(struct group *grp, char *buf,
 135                          int buflen);
 136 .in
 137 .fi
 138 .sp
 139 より良いものでは、以下のようになっている。
 140 .sp
 141 .nf
 142 .in +4n
 143 int getgrent_r(struct group *grp, char *buf, int buflen,
 144                FILE **gr_fp);
 145 .in
 146 .fi
 147 .SH 注意
 148 関数
 149 .BR getgrent_r ()
 150 は本当のリエントラントではない。
 151 なぜなら、ストリームの読み込み位置を
 152 他の全てのスレッドと共有しているためである。
 153 .SH 例
 154 .nf
 155 #define _GNU_SOURCE
 156 #include <grp.h>
 157 #include <stdio.h>
 158 #include <stdlib.h>
 159 #define BUFLEN 4096
 160
 161 int
 162 main(void)
 163 {
 164     struct group grp, *grpp;
 165     char buf[BUFLEN];
 166     int i;
 167
 168     setgrent();
 169     while (1) {
 170         i = getgrent_r(&grp, buf, BUFLEN, &grpp);
 171         if (i)
 172             break;
 173         printf("%s (%d):", grpp\->gr_name, grpp\->gr_gid);
 174         for (i = 0; ; i++) {
 175             if (grpp\->gr_mem[i] == NULL)
 176                 break;
 177             printf(" %s", grpp\->gr_mem[i]);
 178         }
 179         printf("\en");
 180     }
 181     endgrent();
 182     exit(EXIT_SUCCESS);
 183 }
 184 .fi
 185 .\" たぶんエラーチェックを追加して、strerror_r を使うべきだろう。
 186 .\" #include <errno.h>
 187 .\" #include <stdlib.h>
 188 .\"         if (i) {
 189 .\"               if (i == ENOENT)
 190 .\"                     break;
 191 .\"               printf("getgrent_r: %s", strerror(i));
 192 .\"               exit(EXIT_FAILURE);
 193 .\"         }
 194 .SH 関連項目
 195 .BR fgetgrent (3),
 196 .BR getgrent (3),
 197 .BR getgrgid (3),
 198 .BR getgrnam (3),
 199 .BR putgrent (3),
 200 .BR group (5)