man3/getgrnam.3

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