diff options
Diffstat (limited to 'man3/getgrnam.3')
| -rw-r--r-- | man3/getgrnam.3 | 261 |
1 files changed, 261 insertions, 0 deletions
diff --git a/man3/getgrnam.3 b/man3/getgrnam.3 new file mode 100644 index 0000000..b79e15f --- /dev/null +++ b/man3/getgrnam.3 @@ -0,0 +1,261 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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 (faith@cs.unc.edu) +.\" Modified 2003-11-15 by aeb +.\" +.TH getgrnam 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +getgrnam, getgrnam_r, getgrgid, getgrgid_r \- get group file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <grp.h> +.PP +.BI "struct group *getgrnam(const char *" name ); +.BI "struct group *getgrgid(gid_t " gid ); +.PP +.BI "int getgrnam_r(const char *restrict " name \ +", struct group *restrict " grp , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct group **restrict " result ); +.BI "int getgrgid_r(gid_t " gid ", struct group *restrict " grp , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct group **restrict " result ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR getgrnam_r (), +.BR getgrgid_r (): +.nf + _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR 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 +.IR /etc/group , +NIS, and LDAP) +that matches the group name +.IR name . +.PP +The +.BR 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 +.IR gid . +.PP +The \fIgroup\fP structure is defined in \fI<grp.h>\fP as follows: +.PP +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL\-terminated array of pointers + to names of group members */ +}; +.EE +.in +.PP +For more information about the fields of this structure, see +.BR group (5). +.PP +The +.BR getgrnam_r () +and +.BR getgrgid_r () +functions obtain the same information as +.BR getgrnam () +and +.BR getgrgid (), +but store the retrieved +.I group +structure +in the space pointed to by +.IR grp . +The string fields pointed to by the members of the +.I group +structure are stored in the buffer +.I buf +of size +.IR 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 +.IR *result . +.PP +The call +.PP +.in +4n +.EX +sysconf(_SC_GETGR_R_SIZE_MAX) +.EE +.in +.PP +returns either \-1, without changing +.IR errno , +or an initial suggested size for +.IR buf . +(If this size is too small, +the call fails with +.BR ERANGE , +in which case the caller can retry with a larger buffer.) +.SH RETURN VALUE +The +.BR getgrnam () +and +.BR getgrgid () +functions return a pointer to a +.I group +structure, or NULL if the matching entry +is not found or an error occurs. +If an error occurs, +.I errno +is set to indicate the error. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.PP +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getgrent (3), +.BR getgrgid (), +or +.BR getgrnam (). +(Do not pass the returned pointer to +.BR free (3).) +.PP +On success, +.BR getgrnam_r () +and +.BR getgrgid_r () +return zero, and set +.I *result +to +.IR grp . +If no matching group record was found, +these functions return 0 and store NULL in +.IR *result . +In case of error, an error number is returned, and NULL is stored in +.IR *result . +.SH ERRORS +.TP +.BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ..." +The given +.I name +or +.I gid +was not found. +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I group +structure. +.\" to allocate the group structure, or to allocate buffers +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/group +local group database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getgrnam () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grnam locale +T} +T{ +.na +.nh +.BR getgrgid () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grgid locale +T} +T{ +.na +.nh +.BR getgrnam_r (), +.BR getgrgid_r () +T} Thread safety MT-Safe locale +.TE +.sp 1 +.SH VERSIONS +The formulation given above under "RETURN VALUE" is from POSIX.1. +.\" POSIX.1-2001, POSIX.1-2008 +It does not call "not found" an error, hence does not specify what value +.I errno +might have in this situation. +But that makes it impossible to recognize +errors. +One might argue that according to POSIX +.I 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. +.\" more precisely: +.\" AIX 5.1 - gives ESRCH +.\" OSF1 4.0g - gives EWOULDBLOCK +.\" libc, glibc up to glibc 2.6, Irix 6.5 - give ENOENT +.\" since glibc 2.7 - give 0 +.\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM +.\" SunOS 5.8 - gives EBADF +.\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0 +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR endgrent (3), +.BR fgetgrent (3), +.BR getgrent (3), +.BR getpwnam (3), +.BR setgrent (3), +.BR group (5) |