diff options
Diffstat (limited to 'man-pages-posix-2013/man3p/getgrgid.3p')
| -rw-r--r-- | man-pages-posix-2013/man3p/getgrgid.3p | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man3p/getgrgid.3p b/man-pages-posix-2013/man3p/getgrgid.3p new file mode 100644 index 0000000..7d4b51e --- /dev/null +++ b/man-pages-posix-2013/man3p/getgrgid.3p @@ -0,0 +1,235 @@ +'\" et +.TH GETGRGID "3P" 2013 "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 +getgrgid, +getgrgid_r +\(em get group database entry for a group ID +.SH SYNOPSIS +.LP +.nf +#include <grp.h> +.P +struct group *getgrgid(gid_t \fIgid\fP); +int getgrgid_r(gid_t \fIgid\fP, struct group *\fIgrp\fP, char *\fIbuffer\fP, + size_t \fIbufsize\fP, struct group **\fIresult\fP); +.fi +.SH DESCRIPTION +The +\fIgetgrgid\fR() +function shall search the group database for an entry with a matching +.IR gid . +.P +The +\fIgetgrgid\fR() +function need not be thread-safe. +.P +The +\fIgetgrgid_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 gid . +Storage referenced by the 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 \(mi1 without changing +.IR errno +or an initial value suggested for the size of this buffer. +A null pointer shall be returned at the location pointed to by +.IR result +on error or if the requested entry is not found. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetgrgid\fR() +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 +\fIgetgrgid\fR() +function shall return a null pointer if either the requested entry was +not found, or an error occurred. 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(). +.P +If successful, the +\fIgetgrgid_r\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIgetgrgid\fR() +and +\fIgetgrgid_r\fR() +functions may fail if: +.TP +.BR EIO +An I/O error has occurred. +.TP +.BR EINTR +A signal was caught during +\fIgetgrgid\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 +\fIgetgrgid_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 \(mi1 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 +\fIgetgrid_r\fR(). +.sp +.RS 4 +.nf +\fB +long int initlen = sysconf(_SC_GETGR_R_SIZE_MAX); +size_t len; +if (initlen =\|= \(mi1) + /* 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 = getgrgid_r(42, &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 \fR +.P +.RE +.SS "Finding an Entry in the Group Database" +.P +The following example uses +\fIgetgrgid\fR() +to search the group database for a group ID that was previously stored +in a +.BR stat +structure, then prints out the group name if it is found. If the group +is not found, the program prints the numeric value of the group for the +entry. +.sp +.RS 4 +.nf +\fB +#include <sys/types.h> +#include <grp.h> +#include <stdio.h> +\&... +struct stat statbuf; +struct group *grp; +\&... +if ((grp = getgrgid(statbuf.st_gid)) != NULL) + printf(" %-8.8s", grp->gr_name); +else + printf(" %-8d", statbuf.st_gid); +\&... +.fi \fR +.P +.RE +.SH "APPLICATION USAGE" +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetgrgid\fR(). +If +.IR errno +is set on return, an error occurred. +.P +The +\fIgetgrgid_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 \(mi1 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 "\fIgetgrnam\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html . + +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 . |