'\" te .\" Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved. .TH getprojent 3PROJECT "18 Sep 2012" "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 \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 behaves as follows: .RS +4 .TP .ie t \(bu .el o It searches for a named project defined by the "project" keyword in the user's \fBuser_attr\fR entry. If no match is found, or if the user is excluded from that project, it proceeds to the next search. Otherwise, the project pointer is returned. .RE .RS +4 .TP .ie t \(bu .el o It searches for a project with a naming pattern of "\fBuser\fR.\fIuser_name\fR" where \fIuser_name\fR is the user's login name. If no match is found, or if the user is excluded from that project, it proceeds to the next search. Otherwise, the project pointer is returned. .RE .RS +4 .TP .ie t \(bu .el o It searches for a project with a naming pattern of "\fBgroup\fR.\fIgroup_name\fR" where \fIgroup_name\fR is the user's primary group name. If no match is found, or if the user is excluded from that project, it proceeds to the next search. Otherwise, the project pointer is returned. .RE .RS +4 .TP .ie t \(bu .el o It searches for a project named "default". If no match is found, or if the user is excluded from that project, it returns \fINULL\fR. Otherwise, the project pointer is returned. .RE .sp .LP The \fBinproj()\fR function checks if the user specified by \fIusername\fR is able to use the project specified by \fIprojname\fR. It returns 1 if the project is the user's default project, the user is not explicitly excluded from that project's users list, and the user is not explicitly excluded from that project's groups list. It also returns 1 if the project is a normal project, the user is not explicitly excluded from and is explicitly included in that project's users list, and the user is not explicitly excluded from and is explicitly included in that project's groups list. It returns 0 for all other cases. .sp .LP A user is considered explicitly excluded from a project's users list if there exists a "!*" or a "!\fIuser_name\fR" token, where \fIuser_name\fR is the user's login name. .sp .LP A user is considered explicitly included in a project's users list if there exists a "*" or a "\fIuser_name\fR" token, where \fIuser_name\fR is the user's login name. .sp .LP A user is considered explicitly excluded in a project's groups list if there exists a "!*" or a "!\fIgroup_name\fR" token, where \fIgroup_name\fR is the user's primary group name or the name of a group to which the user belongs. .sp .LP A user is considered explicitly included in a project's groups list if there exists a "*" or a "\fIgroup_name\fR" token, where \fIgroup_name\fR is the user's primary group name or the name of a group to which the user belongs. .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 StabilityCommitted _ 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)