'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
.\" 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 getprojent 3PROJECT "5 Apr 2004" "SunOS 5.11" "Project Database Access Library Functions"
.SH NAME
getprojent, getprojbyname, getprojbyid, getdefaultproj, inproj,
getprojidbyname, setprojent, endprojent, fgetprojent \- project database entry
operations
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... \(milproject [ \fIlibrary\fR... ]
#include <project.h>

\fBstruct project *\fR\fBgetprojent\fR(\fBstruct project *\fR\fIproj\fR, \fBvoid *\fR\fIbuffer\fR,
     \fBsize_t\fR \fIbufsize\fR);
.fi

.LP
.nf
\fBstruct project *\fR\fBgetprojbyname\fR(\fBconst char *\fR\fIname\fR,
     \fBstruct project *\fR\fIproj\fR, \fBvoid *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR);
.fi

.LP
.nf
\fBstruct project *\fR\fBgetprojbyid\fR(\fBprojid_t\fR \fIprojid\fR,
     \fBstruct project *\fR\fIproj\fR, \fBvoid *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR);
.fi

.LP
.nf
\fBstruct project *\fR\fBgetdefaultproj\fR(\fBconst char *\fR\fIusername\fR,
     \fBstruct project *\fR\fIproj\fR, \fBvoid *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR);
.fi

.LP
.nf
\fBint\fR \fBinproj\fR(\fBconst char *\fR\fIusername\fR, \fBconst char *\fR\fIprojname\fR,
     \fBvoid *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR);
.fi

.LP
.nf
\fBprojid_t\fR \fBgetprojidbyname\fR(\fBconst char *\fR\fIname\fR);
.fi

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

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

.LP
.nf
\fBstruct project *\fR\fBfgetprojent\fR(\fBFILE *\fR\fIf\fR, \fBstruct project *\fR\fIproj\fR,
     \fBvoid *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR);
.fi

.SH DESCRIPTION
.sp
.LP
These functions are used to obtain entries describing user projects. Entries
can come from any of the sources for a project specified in the
\fB/etc/nsswitch.conf\fR file (see \fBnsswitch.conf\fR(4)).
.sp
.LP
The \fBsetprojent()\fR, \fBgetprojent()\fR, and \fBendprojent()\fR functions
are used to enumerate project entries from the database.
.sp
.LP
The \fBsetprojent()\fR function effectively rewinds the project database to
allow repeated searches. It sets (or resets) the enumeration to the beginning
of the set of project entries. This function should be called before the first
call to \fBgetprojent()\fR.
.sp
.LP
The \fBgetprojent()\fR function returns a pointer to a structure containing the
broken-out fields of an entry in the project database. When first called,
\fBgetprojent()\fR returns a pointer to a project structure containing the
first project structure in the project database. Successive calls can be used
to read the entire database.
.sp
.LP
The \fBendprojent()\fR function closes the project database and deallocates
resources when processing is complete. It is permissible, though possibly less
efficient, for the process to call more project functions after calling
\fBendprojent()\fR.
.sp
.LP
The \fBgetprojbyname()\fR function searches the project database for an entry
with the project name specified by the character string \fIname\fR.
.sp
.LP
The \fBgetprojbyid()\fR function searches the project database for an entry
with the (numeric) project \fBID\fR specified by \fIprojid\fR.
.sp
.LP
The \fBgetdefaultproj()\fR function first looks up the project key word in the
\fBuser_attr\fR database used to define user attributes in restricted Solaris
environments. If the database is available and the keyword is present, the
function looks up the named project, returning \fINULL\fR if it cannot be found
or if the user is not a member of the named project. If absent, the function
looks for a match in the project database for the special project
\fBuser\fR.\fIusername\fR. If no match is found, or if the user is excluded
from project \fBuser\fR.\fIusername\fR, the function looks at the default group
entry of the \fBpasswd\fR database for the user, and looks for a match in the
project database for the special name \fBgroup\fR.\fIgroupname\fR, where
\fIgroupname\fR is the default group associated with the password entry
corresponding to the given \fIusername\fR. If no match is found, or if the user
is excluded from project \fBgroup\fR.\fIgroupname\fR, the function returns
\fINULL\fR. A special project entry called 'default' can be looked up and used
as a last resort, unless the user is excluded from project 'default'. On
successful lookup, this function returns a pointer to the valid \fBproject\fR
structure. By convention, the user must have a default project defined on a
system to be able to log on to that system.
.sp
.LP
The \fBinproj()\fR function checks if the user specified by \fIusername\fR is
able to use the project specified by \fIprojname\fR. This function returns 1 if
the user belongs to the list of project's users, if there is a project's group
that contains the specified user, if project is a user's default project, or if
project's user or group list contains "*"  wildcard. In all other cases it
returns 0.
.sp
.LP
The \fBgetprojidbyname()\fR function searches the project database for an entry
with the project name specified by the character string name. This function
returns the project ID if the requested entry is found; otherwise it returns
\(mi1.
.sp
.LP
The \fBfgetprojent()\fR function, unlike the other functions described 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 \fBproject\fR(4)
file. This function returns the same values as \fBgetprojent()\fR.
.sp
.LP
The \fBgetprojent()\fR, \fBgetprojbyname()\fR, \fBgetprojbyid()\fR,
\fBgetdefaultproj()\fR, and \fBinproj()\fR functions are reentrant interfaces
for operations with the \fBproject\fR database. These functions use buffers
supplied by the caller to store returned results and are safe for use in both
single-threaded and multithreaded applications.
.sp
.LP
Reentrant interfaces require the additional arguments \fIproj\fR, \fIbuffer\fR,
and \fIbufsize\fR. The \fIproj\fR argument must be a pointer to a \fBstruct
project\fR structure allocated by the caller. On successful completion, the
function returns the project entry in this structure. Storage referenced by the
\fBproject\fR structure is allocated from the memory provided with the
\fIbuffer\fR argument, which is \fIbufsize\fR bytes in size. The  content  of
the memory buffer could be lost in cases when these functions return errors.
.sp
.LP
For enumeration in multithreaded applications, the position within the
enumeration is a process-wide property shared by all threads. The
\fBsetprojent()\fR function can be used in a multithreaded application but
resets the enumeration position for all threads. If multiple threads interleave
calls to \fBgetprojent()\fR, the threads will enumerate disjoint subsets of the
project database. The \fBinproj()\fR, \fBgetprojbyname()\fR,
\fBgetprojbyid()\fR, and \fBgetdefaultproj()\fR functions leave the enumeration
position in an indeterminate state.
.SH RETURN VALUES
.sp
.LP
Project entries are represented by the \fBstruct project\fR structure defined
in <\fBproject.h\fR>.
.sp
.in +2
.nf
struct project {
    char      *pj_name;     /* name of the project */
    projid_t  pj_projid;    /* numerical project id */
    char      *pj_comment;  /* project comment */
    char      **pj_users;   /* vector of pointers to 
                               project user names */
    char      **pj_groups;  /* vector of pointers to 
                               project group names */
    char      *pj_attr;     /* project attributes */
};
.fi
.in -2

.sp
.LP
The \fBgetprojbyname()\fR and \fBgetprojbyid()\fR functions each return a
pointer to a \fBstruct project\fR if they successfully locate the requested
entry; otherwise they return \fINULL\fR.
.sp
.LP
The \fBgetprojent()\fR function returns a pointer to a \fBstruct project\fR if
it successfully enumerates an entry; otherwise it returns \fINULL\fR,
indicating the end of the enumeration.
.sp
.LP
The \fBgetprojidbyname()\fR function returns the project ID if the requsted
entry is found; otherwise it returns \(mi1 and sets errno to indicate the
error.
.sp
.LP
When the pointer returned by the reentrant functions \fBgetprojbyname()\fR,
\fBgetprojbyid()\fR, and \fBgetprojent()\fR is non-null, it is always equal to
the \fIproj\fR pointer that was supplied by the caller.
.sp
.LP
Upon failure, \fBNULL\fR is returned and errno is set to indicate the error.
.SH ERRORS
.sp
.LP
The \fBgetprojent()\fR, \fBgetprojbyname()\fR, \fBgetprojbyid()\fR,
\fBinproj()\fR, \fBgetprojidbyname()\fR, \fBfgetprojent()\fR, and
\fBgetdefaultproj()\fR functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEINTR\fR\fR
.ad
.RS 10n
.rt  
A signal was caught during the operation.
.RE

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

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

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

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

.sp
.LP
These functions can also fail if the name service switch does not specify valid
\fBproject\fR(4) name service sources. In the case of an incompletely
configurated name service switch configuration, \fBgetprojbyid()\fR and other
functions can return error values other than those documented above. These
conditions usually occur when the \fBnsswitch.conf\fR file indicates that one
or more name services is providing entries for the project database when that
name service does not actually make a project table available.
.SH USAGE
.sp
.LP
When compiling multithreaded applications, see \fBIntro\fR(3), Notes On
Multithreaded Applications.
.sp
.LP
Use of the enumeration interface \fBgetprojent()\fR is discouraged. Enumeration
is supported for the project file, NIS, and LDAP but in general is not
efficient. The semantics of enumeration are discussed further in
\fBnsswitch.conf\fR(4).
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.64i) |cw(2.86i) 
lw(2.64i) |lw(2.86i) 
.
ATTRIBUTE  TYPEATTRIBUTE VALUE
_
Interface StabilityEvolving
_
MT-LevelSee Description.
.TE

.SH SEE ALSO
.sp
.LP
\fBIntro\fR(3), \fBlibproject\fR(3LIB), \fBproject_walk\fR(3PROJECT),
\fBsysconf\fR(3C), \fBnsswitch.conf\fR(4), \fBproject\fR(4),
\fBattributes\fR(5)