Name
getgrnam, getgrnam_r, getgrgid, getgrgid_r — get group file entry
Synopsis
#include <sys/types.h> #include <grp.h>
struct group
*getgrnam( |
const char *name); |
struct group
*getgrgid( |
gid_t gid); |
int
getgrnam_r( |
const char *restrict name, |
| struct group *restrict grp, | |
| char *restrict buf, | |
| size_t buflen, | |
struct group **restrict result); |
int
getgrgid_r( |
gid_t gid, |
| struct group *restrict grp, | |
| char *restrict buf, | |
| size_t buflen, | |
struct group **restrict result); |
![[Note]](../stylesheet/note.png) |
Note | |||
|---|---|---|---|---|
|
DESCRIPTION
The getgrnam() function
returns a pointer to a structure containing the broken-out
fields of the record in the group database (e.g., the local
group file /etc/group, NIS, and
LDAP) that matches the group name name.
The getgrgid() function
returns a pointer to a structure containing the broken-out
fields of the record in the group database that matches the
group ID gid.
The group structure is
defined in <grp.h> as
follows:
struct group { char * gr_name;char * gr_passwd;gid_t gr_gid;char ** gr_mem;
to names of group members */};
For more information about the fields of this structure, see group(5).
The getgrnam_r() and
getgrgid_r() functions obtain
the same information as getgrnam() and getgrgid(), but store the retrieved
group structure in the space
pointed to by grp.
The string fields pointed to by the members of the
group structure are stored in
the buffer buf of
size buflen. A
pointer to the result (in case of success) or NULL (in case
no entry was found or an error occurred) is stored in
*result.
The call
sysconf(_SC_GETGR_R_SIZE_MAX)
returns either −1, without changing errno, or an initial suggested size for
buf. (If this size is
too small, the call fails with ERANGE, in which case the caller can retry
with a larger buffer.)
RETURN VALUE
The getgrnam() and
getgrgid() functions return a
pointer to a group structure,
or NULL if the matching entry is not found or an error
occurs. If an error occurs, errno is set to indicate the error. If one
wants to check errno after the
call, it should be set to zero before the call.
The return value may point to a static area, and may be
overwritten by subsequent calls to getgrent(3), getgrgid(), or getgrnam(). (Do not pass the returned
pointer to free(3).)
On success, getgrnam_r() and
getgrgid_r() return zero, and
set *result to
grp. If no matching
group record was found, these functions return 0 and store
NULL in *result. In
case of error, an error number is returned, and NULL is
stored in *result.
ERRORS
0or ENOENT or ESRCH or EBADF or EPERM or ...-
The given
nameorgidwas not found. - EINTR
-
A signal was caught; see signal(7).
- EIO
-
I/O error.
- EMFILE
-
The per-process limit on the number of open file descriptors has been reached.
- ENFILE
-
The system-wide limit on the total number of open files has been reached.
- ENOMEM
-
Insufficient memory to allocate group structure.
- ERANGE
-
Insufficient buffer space supplied.
ATTRIBUTES
For an explanation of the terms used in this section, see attributes(7).
| Interface | Attribute | Value |
getgrnam() |
Thread safety | MT-Unsafe race:grnam locale |
getgrgid() |
Thread safety | MT-Unsafe race:grgid locale |
getgrnam_r(), getgrgid_r() |
Thread safety | MT-Safe locale |
NOTES
The formulation given above under "RETURN VALUE" is from
POSIX.1. It does not call "not found" an error, hence does
not specify what value errno
might have in this situation. But that makes it impossible to
recognize errors. One might argue that according to POSIX
errno should be left unchanged
if an entry is not found. Experiments on various UNIX-like
systems show that lots of different values occur in this
situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and
probably others.
COLOPHON
This page is part of release 5.11 of the Linux man-pages project. A
description of the project, information about reporting bugs,
and the latest version of this page, can be found at
https://www.kernel.org/doc/man−pages/.
|
Copyright 1993 David Metcalfe (davidprism.demon.co.uk) %%%LICENSE_START(VERBATIM) Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Since the Linux kernel and libraries are constantly changing, this manual page may be incorrect or out-of-date. The author(s) assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. The author(s) may not have taken the same level of care in the production of this manual, which is licensed free of charge, as they might when working professionally. Formatted or processed versions of this manual, if unaccompanied by the source, must acknowledge the copyright and authors of this work. %%%LICENSE_END References consulted: Linux libc source code Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) 386BSD man pages Modified 1993-07-24 by Rik Faith (faithcs.unc.edu) Modified 2003-11-15 by aeb |