1502 Remove conversion cruft from manpages

[unleashed.git] / usr / src / man / man4 / project.4

'\" te
.\"  Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (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]
.TH PROJECT 4 "May 9, 2005"
.SH NAME
project \- project file
.SH DESCRIPTION
.sp
.LP
The \fBproject\fR file is a local source of project information. The
\fBproject\fR file can be used in conjunction with other project sources,
including the \fBNIS\fR maps \fBproject.byname\fR and \fBproject.bynumber\fR
and the \fBLDAP\fR database \fBproject\fR. Programs use the
\fBgetprojent\fR(3PROJECT) routines to access this information.
.sp
.LP
The \fBproject\fR file contains a one-line entry for each project recognized by
the system, of the form:
.sp
.in +2
.nf
\fIprojname\fR:\fIprojid\fR:\fIcomment\fR:\fIuser-list\fR:\fIgroup-list\fR:\fIattributes\fR
.fi
.in -2

.sp
.LP
where the fields are defined as:
.sp
.ne 2
.na
\fB\fIprojname\fR\fR
.ad
.RS 14n
The name of the project. The name must be a string that consists of
alphanumeric characters, underline (_) characters, hyphens (-), and periods
(.). The period, which is reserved for projects with special meaning to the
operating system, can be used only in the names of default projects for users.
\fIprojname\fR cannot contain colons (:) or newline characters.
.RE

.sp
.ne 2
.na
\fB\fIprojid\fR\fR
.ad
.RS 14n
The project's unique numerical \fBID\fR (\fBPROJID\fR) within the system. The
maximum value of the \fIprojid\fR field is \fBMAXPROJID\fR. Project IDs below
100 are reserved  for the use of the operating system.
.RE

.sp
.ne 2
.na
\fB\fIcomment\fR\fR
.ad
.RS 14n
The project's description.
.RE

.sp
.ne 2
.na
\fB\fIuser-list\fR\fR
.ad
.RS 14n
A comma-separated list of users allowed in the project. With the exception of
the special projects referred to below, an empty field indicates no users are
allowed. See note about the use of wildcards below.
.RE

.sp
.ne 2
.na
\fB\fIgroup-list\fR\fR
.ad
.RS 14n
A comma-separated list of groups of users allowed in the project. With the
exception of the special projects referred to below, an empty field indicates
no groups are allowed. See note about the use of wildcards below.
.RE

.sp
.ne 2
.na
\fB\fIattributes\fR\fR
.ad
.RS 14n
A semicolon-separated list of name value pairs. Each pair has the following
format:
.sp
\fIname\fR[=\fIvalue\fR]
.sp
where \fIname\fR is the arbitrary string specifying the key's name and
\fIvalue\fR is the optional key value. An explanation of the valid name-value
pair syntax is provided in the \fBUSAGE\fR section of this page. The expected
most frequent use of the attribute field is for the specification of resource
controls. See \fBresource_controls\fR(5) for a description of the resource
controls supported in the current release of the Solaris operating system. You
can also use the attribute field for resource caps (see \fBrcapd\fR(1M)) and
for the \fBproject.pool\fR attribute (see \fBsetproject\fR(3PROJECT)).
.RE

.sp
.LP
Null entries (empty fields) in the \fIuser-list\fR and \fIgroup-list\fR fields,
which normally mean "no users" and "no groups", respectively, have a different
meaning in the entries for three special projects, \fBuser.\fIusername\fR\fR,
\fBgroup.\fIgroupname\fR\fR, and \fBdefault\fR. See \fBgetprojent\fR(3PROJECT)
for a description of these projects.
.sp
.LP
Wildcards can be used in user-list and group-list fields of the project
database entry. The asterisk (\fB*\fR), allows all users or groups to join the
project. The exclamation mark followed by the asterisk (\fB!*\fR), excludes all
users or groups from the project. The exclamation mark (\fB!\fR) followed by a
username or groupname excludes the specified user or group from the project.
See EXAMPLES, below.
.sp
.LP
Malformed entries cause routines that read this file to halt, in which case
project assignments specified further along are never made. Blank lines are
treated as malformed entries in the \fBproject\fR file, and cause
\fBgetprojent\fR(3PROJECT) and derived interfaces to fail.
.SH EXAMPLES
.LP
\fBExample 1 \fRSample \fBproject\fR File
.sp
.LP
The following is a sample \fBproject\fR file:

.sp
.in +2
.nf
system:0:System:::
user.root:1:Super-User:::
noproject:2:No Project:::
default:3::::
group.staff:10::::
beatles:100:The Beatles:john,paul,george,ringo::task.max-lwps=
    (privileged,100,signal=SIGTERM),(privileged,110,deny);
    process.max-file-descriptor
.fi
.in -2

.sp
.LP
Note that the two line breaks in the line that begins with \fBbeatles\fR are
not valid in a \fBproject\fR file. They are shown here only to allow the
example to display on a printed or displayed page. Each entry must be on one
and only one line.

.sp
.LP
An example project entry for \fBnsswitch.conf\fR(4) is:

.sp
.in +2
.nf
project: files nis
.fi
.in -2

.sp
.LP
With these entries, the project \fBbeatles\fR will have members \fBjohn\fR,
\fBpaul\fR, \fBgeorge\fR, and \fBringo\fR, and all projects listed in the
\fBNIS\fR project table are effectively incorporated after the entry for
\fBbeatles\fR.

.sp
.LP
The \fBbeatles\fR project has two values set on the \fBtask.max-lwps\fR
resource control. When a task in the \fBbeatles\fR project requests (via one of
its member processes) its 100th and 110th LWPs, an action associated with the
encountered threshold triggers. Upon the request for the 100th LWP, the process
making the request is sent the signal \fBSIGTERM\fR and is granted the request
for an additional lightweight process (LWP). At this point, the threshold for
110 LWPs becomes the active threshold. When a request for the 110th LWP in the
task is made, the requesting process is denied the request--no LWP will be
created. Since the 110th LWP is never granted, the threshold remains active,
and all subsequent requests for an 110th LWP will fail. (If LWPs are given up,
then subsequent requests will succeed, unless they would take the total number
of LWPs across the task over 110.) The \fBprocess.max-file-descriptor\fR
resource control is given no values. This means that processes entering this
project will only have the system resource control value on this \fBrctl\fR.

.LP
\fBExample 2 \fRProject Entry with Wildcards
.sp
.LP
The following entries use wildcards:

.sp
.in +2
.nf
notroot:200:Shared Project:*,!root::
notused:300:Unused Project::!*:
.fi
.in -2
.sp

.sp
.LP
In this example, any user except "root" is a member of project "notroot". For
the project "notused", all groups are excluded.

.SH USAGE
.sp
.LP
The \fBproject\fR database offers a reasonably flexible attribute mechanism in
the final name-value pair field. Name-value pairs are separated from one
another with the semicolon (;) character. The name is in turn distinguished
from the (optional) value by the equals (=) character. The value field can
contain multiple values separated by the comma (,) character, with grouping
support (into further values lists) by parentheses. Each of these values can be
composed of the upper and lower case alphabetic characters, the digits '0'
through '9', and the punctuation characters hyphen (-), plus (+), period (.),
slash (/), and underscore (_). Example resource control value specifications
are provided in EXAMPLES, above, and in \fBresource_controls\fR(5) and
\fBgetprojent\fR(3PROJECT).
.SH SEE ALSO
.sp
.LP
\fBnewtask\fR(1), \fBprojects\fR(1), \fBprctl\fR(1),
\fBgetprojent\fR(3PROJECT), \fBsetrctl\fR(2), \fBunistd.h\fR(3HEAD),
\fBnsswitch.conf\fR(4), \fBresource_controls\fR(5)