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)