manual/LDP_man-pages/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 2007-07-26 "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 .sp
 113 .\"O The nonreentrant functions return a pointer to static storage,
 114 .\"O where this static storage contains further pointers to group
 115 .\"O name, password and members.
 116 ¥ê¥¨¥ó¥È¥é¥ó¥È¤Ç¤Ê¤¤´Ø¿ô¤ÏÀÅÅª¤Ê³ÊÇ¼ÎÎ°è¤Ø¤Î¥Ý¥¤¥ó¥¿¤òÊÖ¤¹¡£
 117 ¤³¤ÎÀÅÅª¤Ê³ÊÇ¼ÎÎ°è¤Ë¤Ï¡¢¹¹¤Ë¥°¥ë¡¼¥×Ì¾¡¦¥Ñ¥¹¥ï¡¼¥É¡¦
 118 ¥á¥ó¥Ð¤Ø¤Î¥Ý¥¤¥ó¥¿¤¬´Þ¤Þ¤ì¤ë¡£
 119 .\"O The reentrant functions described here return all of that in
 120 .\"O caller-provided buffers.
 121 .\"O First of all there is the buffer
 122 .\"O .I gbuf
 123 .\"O that can hold a \fIstruct group\fP.
 124 .\"O And next the buffer
 125 .\"O .I buf
 126 .\"O of size
 127 .\"O .I buflen
 128 .\"O that can hold additional strings.
 129 ¤³¤³¤ÇÀâÌÀ¤µ¤ì¤Æ¤¤¤ë¥ê¥¨¥ó¥È¥é¥ó¥È¤Ê´Ø¿ô¤Ï¡¢
 130 ¸Æ¤Ó½Ð¤·Â¦¤«¤éÄó¶¡¤µ¤ì¤ë¥Ð¥Ã¥Õ¥¡¤Ë¥°¥ë¡¼¥×Ì¾¤Ê¤ÉÁ´¤Æ¤òÊÖ¤¹¡£
 131 ºÇ½é¤Î°ú¤¿ô¤È¤·¤Æ \fIstruct group\fP ¤òÊÝ»ý¤Ç¤¤ë¥Ð¥Ã¥Õ¥¡
 132 .I gbuf
 133 ¤¬¤¢¤ë¡£
 134 ¼¡¤Ë¤½¤ÎÂ¾¤ÎÊ¸»úÎó¤òÊÝ»ý¤Ç¤¤ë¥µ¥¤¥º
 135 .I buflen
 136 ¤Î¥Ð¥Ã¥Õ¥¡
 137 .I buf
 138 ¤¬¤¢¤ë¡£
 139 .\"O The result of these functions, the \fIstruct group\fP read from the stream,
 140 .\"O is stored in the provided buffer
 141 .\"O .IR *gbuf ,
 142 .\"O and a pointer to this \fIstruct group\fP is returned in
 143 .\"O .IR *gbufp .
 144 ¤³¤ì¤é¤Î´Ø¿ô¤Î·ë²Ì (¥¹¥È¥ê¡¼¥à¤«¤éÆÉ¤ß¹þ¤Þ¤ì¤¿ \fIstruct group\fP) ¤Ï¡¢
 145 Äó¶¡¤µ¤ì¤¿¥Ð¥Ã¥Õ¥¡
 146 .IR *gbuf
 147 ¤Ë³ÊÇ¼¤µ¤ì¡¢¤³¤Î \fIstruct group\fP ¤Ø¤Î¥Ý¥¤¥ó¥¿¤Ï
 148 .IR *gbufp
 149 ¤ËÊÖ¤µ¤ì¤ë¡£
 150 .\"O .SH "RETURN VALUE"
 151 .SH ÊÖ¤êÃÍ
 152 .\"O On success, these functions return 0 and
 153 .\"O .RI * gbufp
 154 .\"O is a pointer to the \fIstruct group\fP.
 155 À®¸ù¤·¤¿¾ì¹ç¡¢¤³¤ì¤é¤Î´Ø¿ô¤Ï 0 ¤òÊÖ¤·¡¢
 156 .RI * gbufp
 157 ¤Ï \fIstruct group\fP ¤Ø¤Î¥Ý¥¤¥ó¥¿¤È¤Ê¤ë¡£
 158 .\"O On error, these functions return an error value and
 159 .\"O .RI * gbufp
 160 .\"O is NULL.
 161 ¥¨¥é¡¼¤Î¾ì¹ç¡¢¤³¤ì¤é¤Î´Ø¿ô¤Ï¥¨¥é¡¼ÃÍ¤òÊÖ¤·¡¢
 162 .RI * gbufp
 163 ¤Ï NULL ¤Ë¤Ê¤ë¡£
 164 .\"O .SH ERRORS
 165 .SH ¥¨¥é¡¼
 166 .TP
 167 .B ENOENT
 168 .\"O No more entries.
 169 ¼¡¤Î¥¨¥ó¥È¥ê¤¬¤Ê¤¤¡£
 170 .TP
 171 .B ERANGE
 172 .\"O Insufficient buffer space supplied.
 173 .\"O Try again with larger buffer.
 174 ½½Ê¬¤Ê¥Ð¥Ã¥Õ¥¡¶õ´Ö¤¬Í¿¤¨¤é¤ì¤Æ¤¤¤Ê¤¤¡£
 175 ¤â¤Ã¤ÈÂç¤¤Ê¥Ð¥Ã¥Õ¥¡¤ÇºÆÅÙ¼Â¹Ô¤¹¤ë¤³¤È¡£
 176 .\"O .SH "CONFORMING TO"
 177 .SH ½àµò
 178 .\"O These functions are GNU extensions, done in a style resembling
 179 .\"O the POSIX version of functions like
 180 .\"O .BR getpwnam_r (3).
 181 ¤³¤ì¤é¤Î´Ø¿ô¤Ï GNU ³ÈÄ¥¤Ç¤¢¤ê¡¢POSIX ÈÇ¤Î´Ø¿ô
 182 .BR getpwnam_r (3)
 183 ¤Î·Á¼°¤Ë»÷¤»¤Æ¤¢¤ë¡£
 184 .\"O Other systems use prototype
 185 Â¾¤Î¥·¥¹¥Æ¥à¤Ç¤Ï°Ê²¼¤Î¥×¥í¥È¥¿¥¤¥×¤¬»È¤ï¤ì¤Æ¤¤¤ë¡£
 186 .sp
 187 .nf
 188 .in +4n
 189 struct group *getgrent_r(struct group *grp, char *buf,
 190                          int buflen);
 191 .in
 192 .fi
 193 .sp
 194 .\"O or, better,
 195 ¤è¤êÎÉ¤¤¤â¤Î¤Ç¤Ï¡¢°Ê²¼¤Î¤è¤¦¤Ë¤Ê¤Ã¤Æ¤¤¤ë¡£
 196 .sp
 197 .nf
 198 .in +4n
 199 int getgrent_r(struct group *grp, char *buf, int buflen,
 200                FILE **gr_fp);
 201 .in
 202 .fi
 203 .\"O .SH NOTES
 204 .SH Ãí°Õ
 205 .\"O The function
 206 .\"O .BR getgrent_r ()
 207 .\"O is not really reentrant since it shares the reading position
 208 .\"O in the stream with all other threads.
 209 ´Ø¿ô
 210 .BR getgrent_r ()
 211 ¤ÏËÜÅö¤Î¥ê¥¨¥ó¥È¥é¥ó¥È¤Ç¤Ï¤Ê¤¤¡£
 212 ¤Ê¤¼¤Ê¤é¡¢¥¹¥È¥ê¡¼¥à¤ÎÆÉ¤ß¹þ¤ß°ÌÃÖ¤ò
 213 Â¾¤ÎÁ´¤Æ¤Î¥¹¥ì¥Ã¥É¤È¶¦Í¤·¤Æ¤¤¤ë¤¿¤á¤Ç¤¢¤ë¡£
 214 .\"O .SH EXAMPLE
 215 .SH Îã
 216 .nf
 217 #define _GNU_SOURCE
 218 #include <grp.h>
 219 #include <stdio.h>
 220 #include <stdlib.h>
 221 #define BUFLEN 4096
 222
 223 int
 224 main(void)
 225 {
 226     struct group grp, *grpp;
 227     char buf[BUFLEN];
 228     int i;
 229
 230     setgrent();
 231     while (1) {
 232         i = getgrent_r(&grp, buf, BUFLEN, &grpp);
 233         if (i)
 234             break;
 235         printf("%s (%d):", grpp\->gr_name, grpp\->gr_gid);
 236         for (i = 0; ; i++) {
 237             if (grpp\->gr_mem[i] == NULL)
 238                 break;
 239             printf(" %s", grpp\->gr_mem[i]);
 240         }
 241         printf("\en");
 242     }
 243     endgrent();
 244     exit(EXIT_SUCCESS);
 245 }
 246 .fi
 247 .\"O .\" perhaps add error checking - should use strerror_r
 248 .\" ¤¿¤Ö¤ó¥¨¥é¡¼¥Á¥§¥Ã¥¯¤òÄÉ²Ã¤·¤Æ¡¢strerror_r ¤ò»È¤¦¤Ù¤¤À¤í¤¦¡£
 249 .\" #include <errno.h>
 250 .\" #include <stdlib.h>
 251 .\"         if (i) {
 252 .\"               if (i == ENOENT)
 253 .\"                     break;
 254 .\"               printf("getgrent_r: %s", strerror(i));
 255 .\"               exit(EXIT_FAILURE);
 256 .\"         }
 257 .\"O .SH "SEE ALSO"
 258 .SH ´ØÏ¢¹àÌÜ
 259 .BR fgetgrent (3),
 260 .BR getgrent (3),
 261 .BR getgrgid (3),
 262 .BR getgrnam (3),
 263 .BR putgrent (3),
 264 .BR group (5)