1getprojent(3PROJECT)Project Database Access Library Functiongsetprojent(3PROJECT)
2
3
4

NAME

6       getprojent, getprojbyname, getprojbyid, getdefaultproj, inproj, getpro‐
7       jidbyname, setprojent, endprojent, fgetprojent - project database entry
8       operations
9

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

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 contain‐
66       ing the first project structure in  the  project  database.  Successive
67       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 possi‐
72       bly  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  cor‐
95       responding  to the given username. If no match is found, or if the user
96       is excluded from project group.groupname, the function returns NULL.  A
97       special  project  entry called 'default' can be looked up and used as a
98       last resort, unless the user is excluded  from  project  'default'.  On
99       successful lookup, this function returns a pointer to the valid project
100       structure. By convention, the user must have a default project  defined
101       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 struc‐
133       ture allocated by the caller. On successful  completion,  the  function
134       returns  the project entry in this structure. Storage referenced by the
135       project structure is allocated from the memory provided with the buffer
136       argument,  which  is bufsize bytes in size. The  content  of the memory
137       buffer could be lost in cases when these functions return errors.
138
139
140       For enumeration in multithreaded applications, the position within  the
141       enumeration  is a process-wide property shared by all threads. The set‐
142       projent() function can be  used  in  a  multithreaded  application  but
143       resets  the  enumeration  position for all threads. If multiple threads
144       interleave calls to getprojent(), the threads will  enumerate  disjoint
145       subsets of the project database. The inproj(), getprojbyname(), getpro‐
146       jbyid(), and getdefaultproj() functions leave the enumeration  position
147       in an indeterminate state.
148

RETURN VALUES

150       Project entries are represented by the struct project structure defined
151       in <project.h>.
152
153         struct project {
154             char      *pj_name;     /* name of the project */
155             projid_t  pj_projid;    /* numerical project id */
156             char      *pj_comment;  /* project comment */
157             char      **pj_users;   /* vector of pointers to
158                                        project user names */
159             char      **pj_groups;  /* vector of pointers to
160                                        project group names */
161             char      *pj_attr;     /* project attributes */
162         };
163
164
165
166       The getprojbyname() and getprojbyid() functions each return  a  pointer
167       to  a  struct  project if they successfully locate the requested entry;
168       otherwise they return NULL.
169
170
171       The getprojent() function returns a pointer to a struct project  if  it
172       successfully enumerates an entry; otherwise it returns NULL, indicating
173       the end of the enumeration.
174
175
176       The getprojidbyname() function returns the project ID if  the  requsted
177       entry  is found; otherwise it returns −1 and sets errno to indicate the
178       error.
179
180
181       When the pointer returned by the reentrant  functions  getprojbyname(),
182       getprojbyid(),  and getprojent() is non-null, it is always equal to the
183       proj pointer that was supplied by the caller.
184
185
186       Upon failure, NULL is returned and errno is set to indicate the error.
187

ERRORS

189       The getprojent(), getprojbyname(), getprojbyid(), inproj(),  getprojid‐
190       byname(), fgetprojent(), and getdefaultproj() functions will fail if:
191
192       EINTR     A signal was caught during the operation.
193
194
195       EIO       An I/O error has occurred.
196
197
198       EMFILE    There  are  OPEN_MAX  file  descriptors currently open in the
199                 calling process.
200
201
202       ENFILE    The maximum allowable number of files is  currently  open  in
203                 the system.
204
205
206       ERANGE    Insufficient  storage  was  supplied by buffer and bufsize to
207                 contain the data to be referenced by  the  resulting  project
208                 structure.
209
210
211
212       These functions can also fail if the name service switch does not spec‐
213       ify valid project(4) name service sources. In the  case  of  an  incom‐
214       pletely  configurated  name service switch configuration, getprojbyid()
215       and other functions can return error values other than those documented
216       above. These conditions usually occur when the nsswitch.conf file indi‐
217       cates that one or more name  services  is  providing  entries  for  the
218       project  database  when  that  name  service  does  not actually make a
219       project table available.
220

USAGE

222       When compiling multithreaded applications, see Intro(3), Notes On  Mul‐
223       tithreaded Applications.
224
225
226       Use  of the enumeration interface getprojent() is discouraged. Enumera‐
227       tion is supported for the project file, NIS, and LDAP but in general is
228       not  efficient.  The  semantics of enumeration are discussed further in
229       nsswitch.conf(4).
230

ATTRIBUTES

232       See attributes(5) for descriptions of the following attributes:
233
234
235
236
237       ┌────────────────────────────┬──────────────────────────────┐
238       │     ATTRIBUTE  TYPE        │       ATTRIBUTE VALUE        │
239       ├────────────────────────────┼──────────────────────────────┤
240       │Interface Stability         │Evolving                      │
241       ├────────────────────────────┼──────────────────────────────┤
242       │MT-Level                    │See Description.              │
243       └────────────────────────────┴──────────────────────────────┘
244

SEE ALSO

246       Intro(3), libproject(3LIB), project_walk(3PROJECT),  sysconf(3C),  nss‐
247       witch.conf(4), project(4), attributes(5)
248
249
250
251SunOS 5.11                        5 Apr 2004              getprojent(3PROJECT)
Impressum