47 \fBprojid_t\fR \fBgetprojidbyname\fR(\fBconst char *\fR\fIname\fR);
48 .fi
49
50 .LP
51 .nf
52 \fBvoid\fR \fBsetprojent\fR(\fBvoid\fR);
53 .fi
54
55 .LP
56 .nf
57 \fBvoid\fR \fBendprojent\fR(\fBvoid\fR);
58 .fi
59
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
65
66 .SH DESCRIPTION
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
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.
169 .SH RETURN VALUES
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
189
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.
213 .SH ERRORS
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
227
228 .sp
229 .ne 2
230 .na
231 \fB\fBEIO\fR\fR
232 .ad
233 .RS 10n
234 An I/O error has occurred.
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
255
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
265
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).
286 .SH ATTRIBUTES
287 .sp
288 .LP
289 See \fBattributes\fR(5) for descriptions of the following attributes:
290 .sp
291
292 .sp
293 .TS
294 box;
295 c | c
296 l | l .
297 ATTRIBUTE TYPE ATTRIBUTE VALUE
298 _
299 Interface Stability Evolving
300 _
301 MT-Level See Description.
302 .TE
303
304 .SH SEE ALSO
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)
|
47 \fBprojid_t\fR \fBgetprojidbyname\fR(\fBconst char *\fR\fIname\fR);
48 .fi
49
50 .LP
51 .nf
52 \fBvoid\fR \fBsetprojent\fR(\fBvoid\fR);
53 .fi
54
55 .LP
56 .nf
57 \fBvoid\fR \fBendprojent\fR(\fBvoid\fR);
58 .fi
59
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
65
66 .SH DESCRIPTION
67 .LP
68 These functions are used to obtain entries describing user projects. Entries
69 can come from any of the sources for a project specified in the
70 \fB/etc/nsswitch.conf\fR file (see \fBnsswitch.conf\fR(4)).
71 .sp
72 .LP
73 The \fBsetprojent()\fR, \fBgetprojent()\fR, and \fBendprojent()\fR functions
74 are used to enumerate project entries from the database.
75 .sp
76 .LP
77 The \fBsetprojent()\fR function effectively rewinds the project database to
78 allow repeated searches. It sets (or resets) the enumeration to the beginning
79 of the set of project entries. This function should be called before the first
80 call to \fBgetprojent()\fR.
81 .sp
82 .LP
83 The \fBgetprojent()\fR function returns a pointer to a structure containing the
84 broken-out fields of an entry in the project database. When first called,
85 \fBgetprojent()\fR returns a pointer to a project structure containing the
86 first project structure in the project database. Successive calls can be used
149 .sp
150 .LP
151 Reentrant interfaces require the additional arguments \fIproj\fR, \fIbuffer\fR,
152 and \fIbufsize\fR. The \fIproj\fR argument must be a pointer to a \fBstruct
153 project\fR structure allocated by the caller. On successful completion, the
154 function returns the project entry in this structure. Storage referenced by the
155 \fBproject\fR structure is allocated from the memory provided with the
156 \fIbuffer\fR argument, which is \fIbufsize\fR bytes in size. The content of
157 the memory buffer could be lost in cases when these functions return errors.
158 .sp
159 .LP
160 For enumeration in multithreaded applications, the position within the
161 enumeration is a process-wide property shared by all threads. The
162 \fBsetprojent()\fR function can be used in a multithreaded application but
163 resets the enumeration position for all threads. If multiple threads interleave
164 calls to \fBgetprojent()\fR, the threads will enumerate disjoint subsets of the
165 project database. The \fBinproj()\fR, \fBgetprojbyname()\fR,
166 \fBgetprojbyid()\fR, and \fBgetdefaultproj()\fR functions leave the enumeration
167 position in an indeterminate state.
168 .SH RETURN VALUES
169 .LP
170 Project entries are represented by the \fBstruct project\fR structure defined
171 in <\fBproject.h\fR>.
172 .sp
173 .in +2
174 .nf
175 struct project {
176 char *pj_name; /* name of the project */
177 projid_t pj_projid; /* numerical project id */
178 char *pj_comment; /* project comment */
179 char **pj_users; /* vector of pointers to
180 project user names */
181 char **pj_groups; /* vector of pointers to
182 project group names */
183 char *pj_attr; /* project attributes */
184 };
185 .fi
186 .in -2
187
188 .sp
189 .LP
190 The \fBgetprojbyname()\fR and \fBgetprojbyid()\fR functions each return a
191 pointer to a \fBstruct project\fR if they successfully locate the requested
192 entry; otherwise they return \fINULL\fR.
193 .sp
194 .LP
195 The \fBgetprojent()\fR function returns a pointer to a \fBstruct project\fR if
196 it successfully enumerates an entry; otherwise it returns \fINULL\fR,
197 indicating the end of the enumeration.
198 .sp
199 .LP
200 The \fBgetprojidbyname()\fR function returns the project ID if the requested
201 entry is found; otherwise it returns \(mi1 and sets errno to indicate the
202 error.
203 .sp
204 .LP
205 When the pointer returned by the reentrant functions \fBgetprojbyname()\fR,
206 \fBgetprojbyid()\fR, and \fBgetprojent()\fR is non-null, it is always equal to
207 the \fIproj\fR pointer that was supplied by the caller.
208 .sp
209 .LP
210 Upon failure, \fBNULL\fR is returned and errno is set to indicate the error.
211 .SH ERRORS
212 .LP
213 The \fBgetprojent()\fR, \fBgetprojbyname()\fR, \fBgetprojbyid()\fR,
214 \fBinproj()\fR, \fBgetprojidbyname()\fR, \fBfgetprojent()\fR, and
215 \fBgetdefaultproj()\fR functions will fail if:
216 .sp
217 .ne 2
218 .na
219 \fB\fBEINTR\fR\fR
220 .ad
221 .RS 10n
222 A signal was caught during the operation.
223 .RE
224
225 .sp
226 .ne 2
227 .na
228 \fB\fBEIO\fR\fR
229 .ad
230 .RS 10n
231 An I/O error has occurred.
247 \fB\fBENFILE\fR\fR
248 .ad
249 .RS 10n
250 The maximum allowable number of files is currently open in the system.
251 .RE
252
253 .sp
254 .ne 2
255 .na
256 \fB\fBERANGE\fR\fR
257 .ad
258 .RS 10n
259 Insufficient storage was supplied by \fIbuffer\fR and \fIbufsize\fR to contain
260 the data to be referenced by the resulting \fBproject\fR structure.
261 .RE
262
263 .sp
264 .LP
265 These functions can also fail if the name service switch does not specify valid
266 \fBproject\fR(4) name service sources. In the case of an incompletely
267 configured name service switch configuration, \fBgetprojbyid()\fR and other
268 functions can return error values other than those documented above. These
269 conditions usually occur when the \fBnsswitch.conf\fR file indicates that one
270 or more name services is providing entries for the project database when that
271 name service does not actually make a project table available.
272 .SH USAGE
273 .LP
274 When compiling multithreaded applications, see \fBIntro\fR(3), Notes On
275 Multithreaded Applications.
276 .sp
277 .LP
278 Use of the enumeration interface \fBgetprojent()\fR is discouraged. Enumeration
279 is supported for the project file, NIS, and LDAP but in general is not
280 efficient. The semantics of enumeration are discussed further in
281 \fBnsswitch.conf\fR(4).
282 .SH ATTRIBUTES
283 .LP
284 See \fBattributes\fR(5) for descriptions of the following attributes:
285 .sp
286
287 .sp
288 .TS
289 box;
290 c | c
291 l | l .
292 ATTRIBUTE TYPE ATTRIBUTE VALUE
293 _
294 Interface Stability Evolving
295 _
296 MT-Level See Description.
297 .TE
298
299 .SH SEE ALSO
300 .LP
301 \fBIntro\fR(3), \fBlibproject\fR(3LIB), \fBproject_walk\fR(3PROJECT),
302 \fBsysconf\fR(3C), \fBnsswitch.conf\fR(4), \fBproject\fR(4),
303 \fBattributes\fR(5)
|