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