#

# Copyright 2005 Sun Microsystems, Inc. All rights reserved.

# Use is subject to license terms.

#

# CDDL HEADER START

#

# The contents of this file are subject to the terms of the

# Common Development and Distribution License, Version 1.0 only

# (the "License"). You may not use this file except in compliance

# with the License.

#

# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

# or http://www.opensolaris.org/os/licensing.

# See the License for the specific language governing permissions

# and limitations under the License.

#

# When distributing Covered Code, include this CDDL HEADER in each

# file and include the License file at usr/src/OPENSOLARIS.LICENSE.

# If applicable, add the following below this CDDL HEADER, with the

# fields enclosed by brackets "[]" replaced with your own identifying

# information: Portions Copyright [yyyy] [name of copyright owner]

#

# CDDL HEADER END

#

#ident "%Z%%M% %I% %E% SMI"

#

# Sun::Solaris::Project documentation.

#

=head1 NAME

Sun::Solaris::Project - Perl interface to Projects

=head1 SYNOPSIS

use Sun::Solaris::Project qw(:ALL);

my $projid = getprojid();

This module provides wrappers for the Project-related system calls and the

C<libproject(3LIB)> library. Also provided are constants from the various

Project-related headers.

=head2 Constants

C<MAXPROJID>, C< PROJNAME_MAX>, C<PROJF_PATH>, C<PROJECT_BUFSZ>,

C<SETPROJ_ERR_TASK>, and C<SETPROJ_ERR_POOL>.

=head2 Functions

B<C<getprojid()>>

This function returns the numeric project ID of the calling process or C<undef>

if the underlying C<getprojid(2)> system call is unsuccessful.

B<C<setproject($project, $user, $flags)>>

If C<$user> is a member of the project specified by C<$project>,

C<setproject()> creates a new task and associates the appropriate resource

controls with the process, task, and project. This function returns 0 on

success. If the the underlying task creation fails, C<SETPROJ_ERR_TASK> is

returned. If pool assignment fails, C<SETPROJ_ERR_POOL> is returned. If any

resource attribute assignments fail, an integer value corresponding to the

offset of the failed attribute assignment in the project database is returned.

See C<setproject(3PROJECT)>.

B<C<activeprojects()>>

This function returns a list of the currently active projects on the system.

Each value in the list is the numeric ID of a currently active project.

B<C<getprojent()>>

This function returns the next entry from the project database. When called in

a scalar context, C<getprojent()> returns only the name of the project. When

called in a list context, C<getprojent()> returns a 6-element list consisting

of:

($name, $projid, $comment, \@users, \@groups, $attr)

C<\@users> and C<\@groups> are returned as arrays containing the appropriate

user or project lists. On end-of-file C<undef> is returned.

B<C<setprojent()>>

This function rewinds the project database to the beginning of the file.

B<C<endprojent()>>

This function closes the project database.

B<C<getprojbyname($name)>>

This function searches the project database for an entry with the specified

name. It returns a 6-element list as returned by C<getprojent()> if the entry

is found and C<undef> if it cannot be found.

B<C<getprojbyid($id)>>

This function searches the project database for an entry with the specified

ID. It returns a 6-element list as returned by C<getprojent()> if the entry is

found or C<undef> if it cannot be found.

B<C<getdefaultproj($user)>>

This function returns the default project entry for the specified user in the

same format as C<getprojent()>. It returns C<undef> if the user cannot be

found. See C<getdefaultproj(3PROJECT)> for information about the lookup

process.

B<C<fgetprojent($filehandle)>>

This function returns the next project entry from C<$filehandle>, a Perl file

handle that must refer to a previously opened file in C<project(4)> format.

Return values are the same as for C<getprojent()>.

B<C<inproj($user, $project)>>

This function checks whether the specified user is able to use the project.

This function returns C<true> if the user can use the project and C<false>

otherwise. See C<inproj(3PROJECT)>.

B<C<getprojidbyname($project)>>

This function searches the project database for the specified project. It

returns the project ID if the project is found and C<undef> if it is not found.

=head2 Class methods

None.

=head2 Object methods

None.

=head2 Exports

By default nothing is exported from this module. The following tags can be

used to selectively import constants and functions defined in this module:

:SYSCALLS getprojid()

:LIBCALLS setproject(), activeprojects(), getprojent(), setprojent(),

endprojent(), getprojbyname(), getprojbyid(), getdefaultproj(),

fgetprojent(), inproj(), and getprojidbyname()

:CONSTANTS MAXPROJID, PROJNAME_MAX, PROJF_PATH, PROJECT_BUFSZ,

SETPROJ_ERR_TASK, and SETPROJ_ERR_POOL

:ALL :SYSCALLS, :LIBCALLS, and :CONSTANTS

=head1 ATTRIBUTES

See C<attributes(5)> for descriptions of the following attributes:

___________________________________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE |

|_____________________________|_____________________________|

| Availability | CPAN (http://www.cpan.org) |

|_____________________________|_____________________________|

| Interface Stability | Evolving |

|_____________________________|_____________________________|

=head1 SEE ALSO

C<getprojid(2)>, C<getdefaultproj(3PROJECT)>, C<inproj(3PROJECT)>,

C<libproject(3LIB)>, C<setproject(3PROJECT)>, C<project(4)>, C<attributes(5)>