usr/src/cmd/perl/contrib/Sun/Solaris/Project/pod/Project.pod

   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
  11 Sun::Solaris::Project - Perl interface to Projects
  12
  13 =head1 SYNOPSIS
  14
  15  use Sun::Solaris::Project qw(:ALL);
  16  my $projid = getprojid();
  17
  18 This module provides wrappers for the Project-related system calls and the
  19 C<libproject(3LIB)> library. Also provided are constants from the various
  20 Project-related headers.
  21
  22 =head2 Constants
  23
  24 C<MAXPROJID>, C< PROJNAME_MAX>, C<PROJF_PATH>, C<PROJECT_BUFSZ>,
  25 C<SETPROJ_ERR_TASK>, and C<SETPROJ_ERR_POOL>.
  26
  27 =head2 Functions
  28
  29 B<C<getprojid()>>
  30
  31 This function returns the numeric project ID of the calling process or C<undef>
  32 if the underlying C<getprojid(2)> system call is unsuccessful.
  33
  34 B<C<setproject($project, $user, $flags)>>
  35
  36 If C<$user> is a member of the project specified by C<$project>,
  37 C<setproject()> creates a new task and associates the appropriate resource
  38 controls with the process, task, and project. This function returns 0 on
  39 success. If the the underlying task creation fails, C<SETPROJ_ERR_TASK> is
  40 returned. If pool assignment fails, C<SETPROJ_ERR_POOL> is returned. If any
  41 resource attribute assignments fail, an integer value corresponding to the
  42 offset of the failed attribute assignment in the project database is returned.
  43 See C<setproject(3PROJECT)>.
  44
  45 B<C<activeprojects()>>
  46
  47 This function returns a list of the currently active projects on the system.
  48 Each value in the list is the numeric ID of a currently active project.
  49
  50 B<C<getprojent()>>
  51
  52 This function returns the next entry from the project database. When called in
  53 a scalar context, C<getprojent()> returns only the name of the project. When
  54 called in a list context, C<getprojent()> returns a 6-element list consisting
  55 of:
  56
  57  ($name, $projid, $comment, \@users, \@groups, $attr)
  58
  59 C<\@users> and C<\@groups> are returned as arrays containing the appropriate
  60 user or project lists. On end-of-file C<undef> is returned.
  61
  62 B<C<setprojent()>>
  63
  64 This function rewinds the project database to the beginning of the file.
  65
  66 B<C<endprojent()>>
  67
  68 This function closes the project database.
  69
  70 B<C<getprojbyname($name)>>
  71
  72 This function searches the project database for an entry with the specified
  73 name. It returns a 6-element list as returned by C<getprojent()> if the entry
  74 is found and C<undef> if it cannot be found.
  75
  76 B<C<getprojbyid($id)>>
  77
  78 This function searches the project database for an entry with the specified
  79 ID. It returns a 6-element list as returned by C<getprojent()> if the entry is
  80 found or C<undef> if it cannot be found.
  81
  82 B<C<getdefaultproj($user)>>
  83
  84 This function returns the default project entry for the specified user in the
  85 same format as C<getprojent()>. It returns C<undef> if the user cannot be
  86 found. See C<getdefaultproj(3PROJECT)> for information about the lookup
  87 process.
  88
  89 B<C<fgetprojent($filehandle)>>
  90
  91 This function returns the next project entry from C<$filehandle>, a Perl file
  92 handle that must refer to a previously opened file in C<project(4)> format.
  93 Return values are the same as for C<getprojent()>.
  94
  95 B<C<inproj($user, $project)>>
  96
  97 This function checks whether the specified user is able to use the project.
  98 This function returns C<true> if the user can use the project and C<false>
  99 otherwise. See C<inproj(3PROJECT)>.
 100
 101 B<C<getprojidbyname($project)>>
 102
 103 This function searches the project database for the specified project. It
 104 returns the project ID if the project is found and C<undef> if it is not found.
 105
 106 =head2 Class methods
 107
 108 None.
 109
 110 =head2 Object methods
 111
 112 None.
 113
 114 =head2 Exports
 115
 116 By default nothing is exported from this module. The following tags can be
 117 used 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
 132 See 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
 144 C<getprojid(2)>, C<getdefaultproj(3PROJECT)>, C<inproj(3PROJECT)>,
 145 C<libproject(3LIB)>, C<setproject(3PROJECT)>, C<project(4)>, C<attributes(5)>