diff options
Diffstat (limited to 'upstream/archlinux/man3p/getgrnam.3p')
| -rw-r--r-- | upstream/archlinux/man3p/getgrnam.3p | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/getgrnam.3p b/upstream/archlinux/man3p/getgrnam.3p new file mode 100644 index 00000000..7d191f97 --- /dev/null +++ b/upstream/archlinux/man3p/getgrnam.3p @@ -0,0 +1,219 @@ +'\" et +.TH GETGRNAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getgrnam, +getgrnam_r +\(em search group database for a name +.SH SYNOPSIS +.LP +.nf +#include <grp.h> +.P +struct group *getgrnam(const char *\fIname\fP); +int getgrnam_r(const char *\fIname\fP, struct group *\fIgrp\fP, char *\fIbuffer\fP, + size_t \fIbufsize\fP, struct group **\fIresult\fP); +.fi +.SH DESCRIPTION +The +\fIgetgrnam\fR() +function shall search the group database for an entry with a matching +.IR name . +.P +The +\fIgetgrnam\fR() +function need not be thread-safe. +.P +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetgrnam\fR(). +If +\fIgetgrnam\fR() +returns a null pointer and +.IR errno +is set to non-zero, an error occurred. +.P +The +\fIgetgrnam_r\fR() +function shall update the +.BR group +structure pointed to by +.IR grp +and store a pointer to that structure at the location pointed to by +.IR result . +The structure shall contain an entry from the group database with a +matching +.IR name . +Storage referenced by the +.BR group +structure is allocated from the memory provided with the +.IR buffer +parameter, which is +.IR bufsize +bytes in size. A call to +.IR sysconf (_SC_GETGR_R_SIZE_MAX) +returns either \-1 without changing +.IR errno +or an initial value suggested for the size of this buffer. +A null pointer is returned at the location pointed to by +.IR result +on error or if the requested entry is not found. +.SH "RETURN VALUE" +The +\fIgetgrnam\fR() +function shall return a pointer to a +.BR "struct group" +with the structure defined in +.IR <grp.h> +with a matching entry if one is found. The +\fIgetgrnam\fR() +function shall return a null pointer if either the requested entry +was not found, or an error occurred. If the requested entry was +not found, +.IR errno +shall not be changed. On error, +.IR errno +shall be set to indicate the error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetgrent\fR(), +\fIgetgrgid\fR(), +or +\fIgetgrnam\fR(). +The returned pointer, and pointers within the structure, might +also be invalidated if the calling thread is terminated. +.P +The +\fIgetgrnam_r\fR() +function shall return zero on success or if the requested entry was not +found and no error has occurred. If any error has occurred, an error +number shall be returned to indicate the error. +.SH ERRORS +The +\fIgetgrnam\fR() +and +\fIgetgrnam_r\fR() +functions may fail if: +.TP +.BR EIO +An I/O error has occurred. +.TP +.BR EINTR +A signal was caught during +\fIgetgrnam\fR(). +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the +system. +.P +The +\fIgetgrnam_r\fR() +function may fail if: +.TP +.BR ERANGE +Insufficient storage was supplied via +.IR buffer +and +.IR bufsize +to contain the data to be referenced by the resulting +.BR group +structure. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Note that +.IR sysconf (_SC_GETGR_R_SIZE_MAX) +may return \-1 if there is no hard limit on the size of the buffer +needed to store all the groups returned. This example shows how an +application can allocate a buffer of sufficient size to work with +\fIgetgrnam_r\fR(). +.sp +.RS 4 +.nf + +long int initlen = sysconf(_SC_GETGR_R_SIZE_MAX); +size_t len; +if (initlen =\|= -1) + /* Default initial length. */ + len = 1024; +else + len = (size_t) initlen; +struct group result; +struct group *resultp; +char *buffer = malloc(len); +if (buffer =\|= NULL) + ...handle error... +int e; +while ((e = getgrnam_r("somegroup", &result, buffer, len, &resultp)) + =\|= ERANGE) + { + size_t newlen = 2 * len; + if (newlen < len) + ...handle error... + len = newlen; + char *newbuffer = realloc(buffer, len); + if (newbuffer =\|= NULL) + ...handle error... + buffer = newbuffer; + } +if (e != 0) + ...handle error... +free (buffer); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIgetgrnam_r\fR() +function is thread-safe and shall return values in a user-supplied +buffer instead of possibly using a static data area that may be +overwritten by each call. +.P +Portable applications should take into account that it is usual +for an implementation to return \-1 from +\fIsysconf\fR() +indicating that there is no maximum for _SC_GETGR_R_SIZE_MAX. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendgrent\fR\^(\|)", +.IR "\fIgetgrgid\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<grp.h>\fP", +.IR "\fB<sys_types.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |