xref: /titanic_44/usr/src/cmd/perl/contrib/Sun/Solaris/Project/pod/Project.pod (revision c227543f6890bd6f2054360ec1820bfef8132431)
1#
2# Copyright (c) 2002, 2003, Oracle and/or its affiliates. All rights reserved.
3#
4
5#
6# Sun::Solaris::Project documentation.
7#
8
9=head1 NAME
10
11Sun::Solaris::Project - Perl interface to Projects
12
13=head1 SYNOPSIS
14
15 use Sun::Solaris::Project qw(:ALL);
16 my $projid = getprojid();
17
18This module provides wrappers for the Project-related system calls and the
19C<libproject(3LIB)> library. Also provided are constants from the various
20Project-related headers.
21
22=head2 Constants
23
24C<MAXPROJID>, C< PROJNAME_MAX>, C<PROJF_PATH>, C<PROJECT_BUFSZ>,
25C<SETPROJ_ERR_TASK>, and C<SETPROJ_ERR_POOL>.
26
27=head2 Functions
28
29B<C<getprojid()>>
30
31This function returns the numeric project ID of the calling process or C<undef>
32if the underlying C<getprojid(2)> system call is unsuccessful.
33
34B<C<setproject($project, $user, $flags)>>
35
36If C<$user> is a member of the project specified by C<$project>,
37C<setproject()> creates a new task and associates the appropriate resource
38controls with the process, task, and project. This function returns 0 on
39success. If the the underlying task creation fails, C<SETPROJ_ERR_TASK> is
40returned. If pool assignment fails, C<SETPROJ_ERR_POOL> is returned. If any
41resource attribute assignments fail, an integer value corresponding to the
42offset of the failed attribute assignment in the project database is returned.
43See C<setproject(3PROJECT)>.
44
45B<C<activeprojects()>>
46
47This function returns a list of the currently active projects on the system.
48Each value in the list is the numeric ID of a currently active project.
49
50B<C<getprojent()>>
51
52This function returns the next entry from the project database. When called in
53a scalar context, C<getprojent()> returns only the name of the project. When
54called in a list context, C<getprojent()> returns a 6-element list consisting
55of:
56
57 ($name, $projid, $comment, \@users, \@groups, $attr)
58
59C<\@users> and C<\@groups> are returned as arrays containing the appropriate
60user or project lists. On end-of-file C<undef> is returned.
61
62B<C<setprojent()>>
63
64This function rewinds the project database to the beginning of the file.
65
66B<C<endprojent()>>
67
68This function closes the project database.
69
70B<C<getprojbyname($name)>>
71
72This function searches the project database for an entry with the specified
73name. It returns a 6-element list as returned by C<getprojent()> if the entry
74is found and C<undef> if it cannot be found.
75
76B<C<getprojbyid($id)>>
77
78This function searches the project database for an entry with the specified
79ID. It returns a 6-element list as returned by C<getprojent()> if the entry is
80found or C<undef> if it cannot be found.
81
82B<C<getdefaultproj($user)>>
83
84This function returns the default project entry for the specified user in the
85same format as C<getprojent()>. It returns C<undef> if the user cannot be
86found. See C<getdefaultproj(3PROJECT)> for information about the lookup
87process.
88
89B<C<fgetprojent($filehandle)>>
90
91This function returns the next project entry from C<$filehandle>, a Perl file
92handle that must refer to a previously opened file in C<project(4)> format.
93Return values are the same as for C<getprojent()>.
94
95B<C<inproj($user, $project)>>
96
97This function checks whether the specified user is able to use the project.
98This function returns C<true> if the user can use the project and C<false>
99otherwise. See C<inproj(3PROJECT)>.
100
101B<C<getprojidbyname($project)>>
102
103This function searches the project database for the specified project. It
104returns the project ID if the project is found and C<undef> if it is not found.
105
106=head2 Class methods
107
108None.
109
110=head2 Object methods
111
112None.
113
114=head2 Exports
115
116By default nothing is exported from this module. The following tags can be
117used to selectively import constants and functions defined in this module:
118
119 :SYSCALLS    getprojid()
120
121 :LIBCALLS    setproject(), activeprojects(), getprojent(), setprojent(),
122              endprojent(), getprojbyname(), getprojbyid(), getdefaultproj(),
123              fgetprojent(), inproj(), and getprojidbyname()
124
125 :CONSTANTS   MAXPROJID, PROJNAME_MAX, PROJF_PATH, PROJECT_BUFSZ,
126              SETPROJ_ERR_TASK, and SETPROJ_ERR_POOL
127
128 :ALL         :SYSCALLS, :LIBCALLS, and :CONSTANTS
129
130=head1 ATTRIBUTES
131
132See C<attributes(5)> for descriptions of the following attributes:
133
134  ___________________________________________________________
135 |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
136 |_____________________________|_____________________________|
137 | Availability                | CPAN (http://www.cpan.org)  |
138 |_____________________________|_____________________________|
139 | Interface Stability         | Evolving                    |
140 |_____________________________|_____________________________|
141
142=head1 SEE ALSO
143
144C<getprojid(2)>, C<getdefaultproj(3PROJECT)>, C<inproj(3PROJECT)>,
145C<libproject(3LIB)>, C<setproject(3PROJECT)>, C<project(4)>, C<attributes(5)>
146