1GETGRNAM(P) POSIX Programmer's Manual GETGRNAM(P)
2
6 getgrnam, getgrnam_r - search group database for a name
7
9 #include <grp.h>
10 struct group *getgrnam(const char *name);
12 int getgrnam_r(const char *name, struct group *grp, char *buffer,
15 size_t bufsize, struct group **result);
16
19 The getgrnam() function shall search the group database for an entry
20 with a matching name.
21 The getgrnam() function need not be reentrant. A function that is not
23 required to be reentrant is not required to be thread-safe.
24 The getgrnam_r() function shall update the group structure pointed to
26 by grp and store a pointer to that structure at the location pointed to
27 by result. The structure shall contain an entry from the group database
28 with a matching gid or name. Storage referenced by the group structure
29 is allocated from the memory provided with the buffer parameter, which
30 is bufsize bytes in size. The maximum size needed for this buffer can
31 be determined with the {_SC_GETGR_R_SIZE_MAX} sysconf() parameter. A
32 NULL pointer is returned at the location pointed to by result on error
33 or if the requested entry is not found.
34
36 The getgrnam() function shall return a pointer to a struct group with
37 the structure defined in <grp.h> with a matching entry if one is found.
38 The getgrnam() function shall return a null pointer if either the
39 requested entry was not found, or an error occurred. On error, errno
40 shall be set to indicate the error.
41 The return value may point to a static area which is overwritten by a
43 subsequent call to getgrent(), getgrgid(), or getgrnam().
44 If successful, the getgrnam_r() function shall return zero; otherwise,
46 an error number shall be returned to indicate the error.
47
49 The getgrnam() and getgrnam_r() functions may fail if:
50 EIO An I/O error has occurred.
52 EINTR A signal was caught during getgrnam().
54 EMFILE {OPEN_MAX} file descriptors are currently open in the calling
56 process.
57 ENFILE The maximum allowable number of files is currently open in the
59 system.
60 The getgrnam_r() function may fail if:
63 ERANGE Insufficient storage was supplied via buffer and bufsize to con‐
65 tain the data to be referenced by the resulting group structure.
66 The following sections are informative.
69
71 None.
72
74 Applications wishing to check for error situations should set errno to
75 0 before calling getgrnam(). If errno is set on return, an error
76 occurred.
77 The getgrnam_r() function is thread-safe and shall return values in a
79 user-supplied buffer instead of possibly using a static data area that
80 may be overwritten by each call.
81
83 None.
84
86 None.
87
89 endgrent() , getgrgid() , the Base Definitions volume of
90 IEEE Std 1003.1-2001, <grp.h>, <limits.h>, <sys/types.h>
91
93 Portions of this text are reprinted and reproduced in electronic form
94 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
95 -- Portable Operating System Interface (POSIX), The Open Group Base
96 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
97 Electrical and Electronics Engineers, Inc and The Open Group. In the
98 event of any discrepancy between this version and the original IEEE and
99 The Open Group Standard, the original IEEE and The Open Group Standard
100 is the referee document. The original Standard can be obtained online
101 at http://www.opengroup.org/unix/online.html .
102IEEE/The Open Group 2003 GETGRNAM(P)