man3/getgrnam.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\"
  11 .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
  12 .\" Modified 2003-11-15 by aeb
  13 .\"
  14 .TH getgrnam 3 (date) "Linux man-pages (unreleased)"
  15 .SH NAME
  16 getgrnam, getgrnam_r, getgrgid, getgrgid_r \- get group file entry
  17 .SH LIBRARY
  18 Standard C library
  19 .RI ( libc ", " \-lc )
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <sys/types.h>
  23 .B #include <grp.h>
  24 .PP
  25 .BI "struct group *getgrnam(const char *" name );
  26 .BI "struct group *getgrgid(gid_t " gid );
  27 .PP
  28 .BI "int getgrnam_r(const char *restrict " name \
  29 ", struct group *restrict " grp ,
  30 .BI "               char " buf "[restrict ." buflen "], size_t " buflen ,
  31 .BI "               struct group **restrict " result );
  32 .BI "int getgrgid_r(gid_t " gid ", struct group *restrict " grp ,
  33 .BI "               char " buf "[restrict ." buflen "], size_t " buflen ,
  34 .BI "               struct group **restrict " result );
  35 .fi
  36 .PP
  37 .RS -4
  38 Feature Test Macro Requirements for glibc (see
  39 .BR feature_test_macros (7)):
  40 .RE
  41 .PP
  42 .BR getgrnam_r (),
  43 .BR getgrgid_r ():
  44 .nf
  45     _POSIX_C_SOURCE
  46         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  47 .fi
  48 .SH DESCRIPTION
  49 The
  50 .BR getgrnam ()
  51 function returns a pointer to a structure containing
  52 the broken-out fields of the record in the group database
  53 (e.g., the local group file
  54 .IR /etc/group ,
  55 NIS, and LDAP)
  56 that matches the group name
  57 .IR name .
  58 .PP
  59 The
  60 .BR getgrgid ()
  61 function returns a pointer to a structure containing
  62 the broken-out fields of the record in the group database
  63 that matches the group ID
  64 .IR gid .
  65 .PP
  66 The \fIgroup\fP structure is defined in \fI<grp.h>\fP as follows:
  67 .PP
  68 .in +4n
  69 .EX
  70 struct group {
  71     char   *gr_name;        /* group name */
  72     char   *gr_passwd;      /* group password */
  73     gid_t   gr_gid;         /* group ID */
  74     char  **gr_mem;         /* NULL\-terminated array of pointers
  75                                to names of group members */
  76 };
  77 .EE
  78 .in
  79 .PP
  80 For more information about the fields of this structure, see
  81 .BR group (5).
  82 .PP
  83 The
  84 .BR getgrnam_r ()
  85 and
  86 .BR getgrgid_r ()
  87 functions obtain the same information as
  88 .BR getgrnam ()
  89 and
  90 .BR getgrgid (),
  91 but store the retrieved
  92 .I group
  93 structure
  94 in the space pointed to by
  95 .IR grp .
  96 The string fields pointed to by the members of the
  97 .I group
  98 structure are stored in the buffer
  99 .I buf
 100 of size
 101 .IR buflen .
 102 A pointer to the result (in case of success) or NULL (in case no entry
 103 was found or an error occurred) is stored in
 104 .IR *result .
 105 .PP
 106 The call
 107 .PP
 108 .in +4n
 109 .EX
 110 sysconf(_SC_GETGR_R_SIZE_MAX)
 111 .EE
 112 .in
 113 .PP
 114 returns either \-1, without changing
 115 .IR errno ,
 116 or an initial suggested size for
 117 .IR buf .
 118 (If this size is too small,
 119 the call fails with
 120 .BR ERANGE ,
 121 in which case the caller can retry with a larger buffer.)
 122 .SH RETURN VALUE
 123 The
 124 .BR getgrnam ()
 125 and
 126 .BR getgrgid ()
 127 functions return a pointer to a
 128 .I group
 129 structure, or NULL if the matching entry
 130 is not found or an error occurs.
 131 If an error occurs,
 132 .I errno
 133 is set to indicate the error.
 134 If one wants to check
 135 .I errno
 136 after the call, it should be set to zero before the call.
 137 .PP
 138 The return value may point to a static area, and may be overwritten
 139 by subsequent calls to
 140 .BR getgrent (3),
 141 .BR getgrgid (),
 142 or
 143 .BR getgrnam ().
 144 (Do not pass the returned pointer to
 145 .BR free (3).)
 146 .PP
 147 On success,
 148 .BR getgrnam_r ()
 149 and
 150 .BR getgrgid_r ()
 151 return zero, and set
 152 .I *result
 153 to
 154 .IR grp .
 155 If no matching group record was found,
 156 these functions return 0 and store NULL in
 157 .IR *result .
 158 In case of error, an error number is returned, and NULL is stored in
 159 .IR *result .
 160 .SH ERRORS
 161 .TP
 162 .BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ..."
 163 The given
 164 .I name
 165 or
 166 .I gid
 167 was not found.
 168 .TP
 169 .B EINTR
 170 A signal was caught; see
 171 .BR signal (7).
 172 .TP
 173 .B EIO
 174 I/O error.
 175 .TP
 176 .B EMFILE
 177 The per-process limit on the number of open file descriptors has been reached.
 178 .TP
 179 .B ENFILE
 180 The system-wide limit on the total number of open files has been reached.
 181 .TP
 182 .B ENOMEM
 183 .\" not in POSIX
 184 Insufficient memory to allocate
 185 .I group
 186 structure.
 187 .\" to allocate the group structure, or to allocate buffers
 188 .TP
 189 .B ERANGE
 190 Insufficient buffer space supplied.
 191 .SH FILES
 192 .TP
 193 .I /etc/group
 194 local group database file
 195 .SH ATTRIBUTES
 196 For an explanation of the terms used in this section, see
 197 .BR attributes (7).
 198 .ad l
 199 .nh
 200 .TS
 201 allbox;
 202 lb lb lbx
 203 l l l.
 204 Interface       Attribute       Value
 205 T{
 206 .BR getgrnam ()
 207 T}      Thread safety   T{
 208 MT-Unsafe race:grnam locale
 209 T}
 210 T{
 211 .BR getgrgid ()
 212 T}      Thread safety   T{
 213 MT-Unsafe race:grgid locale
 214 T}
 215 T{
 216 .BR getgrnam_r (),
 217 .BR getgrgid_r ()
 218 T}      Thread safety   MT-Safe locale
 219 .TE
 220 .hy
 221 .ad
 222 .sp 1
 223 .SH VERSIONS
 224 The formulation given above under "RETURN VALUE" is from POSIX.1.
 225 .\" POSIX.1-2001, POSIX.1-2008
 226 It does not call "not found" an error, hence does not specify what value
 227 .I errno
 228 might have in this situation.
 229 But that makes it impossible to recognize
 230 errors.
 231 One might argue that according to POSIX
 232 .I errno
 233 should be left unchanged if an entry is not found.
 234 Experiments on various
 235 UNIX-like systems show that lots of different values occur in this
 236 situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others.
 237 .\" more precisely:
 238 .\" AIX 5.1 - gives ESRCH
 239 .\" OSF1 4.0g - gives EWOULDBLOCK
 240 .\" libc, glibc up to glibc 2.6, Irix 6.5 - give ENOENT
 241 .\" since glibc 2.7 - give 0
 242 .\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM
 243 .\" SunOS 5.8 - gives EBADF
 244 .\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0
 245 .SH STANDARDS
 246 POSIX.1-2008.
 247 .SH HISTORY
 248 POSIX.1-2001, SVr4, 4.3BSD.
 249 .SH SEE ALSO
 250 .BR endgrent (3),
 251 .BR fgetgrent (3),
 252 .BR getgrent (3),
 253 .BR getpwnam (3),
 254 .BR setgrent (3),
 255 .BR group (5)