Project Database Access Library Functions getprojent(3PROJECT)
NAME
getprojent, getprojbyname, getprojbyid, getdefaultproj,
inproj, getprojidbyname, setprojent, endprojent, fgetprojent
- project database entry operations
SYNOPSIS
cc [ flag... ] file... -lproject [ library... ]
#include
struct project *getprojent(struct project *proj, void *buffer,
sizet bufsize);
struct project *getprojbyname(const char *name,
struct project *proj, void *buffer, sizet bufsize);
struct project *getprojbyid(projidt projid,
struct project *proj, void *buffer, sizet bufsize);
struct project *getdefaultproj(const char *username,
struct project *proj, void *buffer, sizet bufsize);
int inproj(const char *username, const char *projname,
void *buffer, sizet bufsize);
projidt getprojidbyname(const char *name);
void setprojent(void);
void endprojent(void);
struct project *fgetprojent(FILE *f, struct project *proj,
void *buffer, sizet bufsize);
DESCRIPTION
These functions are used to obtain entries describing user
projects. Entries can come from any of the sources for a
project specified in the /etc/nsswitch.conf file (see
nsswitch.conf(4)).
The setprojent(), getprojent(), and endprojent() functions
are used to enumerate project entries from the database.
SunOS 5.11 Last change: 5 Apr 2004 1
Project Database Access Library Functions getprojent(3PROJECT)
The setprojent() function effectively rewinds the project
database to allow repeated searches. It sets (or resets) the
enumeration to the beginning of the set of project entries.
This function should be called before the first call to get-
projent().
The getprojent() function returns a pointer to a structure
containing the broken-out fields of an entry in the project
database. When first called, getprojent() returns a pointer
to a project structure containing the first project struc-
ture in the project database. Successive calls can be used
to read the entire database.
The endprojent() function closes the project database and
deallocates resources when processing is complete. It is
permissible, though possibly less efficient, for the process
to call more project functions after calling endprojent().
The getprojbyname() function searches the project database
for an entry with the project name specified by the charac-
ter string name.
The getprojbyid() function searches the project database for
an entry with the (numeric) project ID specified by projid.
The getdefaultproj() function first looks up the project key
word in the userattr database used to define user attri-
butes in restricted Solaris environments. If the database is
available and the keyword is present, the function looks up
the named project, returning NUL if it cannot be found or
if the user is not a member of the named project. If absent,
the function looks for a match in the project database for
the special project user.username. If no match is found, or
if the user is excluded from project user.username, the
function looks at the default group entry of the passwd
database for the user, and looks for a match in the project
database for the special name group.groupname, where group-
name is the default group associated with the password entry
corresponding to the given username. If no match is found,
or if the user is excluded from project group.groupname, the
function returns NUL. A special project entry called
'default' can be looked up and used as a last resort, unless
the user is excluded from project 'default'. On successful
lookup, this function returns a pointer to the valid project
structure. By convention, the user must have a default pro-
ject defined on a system to be able to log on to that sys-
tem.
SunOS 5.11 Last change: 5 Apr 2004 2
Project Database Access Library Functions getprojent(3PROJECT)
The inproj() function checks if the user specified by user-
name is able to use the project specified by projname. This
function returns 1 if the user belongs to the list of
project's users, if there is a project's group that contains
the specified user, if project is a user's default project,
or if project's user or group list contains "*" wildcard.
In all other cases it returns 0.
The getprojidbyname() function searches the project database
for an entry with the project name specified by the charac-
ter string name. This function returns the project ID if the
requested entry is found; otherwise it returns -1.
The fgetprojent() function, unlike the other functions
described above, does not use nsswitch.conf; it reads and
parses the next line from the stream f, which is assumed to
have the format of the project(4) file. This function
returns the same values as getprojent().
The getprojent(), getprojbyname(), getprojbyid(), getde-
faultproj(), and inproj() functions are reentrant interfaces
for operations with the project database. These functions
use buffers supplied by the caller to store returned results
and are safe for use in both single-threaded and mul-
tithreaded applications.
Reentrant interfaces require the additional arguments proj,
buffer, and bufsize. The proj argument must be a pointer to
a struct project structure allocated by the caller. On suc-
cessful completion, the function returns the project entry
in this structure. Storage referenced by the project struc-
ture is allocated from the memory provided with the buffer
argument, which is bufsize bytes in size. The content of
the memory buffer could be lost in cases when these func-
tions return errors.
For enumeration in multithreaded applications, the position
within the enumeration is a process-wide property shared by
all threads. The setprojent() function can be used in a mul-
tithreaded application but resets the enumeration position
for all threads. If multiple threads interleave calls to
getprojent(), the threads will enumerate disjoint subsets of
the project database. The inproj(), getprojbyname(), get-
projbyid(), and getdefaultproj() functions leave the
enumeration position in an indeterminate state.
SunOS 5.11 Last change: 5 Apr 2004 3
Project Database Access Library Functions getprojent(3PROJECT)
RETURN VALUES
Project entries are represented by the struct project struc-
ture defined in .
struct project {
char *pjname; /* name of the project */
projidt pjprojid; /* numerical project id */
char *pjcomment; /* project comment */
char **pjusers; /* vector of pointers to
project user names */
char **pjgroups; /* vector of pointers to
project group names */
char *pjattr; /* project attributes */
};
The getprojbyname() and getprojbyid() functions each return
a pointer to a struct project if they successfully locate
the requested entry; otherwise they return NUL.
The getprojent() function returns a pointer to a struct pro-
ject if it successfully enumerates an entry; otherwise it
returns NUL, indicating the end of the enumeration.
The getprojidbyname() function returns the project ID if the
requsted entry is found; otherwise it returns -1 and sets
errno to indicate the error.
When the pointer returned by the reentrant functions get-
projbyname(), getprojbyid(), and getprojent() is non-null,
it is always equal to the proj pointer that was supplied by
the caller.
Upon failure, NUL is returned and errno is set to indicate
the error.
ERORS
The getprojent(), getprojbyname(), getprojbyid(), inproj(),
getprojidbyname(), fgetprojent(), and getdefaultproj() func-
tions will fail if:
EINTR A signal was caught during the operation.
EIO An I/O error has occurred.
SunOS 5.11 Last change: 5 Apr 2004 4
Project Database Access Library Functions getprojent(3PROJECT)
EMFILE There are OPENMAX file descriptors currently open
in the calling process.
ENFILE The maximum allowable number of files is currently
open in the system.
ERANGE Insufficient storage was supplied by buffer and
bufsize to contain the data to be referenced by
the resulting project structure.
These functions can also fail if the name service switch
does not specify valid project(4) name service sources. In
the case of an incompletely configurated name service switch
configuration, getprojbyid() and other functions can return
error values other than those documented above. These condi-
tions usually occur when the nsswitch.conf file indicates
that one or more name services is providing entries for the
project database when that name service does not actually
make a project table available.
USAGE
When compiling multithreaded applications, see Intro(3),
Notes On Multithreaded Applications.
Use of the enumeration interface getprojent() is
discouraged. Enumeration is supported for the project file,
NIS, and LDAP but in general is not efficient. The semantics
of enumeration are discussed further in nsswitch.conf(4).
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Evolving
MT-Level See Description.
SEE ALSO
Intro(3), libproject(3LIB), projectwalk(3PROJECT),
sysconf(3C), nsswitch.conf(4), project(4), attributes(5)
SunOS 5.11 Last change: 5 Apr 2004 5
|
