Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
getprojent(3PROJECTProject Database Access Library Functiogetprojent(3PROJECT)

       getprojent, getprojbyname, getprojbyid, getdefaultproj, inproj, getpro-
       jidbyname, setprojent, endprojent, fgetprojent -	project	database entry

       cc [ flag... ] file... -lproject	[ library... ]
       #include	<project.h>

       struct  project	*getprojent(struct project *proj, void *buffer,	size_t

       struct project *getprojbyname(const char	*name, struct  project	*proj,
       void *buffer, size_t bufsize);

       struct project *getprojbyid(projid_t projid, struct project *proj, void
       *buffer,	size_t bufsize);

       struct project *getdefaultproj(const  char  *username,  struct  project
       *proj, void *buffer, size_t bufsize);

       int  inproj(const  char	*username, const char *projname, void *buffer,
       size_t bufsize);

       projid_t	getprojidbyname(const char *name);

       void setprojent(void);

       void endprojent(void);

       struct project *fgetprojent(FILE	*f, struct project *proj,  void	 *buf-
       fer, size_t bufsize);

       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.

       The setprojent()	function effectively rewinds the project  database  to
       allow repeated searches.	It sets	(or resets) the	enumeration to the be-
       ginning of the set of project entries. This function should  be	called
       before the first	call to	getprojent().

       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 contain-
       ing the first project structure 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	possi-
       bly  less efficient, for	the process to call more project functions af-
       ter calling endprojent().

       The getprojbyname() function searches the project database for an entry
       with the	project	name specified by the character	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 user_attr database used to define user attributes in	restricted So-
       laris environments. If the database is available	 and  the  keyword  is
       present,	 the function looks up the named project, returning NULL 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
       groupname is the	default	group associated with the password entry  cor-
       responding  to the given	username. If no	match is found,	or if the user
       is excluded from	project	group.groupname, the function returns NULL.  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 project  defined
       on a system to be able to log on	to that	system.

       The  inproj() function checks if	the user specified by username 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 en-
       try  with the project name specified by the character string name. This
       function	returns	the project ID if the requested	entry is found;	other-
       wise 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(), getdefaultproj(), 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
       multithreaded applications.

       Reentrant interfaces require the	additional arguments proj, buffer, and
       bufsize.	The proj argument must be a pointer to a struct	project	struc-
       ture allocated by the caller. On	successful  completion,	 the  function
       returns	the project entry in this structure. Storage referenced	by the
       project structure is allocated from the memory provided with the	buffer
       argument, which is bufsize bytes	in size.

       For  enumeration	in multithreaded applications, the position within the
       enumeration is a	process-wide property shared by	all threads. The  set-
       projent()  function  can	be used	in a multithreaded application but re-
       sets the	enumeration position for all threads. If multiple threads  in-
       terleave	 calls	to  getprojent(),  the threads will enumerate disjoint
       subsets of the project database.	The inproj(), getprojbyname(), getpro-
       jbyid(),	 and getdefaultproj() functions	leave the enumeration position
       in an indeterminate state.

       Project entries are represented by the struct project structure defined
       in <project.h>.

       struct project {
	 char	   *pj_name;	   /* name of the project */
	 projid_t  pj_projid;	   /* numerical	project	id */
	 char	   *pj_comment;	   /* project comment */
	 char	   **pj_users;	   /* vector of	pointers to project
				      user names */
	 char	   **pj_groups;	   /* vector of	pointers to project
				      group names */
	 char	   *pj_attr;	   /* 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 NULL.

       The  getprojent()  function returns a pointer to	a struct project if it
       successfully enumerates an entry; otherwise it returns NULL, 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

       When  the  pointer returned by the reentrant functions getprojbyname(),
       getprojbyid(), and getprojent() is non-null, it is always equal to  the
       proj pointer that was supplied by the caller.

       Upon failure, NULL is returned and errno	is set to indicate the error.

       The  getprojent(), getprojbyname(), getprojbyid(), inproj(), getprojid-
       byname(), fgetprojent(),	and getdefaultproj() functions will fail if:

       EINTR A signal was caught during	the operation.

       EIO   An	I/O error has occurred.

	     There are OPEN_MAX	file descriptors currently open	in the calling

	     The  maximum  allowable  number of	files is currently open	in the

	     Insufficient storage was supplied by buffer and bufsize  to  con-
	     tain  the	data  to be referenced by the resulting	project	struc-

       These functions can also	fail if	the name service switch	does not spec-
       ify  valid  project(4)  name  service sources. In the case of an	incom-
       pletely configurated name service switch	 configuration,	 getprojbyid()
       and other functions can return error values other than those documented
       above. These conditions usually occur when the nsswitch.conf file indi-
       cates  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.

       When  compiling multithreaded applications, see intro(3), Notes On Mul-
       tithreaded Applications.

       Applications that use the interfaces described on this manual page can-
       not  be linked statically, since	the implementations of these functions
       employ dynamic loading and linking of shared objects at runtime.

       Use of the enumeration interface	getprojent() is	discouraged.  Enumera-
       tion is supported for the project file, NIS, and	LDAP but in general is
       not efficient. The semantics of enumeration are	discussed  further  in

       See attributes(5) for descriptions of the following attributes:

       |     ATTRIBUTE	TYPE	    |	    ATTRIBUTE VALUE	   |
       |Interface Stability	    |Evolving			   |
       |MT-Level		    |See "Reentrant Interfaces"	in |
       |			    |Description		   |

       intro(3), sysconf(3C), nsswitch.conf(4),	project(4), attributes(5)

SunOS 5.9			  11 Dec 2001		  getprojent(3PROJECT)


Want to link to this manual page? Use this URL:

home | help