1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH GETPROJENT 3PROJECT "Apr 5, 2004"
   7 .SH NAME
   8 getprojent, getprojbyname, getprojbyid, getdefaultproj, inproj,
   9 getprojidbyname, setprojent, endprojent, fgetprojent \- project database entry
  10 operations
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR... ] \fIfile\fR... \(milproject [ \fIlibrary\fR... ]
  15 #include <project.h>
  17 \fBstruct project *\fR\fBgetprojent\fR(\fBstruct project *\fR\fIproj\fR, \fBvoid *\fR\fIbuffer\fR,
  18      \fBsize_t\fR \fIbufsize\fR);
  19 .fi
  21 .LP
  22 .nf
  23 \fBstruct project *\fR\fBgetprojbyname\fR(\fBconst char *\fR\fIname\fR,
  24      \fBstruct project *\fR\fIproj\fR, \fBvoid *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR);
  25 .fi
  27 .LP
  28 .nf
  29 \fBstruct project *\fR\fBgetprojbyid\fR(\fBprojid_t\fR \fIprojid\fR,
  30      \fBstruct project *\fR\fIproj\fR, \fBvoid *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR);
  31 .fi
  33 .LP
  34 .nf
  35 \fBstruct project *\fR\fBgetdefaultproj\fR(\fBconst char *\fR\fIusername\fR,
  36      \fBstruct project *\fR\fIproj\fR, \fBvoid *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR);
  37 .fi
  39 .LP
  40 .nf
  41 \fBint\fR \fBinproj\fR(\fBconst char *\fR\fIusername\fR, \fBconst char *\fR\fIprojname\fR,
  42      \fBvoid *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR);
  43 .fi
  45 .LP
  46 .nf
  47 \fBprojid_t\fR \fBgetprojidbyname\fR(\fBconst char *\fR\fIname\fR);
  48 .fi
  50 .LP
  51 .nf
  52 \fBvoid\fR \fBsetprojent\fR(\fBvoid\fR);
  53 .fi
  55 .LP
  56 .nf
  57 \fBvoid\fR \fBendprojent\fR(\fBvoid\fR);
  58 .fi
  60 .LP
  61 .nf
  62 \fBstruct project *\fR\fBfgetprojent\fR(\fBFILE *\fR\fIf\fR, \fBstruct project *\fR\fIproj\fR,
  63      \fBvoid *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR);
  64 .fi
  67 .sp
  68 .LP
  69 These functions are used to obtain entries describing user projects. Entries
  70 can come from any of the sources for a project specified in the
  71 \fB/etc/nsswitch.conf\fR file (see \fBnsswitch.conf\fR(4)).
  72 .sp
  73 .LP
  74 The \fBsetprojent()\fR, \fBgetprojent()\fR, and \fBendprojent()\fR functions
  75 are used to enumerate project entries from the database.
  76 .sp
  77 .LP
  78 The \fBsetprojent()\fR function effectively rewinds the project database to
  79 allow repeated searches. It sets (or resets) the enumeration to the beginning
  80 of the set of project entries. This function should be called before the first
  81 call to \fBgetprojent()\fR.
  82 .sp
  83 .LP
  84 The \fBgetprojent()\fR function returns a pointer to a structure containing the
  85 broken-out fields of an entry in the project database. When first called,
  86 \fBgetprojent()\fR returns a pointer to a project structure containing the
  87 first project structure in the project database. Successive calls can be used
  88 to read the entire database.
  89 .sp
  90 .LP
  91 The \fBendprojent()\fR function closes the project database and deallocates
  92 resources when processing is complete. It is permissible, though possibly less
  93 efficient, for the process to call more project functions after calling
  94 \fBendprojent()\fR.
  95 .sp
  96 .LP
  97 The \fBgetprojbyname()\fR function searches the project database for an entry
  98 with the project name specified by the character string \fIname\fR.
  99 .sp
 100 .LP
 101 The \fBgetprojbyid()\fR function searches the project database for an entry
 102 with the (numeric) project \fBID\fR specified by \fIprojid\fR.
 103 .sp
 104 .LP
 105 The \fBgetdefaultproj()\fR function first looks up the project key word in the
 106 \fBuser_attr\fR database used to define user attributes in restricted Solaris
 107 environments. If the database is available and the keyword is present, the
 108 function looks up the named project, returning \fINULL\fR if it cannot be found
 109 or if the user is not a member of the named project. If absent, the function
 110 looks for a match in the project database for the special project
 111 \fBuser\fR.\fIusername\fR. If no match is found, or if the user is excluded
 112 from project \fBuser\fR.\fIusername\fR, the function looks at the default group
 113 entry of the \fBpasswd\fR database for the user, and looks for a match in the
 114 project database for the special name \fBgroup\fR.\fIgroupname\fR, where
 115 \fIgroupname\fR is the default group associated with the password entry
 116 corresponding to the given \fIusername\fR. If no match is found, or if the user
 117 is excluded from project \fBgroup\fR.\fIgroupname\fR, the function returns
 118 \fINULL\fR. A special project entry called 'default' can be looked up and used
 119 as a last resort, unless the user is excluded from project 'default'. On
 120 successful lookup, this function returns a pointer to the valid \fBproject\fR
 121 structure. By convention, the user must have a default project defined on a
 122 system to be able to log on to that system.
 123 .sp
 124 .LP
 125 The \fBinproj()\fR function checks if the user specified by \fIusername\fR is
 126 able to use the project specified by \fIprojname\fR. This function returns 1 if
 127 the user belongs to the list of project's users, if there is a project's group
 128 that contains the specified user, if project is a user's default project, or if
 129 project's user or group list contains "*"  wildcard. In all other cases it
 130 returns 0.
 131 .sp
 132 .LP
 133 The \fBgetprojidbyname()\fR function searches the project database for an entry
 134 with the project name specified by the character string name. This function
 135 returns the project ID if the requested entry is found; otherwise it returns
 136 \(mi1.
 137 .sp
 138 .LP
 139 The \fBfgetprojent()\fR function, unlike the other functions described above,
 140 does not use \fBnsswitch.conf\fR; it reads and parses the next line from the
 141 stream \fIf\fR, which is assumed to have the format of the \fBproject\fR(4)
 142 file. This function returns the same values as \fBgetprojent()\fR.
 143 .sp
 144 .LP
 145 The \fBgetprojent()\fR, \fBgetprojbyname()\fR, \fBgetprojbyid()\fR,
 146 \fBgetdefaultproj()\fR, and \fBinproj()\fR functions are reentrant interfaces
 147 for operations with the \fBproject\fR database. These functions use buffers
 148 supplied by the caller to store returned results and are safe for use in both
 149 single-threaded and multithreaded applications.
 150 .sp
 151 .LP
 152 Reentrant interfaces require the additional arguments \fIproj\fR, \fIbuffer\fR,
 153 and \fIbufsize\fR. The \fIproj\fR argument must be a pointer to a \fBstruct
 154 project\fR structure allocated by the caller. On successful completion, the
 155 function returns the project entry in this structure. Storage referenced by the
 156 \fBproject\fR structure is allocated from the memory provided with the
 157 \fIbuffer\fR argument, which is \fIbufsize\fR bytes in size. The  content  of
 158 the memory buffer could be lost in cases when these functions return errors.
 159 .sp
 160 .LP
 161 For enumeration in multithreaded applications, the position within the
 162 enumeration is a process-wide property shared by all threads. The
 163 \fBsetprojent()\fR function can be used in a multithreaded application but
 164 resets the enumeration position for all threads. If multiple threads interleave
 165 calls to \fBgetprojent()\fR, the threads will enumerate disjoint subsets of the
 166 project database. The \fBinproj()\fR, \fBgetprojbyname()\fR,
 167 \fBgetprojbyid()\fR, and \fBgetdefaultproj()\fR functions leave the enumeration
 168 position in an indeterminate state.
 170 .sp
 171 .LP
 172 Project entries are represented by the \fBstruct project\fR structure defined
 173 in <\fBproject.h\fR>.
 174 .sp
 175 .in +2
 176 .nf
 177 struct project {
 178     char      *pj_name;     /* name of the project */
 179     projid_t  pj_projid;    /* numerical project id */
 180     char      *pj_comment;  /* project comment */
 181     char      **pj_users;   /* vector of pointers to
 182                                project user names */
 183     char      **pj_groups;  /* vector of pointers to
 184                                project group names */
 185     char      *pj_attr;     /* project attributes */
 186 };
 187 .fi
 188 .in -2
 190 .sp
 191 .LP
 192 The \fBgetprojbyname()\fR and \fBgetprojbyid()\fR functions each return a
 193 pointer to a \fBstruct project\fR if they successfully locate the requested
 194 entry; otherwise they return \fINULL\fR.
 195 .sp
 196 .LP
 197 The \fBgetprojent()\fR function returns a pointer to a \fBstruct project\fR if
 198 it successfully enumerates an entry; otherwise it returns \fINULL\fR,
 199 indicating the end of the enumeration.
 200 .sp
 201 .LP
 202 The \fBgetprojidbyname()\fR function returns the project ID if the requsted
 203 entry is found; otherwise it returns \(mi1 and sets errno to indicate the
 204 error.
 205 .sp
 206 .LP
 207 When the pointer returned by the reentrant functions \fBgetprojbyname()\fR,
 208 \fBgetprojbyid()\fR, and \fBgetprojent()\fR is non-null, it is always equal to
 209 the \fIproj\fR pointer that was supplied by the caller.
 210 .sp
 211 .LP
 212 Upon failure, \fBNULL\fR is returned and errno is set to indicate the error.
 214 .sp
 215 .LP
 216 The \fBgetprojent()\fR, \fBgetprojbyname()\fR, \fBgetprojbyid()\fR,
 217 \fBinproj()\fR, \fBgetprojidbyname()\fR, \fBfgetprojent()\fR, and
 218 \fBgetdefaultproj()\fR functions will fail if:
 219 .sp
 220 .ne 2
 221 .na
 222 \fB\fBEINTR\fR\fR
 223 .ad
 224 .RS 10n
 225 A signal was caught during the operation.
 226 .RE
 228 .sp
 229 .ne 2
 230 .na
 231 \fB\fBEIO\fR\fR
 232 .ad
 233 .RS 10n
 234 An I/O error has occurred.
 235 .RE
 237 .sp
 238 .ne 2
 239 .na
 240 \fB\fBEMFILE\fR\fR
 241 .ad
 242 .RS 10n
 243 There are \fBOPEN_MAX\fR file descriptors currently open in the calling
 244 process.
 245 .RE
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fBENFILE\fR\fR
 251 .ad
 252 .RS 10n
 253 The maximum allowable number of files is currently open in the system.
 254 .RE
 256 .sp
 257 .ne 2
 258 .na
 259 \fB\fBERANGE\fR\fR
 260 .ad
 261 .RS 10n
 262 Insufficient storage was supplied by \fIbuffer\fR and \fIbufsize\fR to contain
 263 the data to be referenced by the resulting \fBproject\fR structure.
 264 .RE
 266 .sp
 267 .LP
 268 These functions can also fail if the name service switch does not specify valid
 269 \fBproject\fR(4) name service sources. In the case of an incompletely
 270 configurated name service switch configuration, \fBgetprojbyid()\fR and other
 271 functions can return error values other than those documented above. These
 272 conditions usually occur when the \fBnsswitch.conf\fR file indicates that one
 273 or more name services is providing entries for the project database when that
 274 name service does not actually make a project table available.
 275 .SH USAGE
 276 .sp
 277 .LP
 278 When compiling multithreaded applications, see \fBIntro\fR(3), Notes On
 279 Multithreaded Applications.
 280 .sp
 281 .LP
 282 Use of the enumeration interface \fBgetprojent()\fR is discouraged. Enumeration
 283 is supported for the project file, NIS, and LDAP but in general is not
 284 efficient. The semantics of enumeration are discussed further in
 285 \fBnsswitch.conf\fR(4).
 287 .sp
 288 .LP
 289 See \fBattributes\fR(5) for descriptions of the following attributes:
 290 .sp
 292 .sp
 293 .TS
 294 box;
 295 c | c
 296 l | l .
 298 _
 299 Interface Stability     Evolving
 300 _
 301 MT-Level        See Description.
 302 .TE
 305 .sp
 306 .LP
 307 \fBIntro\fR(3), \fBlibproject\fR(3LIB), \fBproject_walk\fR(3PROJECT),
 308 \fBsysconf\fR(3C), \fBnsswitch.conf\fR(4), \fBproject\fR(4),
 309 \fBattributes\fR(5)