8322 nl: misleading-indentation

[unleashed/tickless.git] / usr / src / man / man3c / getgrnam.3c

'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved.
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions 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.
.\"  This notice shall appear on any product containing this material.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH GETGRNAM 3C "Feb 25, 2017"
.SH NAME
getgrnam, getgrnam_r, getgrent, getgrent_r, getgrgid, getgrgid_r, setgrent,
endgrent, fgetgrent, fgetgrent_r \- group database entry functions
.SH SYNOPSIS
.LP
.nf
#include <grp.h>

\fBstruct group *\fR\fBgetgrnam\fR(\fBconst char *\fR\fIname\fR);
.fi

.LP
.nf
\fBstruct group *\fR\fBgetgrnam_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct group *\fR\fIgrp\fR,
     \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbufsize\fR);
.fi

.LP
.nf
\fBstruct group *\fR\fBgetgrent\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBstruct group *\fR\fBgetgrent_r\fR(\fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbufsize\fR);
.fi

.LP
.nf
\fBstruct group *\fR\fBgetgrgid\fR(\fBgid_t\fR \fIgid\fR);
.fi

.LP
.nf
\fBstruct group *\fR\fBgetgrgid_r\fR(\fBgid_t\fR \fIgid\fR, \fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR,
     \fBint\fR \fIbufsize\fR);
.fi

.LP
.nf
\fBvoid\fR \fBsetgrent\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBvoid\fR \fBendgrent\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBstruct group *\fR\fBfgetgrent\fR(\fBFILE *\fR\fIf\fR);
.fi

.LP
.nf
\fBstruct group *\fR\fBfgetgrent_r\fR(\fBFILE *\fR\fIf\fR, \fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR,
     \fBint\fR \fIbufsize\fR);
.fi

.SS "Standard conforming"
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR... ]

\fBint\fR \fBgetgrnam_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR,
     \fBsize_t\fR \fIbufsize\fR, \fBstruct group **\fR\fIresult\fR);
.fi

.LP
.nf
\fBint\fR \fBgetgrgid_r\fR(\fBgid_t\fR \fIgid\fR, \fBstruct group *\fR\fIgrp\fR, \fBchar *\fR\fIbuffer\fR,
     \fBsize_t\fR \fIbufsize\fR, \fBstruct group **\fR\fIresult\fR);
.fi

.SH DESCRIPTION
.LP
These functions are used to obtain entries describing user groups. Entries can
come from any of the sources for \fBgroup\fR specified in the
\fB/etc/nsswitch.conf\fR file (see \fBnsswitch.conf\fR(4)).
.sp
.LP
The \fBgetgrnam()\fR function searches the group database for an entry with the
group name specified by the character string parameter \fIname\fR.
.sp
.LP
The \fBgetgrgid()\fR function searches the group database for an entry with the
(numeric) group id specified by \fIgid\fR.
.sp
.LP
The \fBsetgrent()\fR, \fBgetgrent()\fR, and \fBendgrent()\fR functions are used
to enumerate group entries from the database.
.sp
.LP
The \fBsetgrent()\fR function effectively rewinds the group database to allow
repeated searches. It sets (or resets) the enumeration to the beginning of the
set of group entries.  This function should be called before the first call to
\fBgetgrent()\fR.
.sp
.LP
The \fBgetgrent()\fR function returns a pointer to a structure containing the
broken-out fields of an entry in the group database.  When first called,
\fBgetgrent()\fR returns a pointer to a \fBgroup\fR structure containing the
next group structure in the group database. Successive calls can be used to
search the entire database.
.sp
.LP
The \fBendgrent()\fR function can be called to close the group database and
deallocate resources when processing is complete. It is permissible, though
possibly less efficient, for the process to call more group functions after
calling \fBendgrent()\fR.
.sp
.LP
The \fBfgetgrent()\fR function, unlike the other functions above, does not use
\fBnsswitch.conf\fR. It reads and parses the next line from the stream \fIf\fR,
which is assumed to have the format of the \fBgroup\fR file (see
\fBgroup\fR(4)).
.SS "Reentrant Interfaces"
.LP
The  \fBgetgrnam()\fR, \fBgetgrgid()\fR, \fBgetgrent()\fR, and
\fBfgetgrent()\fR functions use thread-specific storage that is reused in each
call to one of these functions by the same thread, making them safe to use but
not recommended for multithreaded applications.
.sp
.LP
The parallel functions \fBgetgrnam_r()\fR, \fBgetgrgid_r()\fR,
\fBgetgrent_r()\fR, and \fBfgetgrent_r()\fR provide reentrant interfaces for
these operations.
.sp
.LP
Each reentrant interface performs the same operation as its non-reentrant
counterpart, named by removing the  \fB_r\fR suffix.  The reentrant interfaces,
however, use buffers supplied by the caller to store returned results instead
of using thread-specific data that can be overwritten by each call. They are
safe for use in both single-threaded and multithreaded applications.
.sp
.LP
Each reentrant interface takes the same arguments as its non-reentrant
counterpart, as well as the following additional parameters. The \fIgrp\fR
argument must be a pointer to a \fBstruct group\fR structure allocated by the
caller.  On successful completion, the function returns the group entry in this
structure. Storage referenced by the group structure is allocated from the
memory provided with the \fIbuffer\fR argument that is \fIbufsize\fR characters
in size.  The maximum size needed for  this buffer can be determined with the
\fB_SC_GETGR_R_SIZE_MAX\fR \fBsysconf\fR(3C) parameter. The standard-conforming
versions place a pointer to the modified \fIgrp\fR structure in the
\fIresult\fR parameter, instead of returning a pointer to this structure. A
null pointer is returned at the location pointed to by \fIresult\fR on error or
if the requested entry is not found.
.sp
.LP
For enumeration in multithreaded applications, the position within the
enumeration is a process-wide property shared by all threads. The
\fBsetgrent()\fR function can be used in a multithreaded application but resets
the enumeration position for all threads.  If multiple threads interleave calls
to \fBgetgrent_r()\fR, the threads will enumerate disjoint subsets of the group
database. Like their non-reentrant counterparts, \fBgetgrnam_r()\fR and
\fBgetgrgid_r()\fR leave the enumeration position in an indeterminate state.
.SS "group Structure"
.LP
Group entries are represented by the \fBstruct group\fR structure defined in
<\fBgrp.h\fR>:
.sp
.in +2
.nf
struct group {
    char *gr_name;          /* the name of the group */
    char *gr_passwd;        /* the encrypted group password */
    gid_t gr_gid;           /* the numerical group ID */
    char **gr_mem;          /* vector of pointers to member
                               names */
};
.fi
.in -2

.SH RETURN VALUES
.LP
The \fBgetgrnam()\fR, \fBgetgrnam_r()\fR, \fBgetgrgid()\fR, and
\fBgetgrgid_r()\fR functions each return a pointer to a \fBstruct group\fR if
they successfully locate the requested entry. They return a null pointer if
either the requested entry was not found or an error occurred. On error,
\fBerrno\fR is set to indicate the error. The standard-conforming functions
\fBgetgrnam_r()\fR and \fBgetgrgid_r()\fR return \fB0\fR upon success or an
error number in case of failure.
.sp
.LP
The  \fBgetgrent()\fR, \fBgetgrent_r()\fR, \fBfgetgrent()\fR, and
\fBfgetgrent_r()\fR functions each return a pointer to a \fBstruct group\fR if
they successfully enumerate an entry; otherwise they return a null pointer on
end-of-file or error. On error, \fBerrno\fR is set to indicate the error.
.sp
.LP
The \fBgetgrnam()\fR, \fBgetgrgid()\fR, \fBgetgrent()\fR, and \fBfgetgrent()\fR
functions use thread-specific data storage, so returned data must be copied
before a subsequent call to any of these functions if the data are to be saved.
.sp
.LP
When the pointer returned by the reentrant functions \fBgetgrnam_r()\fR,
\fBgetgrgid_r()\fR, \fBgetgrent_r()\fR, and \fBfgetgrent_r()\fR is non-null, it
is always equal to the \fIgrp\fR pointer that was supplied by the caller.
.sp
.LP
Applications wishing to check for error situations should set \fBerrno\fR to 0
before calling \fBgetgrnam()\fR, \fBgetgrnam_r()\fR, \fBgetgrent()\fR,
\fBgetgrent_r()\fR\fBgetgrgid()\fR, \fBgetgrgid_r()\fR, \fBfgetgrent()\fR, and
\fBfgetgrent_r()\fR. If these functions return a null pointer and \fBerrno\fR
is non-zero, an error occurred.
.SH ERRORS
.LP
The \fBgetgrent_r()\fR, \fBfgetgrent()\fR, and \fBfgetgrent_r()\fR functions
will fail if:
.sp
.ne 2
.na
\fB\fBEIO\fR\fR
.ad
.RS 10n
An I/O error has occurred.
.RE

.sp
.ne 2
.na
\fB\fBERANGE\fR\fR
.ad
.RS 10n
Insufficient storage was supplied by \fIbuffer\fR and \fIbufsize\fR to contain
the data to be referenced by the resulting \fBgroup\fR structure.
.RE

.sp
.LP
The \fBgetgrent_r()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEMFILE\fR\fR
.ad
.RS 10n
There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling
process.
.RE

.sp
.ne 2
.na
\fB\fBENFILE\fR\fR
.ad
.RS 10n
The maximum allowable number of files is currently open in the system.
.RE

.sp
.LP
The \fBgetgrnam()\fR, \fBgetgrnam_r()\fR, \fBgetgrgid()\fR, \fBgetgrgid_r()\fR,
and \fBgetgrent()\fR functions may fail if:
.sp
.ne 2
.na
\fB\fBEINTR\fR\fR
.ad
.RS 10n
A signal was caught during the operation.
.RE

.sp
.ne 2
.na
\fB\fBEIO\fR\fR
.ad
.RS 10n
An I/O error has occurred.
.RE

.sp
.ne 2
.na
\fB\fBEMFILE\fR\fR
.ad
.RS 10n
There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling
process.
.RE

.sp
.ne 2
.na
\fB\fBENFILE\fR\fR
.ad
.RS 10n
The maximum allowable number of files is currently open in the system.
.RE

.sp
.LP
The \fBgetgrnam_r()\fR and \fBgetgrgid_r()\fR functions may fail if:
.sp
.ne 2
.na
\fB\fBERANGE\fR\fR
.ad
.RS 10n
Insufficient storage was supplied by \fIbuffer\fR and \fIbufsize\fR to contain
the data to be referenced by the resulting \fBgroup\fR structure.
.RE

.SH ATTRIBUTES
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
Interface Stability     See below.
_
MT-Level        See \fBReentrant Interfaces\fR in \fBDESCRIPTION\fR.
.TE

.sp
.LP
The \fBendgrent()\fR, \fBgetgrent()\fR, \fBgetgrgid()\fR, \fBgetgrgid_r()\fR,
\fBgetgrnam()\fR, \fBgetgrnam_r()\fR, and \fBsetgrent()\fR functions are
Standard.
.SH SEE ALSO
.LP
\fBIntro\fR(3), \fBgetpwnam\fR(3C), \fBgroup\fR(4), \fBnsswitch.conf\fR(4),
\fBpasswd\fR(4), \fBattributes\fR(5), \fBstandards\fR(5)
.SH NOTES
.LP
When compiling multithreaded programs, see \fBIntro\fR(3).
.sp
.LP
Use of the enumeration interfaces \fBgetgrent()\fR and \fBgetgrent_r()\fR is
discouraged; enumeration is supported for the group file and \fBNIS\fR
but in general is not efficient and might not be supported for all
database sources.  The semantics of enumeration are discussed further in
\fBnsswitch.conf\fR(4).
.sp
.LP
Previous releases allowed the use of ``+'' and ``-'' entries in
\fB/etc/group\fR to selectively include and exclude entries from \fBNIS.\fR The
primary usage of these entries is superseded by the name service switch, so the
``+/-'' form might not be supported in future releases.
.sp
.LP
If required, the ``+/-'' functionality can still be obtained for \fBNIS\fR by
specifying \fBcompat\fR as the source for \fBgroup\fR.
.sp
.LP
If the ``+/-'' functionality is required in conjunction with \fBLDAP,\fR
specify both \fBcompat\fR as the source for \fBgroup\fR and \fBldap\fR as
the source for the pseudo-database \fBgroup_compat\fR. See \fBgroup\fR(4), and
\fBnsswitch.conf\fR(4) for details.
.sp
.LP
Solaris 2.4 and earlier releases provided definitions of the \fBgetgrnam_r()\fR
and \fBgetgrgid_r()\fR functions as specified in POSIX.1c Draft 6. The final
POSIX.1c standard changed the interface for these functions. Support for the
Draft 6 interface is provided for compatibility only and might not be supported
in future releases. New applications and libraries should use the
standard-conforming interface.
.sp
.LP
For POSIX.1c-conforming applications, the \fB_POSIX_PTHREAD_SEMANTICS\fR and
\fB_REENTRANT\fR flags are automatically turned on by defining the
\fB_POSIX_C_SOURCE\fR flag with a value \(>=199506L.