1#
2# Copyright 2005 Sun Microsystems, Inc.  All rights reserved.
3# Use is subject to license terms.
4#
5# CDDL HEADER START
6#
7# The contents of this file are subject to the terms of the
8# Common Development and Distribution License, Version 1.0 only
9# (the "License").  You may not use this file except in compliance
10# with the License.
11#
12# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
13# or http://www.opensolaris.org/os/licensing.
14# See the License for the specific language governing permissions
15# and limitations under the License.
16#
17# When distributing Covered Code, include this CDDL HEADER in each
18# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
19# If applicable, add the following below this CDDL HEADER, with the
20# fields enclosed by brackets "[]" replaced with your own identifying
21# information: Portions Copyright [yyyy] [name of copyright owner]
22#
23# CDDL HEADER END
24#
25#ident	"%Z%%M%	%I%	%E% SMI"
26#
27# Sun::Solaris::Project documentation.
28#
29
30=head1 NAME
31
32Sun::Solaris::Project - Perl interface to Projects
33
34=head1 SYNOPSIS
35
36 use Sun::Solaris::Project qw(:ALL);
37 my $projid = getprojid();
38
39This module provides wrappers for the Project-related system calls and the
40C<libproject(3LIB)> library. Also provided are constants from the various
41Project-related headers.
42
43=head2 Constants
44
45C<MAXPROJID>, C< PROJNAME_MAX>, C<PROJF_PATH>, C<PROJECT_BUFSZ>,
46C<SETPROJ_ERR_TASK>, and C<SETPROJ_ERR_POOL>.
47
48=head2 Functions
49
50B<C<getprojid()>>
51
52This function returns the numeric project ID of the calling process or C<undef>
53if the underlying C<getprojid(2)> system call is unsuccessful.
54
55B<C<setproject($project, $user, $flags)>>
56
57If C<$user> is a member of the project specified by C<$project>,
58C<setproject()> creates a new task and associates the appropriate resource
59controls with the process, task, and project. This function returns 0 on
60success. If the the underlying task creation fails, C<SETPROJ_ERR_TASK> is
61returned. If pool assignment fails, C<SETPROJ_ERR_POOL> is returned. If any
62resource attribute assignments fail, an integer value corresponding to the
63offset of the failed attribute assignment in the project database is returned.
64See C<setproject(3PROJECT)>.
65
66B<C<activeprojects()>>
67
68This function returns a list of the currently active projects on the system.
69Each value in the list is the numeric ID of a currently active project.
70
71B<C<getprojent()>>
72
73This function returns the next entry from the project database. When called in
74a scalar context, C<getprojent()> returns only the name of the project. When
75called in a list context, C<getprojent()> returns a 6-element list consisting
76of:
77
78 ($name, $projid, $comment, \@users, \@groups, $attr)
79
80C<\@users> and C<\@groups> are returned as arrays containing the appropriate
81user or project lists. On end-of-file C<undef> is returned.
82
83B<C<setprojent()>>
84
85This function rewinds the project database to the beginning of the file.
86
87B<C<endprojent()>>
88
89This function closes the project database.
90
91B<C<getprojbyname($name)>>
92
93This function searches the project database for an entry with the specified
94name. It returns a 6-element list as returned by C<getprojent()> if the entry
95is found and C<undef> if it cannot be found.
96
97B<C<getprojbyid($id)>>
98
99This function searches the project database for an entry with the specified
100ID. It returns a 6-element list as returned by C<getprojent()> if the entry is
101found or C<undef> if it cannot be found.
102
103B<C<getdefaultproj($user)>>
104
105This function returns the default project entry for the specified user in the
106same format as C<getprojent()>. It returns C<undef> if the user cannot be
107found. See C<getdefaultproj(3PROJECT)> for information about the lookup
108process.
109
110B<C<fgetprojent($filehandle)>>
111
112This function returns the next project entry from C<$filehandle>, a Perl file
113handle that must refer to a previously opened file in C<project(4)> format.
114Return values are the same as for C<getprojent()>.
115
116B<C<inproj($user, $project)>>
117
118This function checks whether the specified user is able to use the project.
119This function returns C<true> if the user can use the project and C<false>
120otherwise. See C<inproj(3PROJECT)>.
121
122B<C<getprojidbyname($project)>>
123
124This function searches the project database for the specified project. It
125returns the project ID if the project is found and C<undef> if it is not found.
126
127=head2 Class methods
128
129None.
130
131=head2 Object methods
132
133None.
134
135=head2 Exports
136
137By default nothing is exported from this module. The following tags can be
138used to selectively import constants and functions defined in this module:
139
140 :SYSCALLS    getprojid()
141
142 :LIBCALLS    setproject(), activeprojects(), getprojent(), setprojent(),
143              endprojent(), getprojbyname(), getprojbyid(), getdefaultproj(),
144              fgetprojent(), inproj(), and getprojidbyname()
145
146 :CONSTANTS   MAXPROJID, PROJNAME_MAX, PROJF_PATH, PROJECT_BUFSZ,
147              SETPROJ_ERR_TASK, and SETPROJ_ERR_POOL
148
149 :ALL         :SYSCALLS, :LIBCALLS, and :CONSTANTS
150
151=head1 ATTRIBUTES
152
153See C<attributes(5)> for descriptions of the following attributes:
154
155  ___________________________________________________________
156 |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
157 |_____________________________|_____________________________|
158 | Availability                | CPAN (http://www.cpan.org)  |
159 |_____________________________|_____________________________|
160 | Interface Stability         | Evolving                    |
161 |_____________________________|_____________________________|
162
163=head1 SEE ALSO
164
165C<getprojid(2)>, C<getdefaultproj(3PROJECT)>, C<inproj(3PROJECT)>,
166C<libproject(3LIB)>, C<setproject(3PROJECT)>, C<project(4)>, C<attributes(5)>
167