getgrgid.3p (6424B)
- '\" et
- .TH GETGRGID "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
- 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
- Applications wishing to check for error situations should set
- .IR errno
- to 0 before calling
- \fIgetgrgid\fR().
- If
- \fIgetgrgid\fR()
- returns a null pointer and
- .IR errno
- is set to non-zero, an error occurred.
- .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 \-1 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. 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
- 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 \-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
- \fIgetgrid_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 = 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
- .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
- #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
- .P
- .RE
- .SH "APPLICATION USAGE"
- 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 \-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 "\fIgetgrnam\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 .