1 GETPROJENT(3PROJECT) Project Database Access Library Functions
2
3
4
5 NAME
6 getprojent, getprojbyname, getprojbyid, getdefaultproj, inproj,
7 getprojidbyname, setprojent, endprojent, fgetprojent - project database
8 entry operations
9
10 SYNOPSIS
11 cc [ flag... ] file... -lproject [ library... ]
12 #include <project.h>
13
14 struct project *getprojent(struct project *proj, void *buffer,
15 size_t bufsize);
16
17
18 struct project *getprojbyname(const char *name,
19 struct project *proj, void *buffer, size_t bufsize);
20
21
22 struct project *getprojbyid(projid_t projid,
23 struct project *proj, void *buffer, size_t bufsize);
24
25
26 struct project *getdefaultproj(const char *username,
27 struct project *proj, void *buffer, size_t bufsize);
28
29
30 int inproj(const char *username, const char *projname,
31 void *buffer, size_t bufsize);
32
33
34 projid_t getprojidbyname(const char *name);
35
36
37 void setprojent(void);
38
39
40 void endprojent(void);
41
42
43 struct project *fgetprojent(FILE *f, struct project *proj,
44 void *buffer, size_t bufsize);
45
46
47 DESCRIPTION
48 These functions are used to obtain entries describing user projects.
49 Entries can come from any of the sources for a project specified in the
50 /etc/nsswitch.conf file (see nsswitch.conf(4)).
51
52
53 The setprojent(), getprojent(), and endprojent() functions are used to
54 enumerate project entries from the database.
55
56
57 The setprojent() function effectively rewinds the project database to
58 allow repeated searches. It sets (or resets) the enumeration to the
59 beginning of the set of project entries. This function should be called
60 before the first call to getprojent().
61
62
63 The getprojent() function returns a pointer to a structure containing
64 the broken-out fields of an entry in the project database. When first
65 called, getprojent() returns a pointer to a project structure
66 containing the first project structure in the project database.
67 Successive calls can be used to read the entire database.
68
69
70 The endprojent() function closes the project database and deallocates
71 resources when processing is complete. It is permissible, though
72 possibly less efficient, for the process to call more project functions
73 after calling endprojent().
74
75
76 The getprojbyname() function searches the project database for an entry
77 with the project name specified by the character string name.
78
79
80 The getprojbyid() function searches the project database for an entry
81 with the (numeric) project ID specified by projid.
82
83
84 The getdefaultproj() function first looks up the project key word in
85 the user_attr database used to define user attributes in restricted
86 Solaris environments. If the database is available and the keyword is
87 present, the function looks up the named project, returning NULL if it
88 cannot be found or if the user is not a member of the named project. If
89 absent, the function looks for a match in the project database for the
90 special project user.username. If no match is found, or if the user is
91 excluded from project user.username, the function looks at the default
92 group entry of the passwd database for the user, and looks for a match
93 in the project database for the special name group.groupname, where
94 groupname is the default group associated with the password entry
95 corresponding to the given username. If no match is found, or if the
96 user is excluded from project group.groupname, the function returns
97 NULL. A special project entry called 'default' can be looked up and
98 used as a last resort, unless the user is excluded from project
99 'default'. On successful lookup, this function returns a pointer to the
100 valid project structure. By convention, the user must have a default
101 project defined on a system to be able to log on to that system.
102
103
104 The inproj() function checks if the user specified by username is able
105 to use the project specified by projname. This function returns 1 if
106 the user belongs to the list of project's users, if there is a
107 project's group that contains the specified user, if project is a
108 user's default project, or if project's user or group list contains "*"
109 wildcard. In all other cases it returns 0.
110
111
112 The getprojidbyname() function searches the project database for an
113 entry with the project name specified by the character string name.
114 This function returns the project ID if the requested entry is found;
115 otherwise it returns -1.
116
117
118 The fgetprojent() function, unlike the other functions described above,
119 does not use nsswitch.conf; it reads and parses the next line from the
120 stream f, which is assumed to have the format of the project(4) file.
121 This function returns the same values as getprojent().
122
123
124 The getprojent(), getprojbyname(), getprojbyid(), getdefaultproj(), and
125 inproj() functions are reentrant interfaces for operations with the
126 project database. These functions use buffers supplied by the caller to
127 store returned results and are safe for use in both single-threaded and
128 multithreaded applications.
129
130
131 Reentrant interfaces require the additional arguments proj, buffer, and
132 bufsize. The proj argument must be a pointer to a struct project
133 structure allocated by the caller. On successful completion, the
134 function returns the project entry in this structure. Storage
135 referenced by the project structure is allocated from the memory
136 provided with the buffer argument, which is bufsize bytes in size. The
137 content of the memory buffer could be lost in cases when these
138 functions return errors.
139
140
141 For enumeration in multithreaded applications, the position within the
142 enumeration is a process-wide property shared by all threads. The
143 setprojent() function can be used in a multithreaded application but
144 resets the enumeration position for all threads. If multiple threads
145 interleave calls to getprojent(), the threads will enumerate disjoint
146 subsets of the project database. The inproj(), getprojbyname(),
147 getprojbyid(), and getdefaultproj() functions leave the enumeration
148 position in an indeterminate state.
149
150 RETURN VALUES
151 Project entries are represented by the struct project structure defined
152 in <project.h>.
153
154 struct project {
155 char *pj_name; /* name of the project */
156 projid_t pj_projid; /* numerical project id */
157 char *pj_comment; /* project comment */
158 char **pj_users; /* vector of pointers to
159 project user names */
160 char **pj_groups; /* vector of pointers to
161 project group names */
162 char *pj_attr; /* project attributes */
163 };
164
165
166
167 The getprojbyname() and getprojbyid() functions each return a pointer
168 to a struct project if they successfully locate the requested entry;
169 otherwise they return NULL.
170
171
172 The getprojent() function returns a pointer to a struct project if it
173 successfully enumerates an entry; otherwise it returns NULL, indicating
174 the end of the enumeration.
175
176
177 The getprojidbyname() function returns the project ID if the requested
178 entry is found; otherwise it returns -1 and sets errno to indicate the
179 error.
180
181
182 When the pointer returned by the reentrant functions getprojbyname(),
183 getprojbyid(), and getprojent() is non-null, it is always equal to the
184 proj pointer that was supplied by the caller.
185
186
187 Upon failure, NULL is returned and errno is set to indicate the error.
188
189 ERRORS
190 The getprojent(), getprojbyname(), getprojbyid(), inproj(),
191 getprojidbyname(), fgetprojent(), and getdefaultproj() functions will
192 fail if:
193
194 EINTR
195 A signal was caught during the operation.
196
197
198 EIO
199 An I/O error has occurred.
200
201
202 EMFILE
203 There are OPEN_MAX file descriptors currently open in the
204 calling process.
205
206
207 ENFILE
208 The maximum allowable number of files is currently open in
209 the system.
210
211
212 ERANGE
213 Insufficient storage was supplied by buffer and bufsize to
214 contain the data to be referenced by the resulting project
215 structure.
216
217
218
219 These functions can also fail if the name service switch does not
220 specify valid project(4) name service sources. In the case of an
221 incompletely configured name service switch configuration,
222 getprojbyid() and other functions can return error values other than
223 those documented above. These conditions usually occur when the
224 nsswitch.conf file indicates that one or more name services is
225 providing entries for the project database when that name service does
226 not actually make a project table available.
227
228 USAGE
229 When compiling multithreaded applications, see Intro(3), Notes On
230 Multithreaded Applications.
231
232
233 Use of the enumeration interface getprojent() is discouraged.
234 Enumeration is supported for the project file, NIS, and LDAP but in
235 general is not efficient. The semantics of enumeration are discussed
236 further in nsswitch.conf(4).
237
238 ATTRIBUTES
239 See attributes(5) for descriptions of the following attributes:
240
241
242
243
244 +--------------------+------------------+
245 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
246 +--------------------+------------------+
247 |Interface Stability | Evolving |
248 +--------------------+------------------+
249 |MT-Level | See Description. |
250 +--------------------+------------------+
251
252 SEE ALSO
253 Intro(3), libproject(3LIB), project_walk(3PROJECT), sysconf(3C),
254 nsswitch.conf(4), project(4), attributes(5)
255
256
257
258 April 5, 2004 GETPROJENT(3PROJECT)