original/man3/getgrnam.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" References consulted:
  26 .\"     Linux libc source code
  27 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  28 .\"     386BSD man pages
  29 .\"
  30 .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
  31 .\" Modified 2003-11-15 by aeb
  32 .\"
  33 .TH GETGRNAM 3 2013-07-22 "" "Linux Programmer's Manual"
  34 .SH NAME
  35 getgrnam, getgrnam_r, getgrgid, getgrgid_r \- get group file entry
  36 .SH SYNOPSIS
  37 .nf
  38 .B #include <sys/types.h>
  39 .B #include <grp.h>
  40 .sp
  41 .BI "struct group *getgrnam(const char *" name );
  42 .sp
  43 .BI "struct group *getgrgid(gid_t " gid );
  44 .sp
  45 .BI "int getgrnam_r(const char *" name ", struct group *" grp ,
  46 .br
  47 .BI "          char *" buf ", size_t " buflen ", struct group **" result );
  48 .sp
  49 .BI "int getgrgid_r(gid_t " gid ", struct group *" grp ,
  50 .br
  51 .BI "          char *" buf ", size_t " buflen ", struct group **" result );
  52 .fi
  53 .sp
  54 .in -4n
  55 Feature Test Macro Requirements for glibc (see
  56 .BR feature_test_macros (7)):
  57 .ad l
  58 .in
  59 .sp
  60 .BR getgrnam_r (),
  61 .BR getgrgid_r ():
  62 .RS 4
  63 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _BSD_SOURCE ||
  64 _SVID_SOURCE || _POSIX_SOURCE
  65 .RE
  66 .ad b
  67 .SH DESCRIPTION
  68 The
  69 .BR getgrnam ()
  70 function returns a pointer to a structure containing
  71 the broken-out fields of the record in the group database
  72 (e.g., the local group file
  73 .IR /etc/group ,
  74 NIS, and LDAP)
  75 that matches the group name
  76 .IR name .
  77 .PP
  78 The
  79 .BR getgrgid ()
  80 function returns a pointer to a structure containing
  81 the broken-out fields of the record in the group database
  82 that matches the group ID
  83 .IR gid .
  84 .PP
  85 The \fIgroup\fP structure is defined in \fI<grp.h>\fP as follows:
  86 .sp
  87 .in +4n
  88 .nf
  89 struct group {
  90     char   *gr_name;       /* group name */
  91     char   *gr_passwd;     /* group password */
  92     gid_t   gr_gid;        /* group ID */
  93     char  **gr_mem;        /* group members */
  94 };
  95 .fi
  96 .in
  97 .PP
  98 For more information about the fields of this structure, see
  99 .BR group (5).
 100 .PP
 101 The
 102 .BR getgrnam_r ()
 103 and
 104 .BR getgrgid_r ()
 105 functions obtain the same information as
 106 .BR getgrnam ()
 107 and
 108 .BR getgrgid (),
 109 but store the retrieved
 110 .I group
 111 structure
 112 in the space pointed to by
 113 .IR grp .
 114 The string fields pointed to by the members of the
 115 .I group
 116 structure are stored in the buffer
 117 .I buf
 118 of size
 119 .IR buflen .
 120 A pointer to the result (in case of success) or NULL (in case no entry
 121 was found or an error occurred) is stored in
 122 .IR *result .
 123 .PP
 124 The call
 125
 126     sysconf(_SC_GETGR_R_SIZE_MAX)
 127
 128 returns either \-1, without changing
 129 .IR errno ,
 130 or an initial suggested size for
 131 .IR buf .
 132 (If this size is too small,
 133 the call fails with
 134 .BR ERANGE ,
 135 in which case the caller can retry with a larger buffer.)
 136 .SH RETURN VALUE
 137 The
 138 .BR getgrnam ()
 139 and
 140 .BR getgrgid ()
 141 functions return a pointer to a
 142 .I group
 143 structure, or NULL if the matching entry
 144 is not found or an error occurs.
 145 If an error occurs,
 146 .I errno
 147 is set appropriately.
 148 If one wants to check
 149 .I errno
 150 after the call, it should be set to zero before the call.
 151 .LP
 152 The return value may point to a static area, and may be overwritten
 153 by subsequent calls to
 154 .BR getgrent (3),
 155 .BR getgrgid (),
 156 or
 157 .BR getgrnam ().
 158 (Do not pass the returned pointer to
 159 .BR free (3).)
 160 .LP
 161 On success,
 162 .BR getgrnam_r ()
 163 and
 164 .BR getgrgid_r ()
 165 return zero, and set
 166 .IR *result
 167 to
 168 .IR grp .
 169 If no matching group record was found,
 170 these functions return 0 and store NULL in
 171 .IR *result .
 172 In case of error, an error number is returned, and NULL is stored in
 173 .IR *result .
 174 .SH ERRORS
 175 .TP
 176 .BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ... "
 177 The given
 178 .I name
 179 or
 180 .I gid
 181 was not found.
 182 .TP
 183 .B EINTR
 184 A signal was caught.
 185 .TP
 186 .B EIO
 187 I/O error.
 188 .TP
 189 .B EMFILE
 190 The maximum number
 191 .RB ( OPEN_MAX )
 192 of files was open already in the calling process.
 193 .TP
 194 .B ENFILE
 195 The maximum number of files was open already in the system.
 196 .TP
 197 .B ENOMEM
 198 .\" not in POSIX
 199 Insufficient memory to allocate
 200 .I group
 201 structure.
 202 .\" to allocate the group structure, or to allocate buffers
 203 .TP
 204 .B ERANGE
 205 Insufficient buffer space supplied.
 206 .SH FILES
 207 .TP
 208 .I /etc/group
 209 local group database file
 210 .SH ATTRIBUTES
 211 .SS Multithreading (see pthreads(7))
 212 The
 213 .BR getgrnam ()
 214 and
 215 .BR getgrgid ()
 216 functions are not thread-safe.
 217 .LP
 218 The
 219 .BR getgrnam_r ()
 220 and
 221 .BR getgrgid_r ()
 222 functions are thread-safe.
 223 .SH CONFORMING TO
 224 SVr4, 4.3BSD, POSIX.1-2001.
 225 .SH NOTES
 226 The formulation given above under "RETURN VALUE" is from POSIX.1-2001.
 227 It does not call "not found" an error, hence does not specify what value
 228 .I errno
 229 might have in this situation.
 230 But that makes it impossible to recognize
 231 errors.
 232 One might argue that according to POSIX
 233 .I errno
 234 should be left unchanged if an entry is not found.
 235 Experiments on various
 236 UNIX-like systems shows that lots of different values occur in this
 237 situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others.
 238 .\" more precisely:
 239 .\" AIX 5.1 - gives ESRCH
 240 .\" OSF1 4.0g - gives EWOULDBLOCK
 241 .\" libc, glibc up to version 2.6, Irix 6.5 - give ENOENT
 242 .\" glibc since version 2.7 - give 0
 243 .\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM
 244 .\" SunOS 5.8 - gives EBADF
 245 .\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0
 246 .SH SEE ALSO
 247 .BR endgrent (3),
 248 .BR fgetgrent (3),
 249 .BR getgrent (3),
 250 .BR getpwnam (3),
 251 .BR setgrent (3),
 252 .BR group (5)
 253 .SH COLOPHON
 254 This page is part of release 3.67 of the Linux
 255 .I man-pages
 256 project.
 257 A description of the project,
 258 information about reporting bugs,
 259 and the latest version of this page,
 260 can be found at
 261 \%http://www.kernel.org/doc/man\-pages/.