path: root/usr/src/man/man5/contract.5

'\" te
.\" Copyright (c) 2004, 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 CONTRACT 5 "Nov 26, 2017"
.SH NAME
contract \- the contract file system
.SH SYNOPSIS
.LP
.nf
\fB/system/contract\fR
.fi

.SH DESCRIPTION
.LP
The \fB/system/contract\fR file system acts as the primary interface to the
contract subsystem. There is a subdirectory of \fB/system/contract\fR for each
available contract type.
.sp
.LP
\fB/system/contract\fR can be mounted on any mount point, in addition to the
standard \fB/system/contract\fR mount point, and can be mounted several places
at once. Such additional mounts are allowed in order to facilitate the
confinement of processes to subtrees of the file system using \fBchroot\fR(8)
and yet allow such processes to continue to use contract commands and
interfaces.
.sp
.LP
A combination of standard system calls (for example, \fBopen\fR(2),
\fBclose\fR(2), and \fBpoll\fR(2)) and calls to \fBlibcontract\fR(3LIB) access
\fB/system/contract\fR files.
.sp
.LP
Consumers of the contract file system must be large file aware. See
\fBlargefile\fR(7) and \fBlfcompile64\fR(7).
.SS "DIRECTORY STRUCTURE"
.LP
At the top level, the \fB/system/contract\fR directory contains subdirectories
named with each available contract type, and one special directory, \fBall\fR.
Each of these directories is world-readable and world-searchable.
.SS "STRUCTURE OF \fB/system/contract/\fItype\fR\fR"
.LP
Each \fB/system/contract/\fItype\fR\fR directory contains a fixed number of
files. It also contains a variable number of subdirectories corresponding to
existing contracts of type \fItype\fR and named with the decimal representation
of the contracts' IDs.
.sp
.LP
The following files are in a \fB/system/contract/\fItype\fR\fR directory:
.sp
.ne 2
.na
\fB\fBtemplate\fR\fR
.ad
.RS 12n
Opening this file returns a file descriptor for a new \fItype\fR contract
template.
.sp
You can use the following \fBlibcontract\fR(3LIB) calls on a template file
descriptor:
.sp
.in +2
.nf
>

 ct_tmpl_activate(3contract)
 ct_tmpl_clear(3contract)
 ct_tmpl_create(3contract)
.fi
.in -2
.sp

See TERMS for additional template functions.
.RE

.sp
.ne 2
.na
\fBlatest\fR
.ad
.RS 12n
Opening this file returns a file descriptor for the status file of the last
\fItype\fR contract written by the opening LWP. See \fBSTRUCTURE OF
/system/contract/\fItype\fR/\fIid\fR\fR. If the opening LWP has not created a
\fItype\fR contract, opening latest fails with \fBESRCH\fR.
.RE

.sp
.ne 2
.na
\fBbundle\fR
.ad
.RS 12n
Opening this file returns a file descriptor for an event endpoint which
receives events from all \fItype\fR contracts on the system. No privileges are
required to open a type bundle event endpoint. Events sent by contracts owned
and written by users other than the reader's effective user id are invisible,
that is, they are silently skipped, unless the reader has
\fB{PRIV_CONTRACT_OBSERVER}\fR in its effective set. See \fBEVENTS\fR.
.RE

.sp
.ne 2
.na
\fBpbundle\fR
.ad
.RS 12n
Opening this file returns a file descriptor for an event endpoint which
receives events from all \fItype\fR contracts held by the opening process. See
\fBEVENTS\fR.
.RE

.SS "STRUCTURE OF /system/contract/all"
.LP
The \fB/system/contract/all\fR directory contains a numerically named file for
each contract in the system. Each file is a symbolic link to the type-specific
directory for that contract, that is \fB/system/contract/all/\fIid\fR\fR points
to \fB/system/contract/\fItype\fR/\fIid\fR\fR.
.SS "STRUCTURE OF /system/contract/\fItype\fR/\fIid\fR"
.LP
Each \fB/system/contract/\fItype\fR/\fIid\fR\fR directory contains the
following files:
.sp
.ne 2
.na
\fBctl\fR
.ad
.RS 10n
Opening this file returns a file descriptor for contract \fIid\fR's control
file. The open fails if the opening process does not hold contract \fIid\fR and
the contract has not been inherited by the process contract of which the
opening process is a member. See \fBprocess\fR(5).
.sp
The following \fBlibcontract\fR(3LIB) calls can be made on a \fBctl\fR file
descriptor if the contract is owned by the caller:
.sp
.in +2
.nf
ct_ctl_abandon(3contract)
ct_ctl_newct(3contract)
ct_ctl_ack(3contract)
ct_ctl_qack(3contract)
.fi
.in -2
.sp

The following \fBlibcontract\fR(3LIB) call can be made on a ctl file descriptor
if the contract doesn't have an owner:
.sp
.in +2
.nf
ct_ctl_adopt(3contract)
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fBstatus\fR
.ad
.RS 10n
Opening this file returns a file descriptor for contract \fIid\fR's status
file. The following \fBlibcontract\fR(3LIB) calls can be made on a status file
descriptor:
.LP
.nf
ct_status_read(3contract)
.fi

 See STATUS.
.RE

.sp
.ne 2
.na
\fBevents\fR
.ad
.RS 10n
Opening this file returns a file descriptor for an event endpoint which
receives events from contract \fIid\fR. See \fBEVENTS\fR.
.sp
Only a process which has the same effective user ID as the process owning the
contract, the same effective user ID as the contract's author, or has
\fB{PRIV_CONTRACT_OBSERVER}\fR in its effective set can open the event endpoint
for a contract.
.RE

.SS "TERMS"
.LP
The following terms are defined for all contracts:
.sp
.ne 2
.na
\fBcookie\fR
.ad
.RS 25n
Specifies a 64-bit quantity that the contract author can use to identify the
contract. Use \fBct_tmpl_set_cookie\fR(3CONTRACT) to set this term.
.RE

.sp
.ne 2
.na
\fBinformative event set\fR
.ad
.RS 25n
Selects which events are delivered as informative events. Use
\fBct_tmpl_set_informative\fR(3CONTRACT) to set this term.
.RE

.sp
.ne 2
.na
\fBcritical event set\fR
.ad
.RS 25n
Selects which events are delivered as critical events. Use
\fBct_tmpl_set_critical\fR(3CONTRACT) to set this term.
.RE

.SS "STATUS"
.LP
A status object returned by \fBct_status_read\fR(3CONTRACT) contains the
following pieces of information:
.sp
.ne 2
.na
\fBcontract ID\fR
.ad
.sp .6
.RS 4n
The numeric ID of the contract. Use \fBct_status_get_id\fR(3CONTRACT) to obtain
this information.
.RE

.sp
.ne 2
.na
\fBcontract type\fR
.ad
.sp .6
.RS 4n
The type of the contract, specified as a string. Obtained using
\fBct_status_get_type\fR(3CONTRACT). The contract type is the same as its
subdirectory name under \fB/system/contract\fR.
.RE

.sp
.ne 2
.na
\fBcreator's zone ID\fR
.ad
.sp .6
.RS 4n
The zone ID of the process which created the contract. Obtained using
\fBct_status_get_zoneid\fR(3CONTRACT).
.RE

.sp
.ne 2
.na
\fBownership state\fR
.ad
.sp .6
.RS 4n
The state of the contract, specified as \fBCTS_OWNED\fR, \fBCTS_INHERITED\fR,
\fBCTS_ORPHAN\fR, or \fBCTS_DEAD\fR. Use \fBct_status_get_state\fR(3CONTRACT)
to obtain this information.
.RE

.sp
.ne 2
.na
\fBcontract holder\fR
.ad
.sp .6
.RS 4n
If the contract's state is \fBCTS_OWNED\fR, the ID of the process which owns
the contract. If the contract's state is \fBCTS_INHERITED\fR, the ID of the
contract which is acting as regent. If the contract's state is \fBCTS_ORPHAN\fR
or \fBCTS_DEAD\fR, this is undefined. Use \fBct_status_get_holder\fR(3CONTRACT)
to obtain this information.
.RE

.sp
.ne 2
.na
\fBnumber of critical events\fR
.ad
.sp .6
.RS 4n
The number of unacknowledged critical events pending on the contract's event
queue. Use \fBct_status_get_nevents\fR(3CONTRACT) to obtain this information.
.RE

.sp
.ne 2
.na
\fBnegotiation time\fR
.ad
.sp .6
.RS 4n
The time remaining before the current synchronous negotiation times out. Use
\fBct_status_get_ntime\fR(3CONTRACT) to obtain this information.
.RE

.sp
.ne 2
.na
\fBnegotiation quantum time\fR
.ad
.sp .6
.RS 4n
The time remaining before the current negotiation quantum runs out. Use
\fBct_status_get_qtime\fR(3CONTRACT) to obtain this information.
.RE

.sp
.ne 2
.na
\fBnegotiation event ID\fR
.ad
.sp .6
.RS 4n
The ID of the event which initiated the negotiation timeout. Use
\fBct_status_get_nevid\fR(3CONTRACT) to obtain this information.
.RE

.sp
.ne 2
.na
\fBcookie (term)\fR
.ad
.sp .6
.RS 4n
The contract's cookie term. Use \fBct_status_get_cookie\fR(3CONTRACT) to obtain
this information.
.RE

.sp
.ne 2
.na
\fBInformative event set (term)\fR
.ad
.sp .6
.RS 4n
The contract's informative event set. Use
\fBct_status_get_informative\fR(3CONTRACT) to obtain this information.
.RE

.sp
.ne 2
.na
\fBCritical event set (term)\fR
.ad
.sp .6
.RS 4n
The contract's critical event set. Use \fBct_status_get_critical\fR(3CONTRACT)
to obtain this information.
.RE

.SS "EVENTS"
.LP
All three event endpoints, \fB/system/contract/\fItype\fR/bundle\fR,
\fB/system/contract/\fItype\fR/pbundle\fR, and
\fB/system/contract/\fItype\fR/\fIid\fR/events\fR, are accessed in the same
manner.
.sp
.LP
The following \fBlibcontract\fR(3LIB) interfaces are used with an event
endpoint file descriptor:
.sp
.in +2
.nf
ct_event_read(3contract)
ct_event_read_critical(3contract)
ct_event_reset(3contract)
.fi
.in -2
.sp

.sp
.LP
To facilitate processes watching multiple event endpoints, it is possible to
poll(2) on event endpoints. When it is possible to receive on an endpoint file
descriptor, POLLIN is set for that descriptor.
.sp
.LP
An event object returned by \fBct_event_read\fR(3CONTRACT) contains the
following information:
.sp
.ne 2
.na
\fBcontract ID\fR
.ad
.RS 28n
The ID of the contract that generated the event. Use
\fBct_event_read\fR(3CONTRACT) to obtain this information.
.RE

.sp
.ne 2
.na
\fBevent ID\fR
.ad
.RS 28n
The ID of the contract event.Use \fBct_event_get_evid\fR(3CONTRACT).
.RE

.sp
.ne 2
.na
\fBflags\fR
.ad
.RS 28n
A bit vector possibly including \fBCT_ACK\fR and \fBCTE_INFO\fR. Use
\fBct_event_get_flags\fR(3CONTRACT) to obtain this information.
.RE

.sp
.ne 2
.na
\fBevent type\fR
.ad
.RS 28n
The type of event, equal to one of the constants specified in the contract
type's manual page or \fBCT_EV_NEGEND\fR. Use
\fBct_event_get_type\fR(3CONTRACT) to obtain this information.
.RE

.SS "EVENT TYPES"
.LP
The following event types are defined:
.sp
.ne 2
.na
\fB\fBCT_EV_NEGEND\fR\fR
.ad
.RS 16n
Some time after an exit negotiation is initiated, the \fBCT_EV_NEGEND\fR event
is sent. This indicates that the negotiation ended. This might be because the
operation was cancelled, or because the operation was successful. If
successful, and the owner requested that a new contract be written, this
contains the ID of that contract.
.sp
\fBCT_EV_NEGEND\fR cannot be included in a contract's informative or critical
event set. It is always delivered and always critical. If \fBCT_EV_NEGEND\fR
indicates that the operation was successful, no further events are sent. The
contract's owner should use \fBct_ctl_abandon\fR(3CONTRACT) to abandon the
contract.
.sp
A \fBCT_EV_NEGEND\fR event contains:
.sp
.ne 2
.na
\fBnegotiation ID\fR
.ad
.RS 19n
The ID of the negotiation which ended. Use \fBct_event_get_nevid\fR(3CONTRACT)
to obain this information.
.RE

.sp
.ne 2
.na
\fBnew contract ID\fR
.ad
.RS 19n
The ID of the newly created contract. This value is 0 if no contract was
created, or the ID of the existing contract if the operation was not completed.
Use \fBct_event_get_newct\fR(3CONTRACT) to obtain this information.
.RE

.RE

.SH FILES
.ne 2
.na
\fB\fB/system/contract\fR\fR
.ad
.sp .6
.RS 4n
List of all contract types
.RE

.sp
.ne 2
.na
\fB\fB/system/contract/all\fR\fR
.ad
.sp .6
.RS 4n
Directory of all contract IDs
.RE

.sp
.ne 2
.na
\fB\fB/system/contract/all/\fIid\fR\fR\fR
.ad
.sp .6
.RS 4n
Symbolic link to the type-specific directory of contract \fIid\fR
.RE

.sp
.ne 2
.na
\fB\fB/system/contract/\fItype\fR\fR\fR
.ad
.sp .6
.RS 4n
Specific type directory
.RE

.sp
.ne 2
.na
\fB\fB/system/contract/\fItype\fR/template\fR\fR
.ad
.sp .6
.RS 4n
Template for the contract type
.RE

.sp
.ne 2
.na
\fB\fB/system/contract/\fItype\fR/bundle\fR\fR
.ad
.sp .6
.RS 4n
Listening point for all contracts of that type
.RE

.sp
.ne 2
.na
\fB\fB/system/contract/\fItype\fR/pbundle\fR\fR
.ad
.sp .6
.RS 4n
Listening point for all contracts of that type for the opening process
.RE

.sp
.ne 2
.na
\fB\fB/system/contract/\fItype\fR /latest\fR\fR
.ad
.sp .6
.RS 4n
Status of most recent \fItype\fR contract created by the opening LWP
.RE

.sp
.ne 2
.na
\fB\fB/system/contract/\fItype\fR/\fIID\fR\fR\fR
.ad
.sp .6
.RS 4n
Directory for contract id
.RE

.sp
.ne 2
.na
\fB\fB/system/contract/\fItype\fR/\fIID\fR/events\fR\fR
.ad
.sp .6
.RS 4n
Listening point for contract id's events
.RE

.sp
.ne 2
.na
\fB\fB/system/contract/\fItype\fR/\fIID\fR/ctl\fR\fR
.ad
.sp .6
.RS 4n
Control file for contract ID
.RE

.sp
.ne 2
.na
\fB\fB/system/contract/\fItype\fR/\fIID\fR/status\fR\fR
.ad
.sp .6
.RS 4n
Status info for contract ID
.RE

.SH SEE ALSO
.LP
.BR ctrun (1),
.BR ctstat (1),
.BR ctwatch (1),
.BR close (2),
.BR ioctl (2),
.BR open (2),
.BR poll (2),
.BR ct_ctl_abandon (3CONTRACT),
.BR ct_event_get_evid (3CONTRACT),
.BR ct_event_get_flags (3CONTRACT),
.BR ct_event_get_nevid (3CONTRACT),
.BR ct_event_get_newct (3CONTRACT),
.BR ct_event_get_type (3CONTRACT),
.BR ct_event_read (3CONTRACT),
.BR ct_status_get_cookie (3CONTRACT),
.BR ct_status_get_critical (3CONTRACT),
.BR ct_status_get_holder (3CONTRACT),
.BR ct_status_get_id (3CONTRACT),
.BR ct_status_get_informative (3CONTRACT),
.BR ct_status_get_nevents (3CONTRACT),
.BR ct_status_get_nevid (3CONTRACT),
.BR ct_status_get_ntime (3CONTRACT),
.BR ct_status_get_qtime (3CONTRACT),
.BR ct_status_get_state (3CONTRACT),
.BR ct_status_get_type (3CONTRACT),
.BR ct_status_read (3CONTRACT),
.BR ct_tmpl_set_cookie (3CONTRACT),
.BR ct_tmpl_set_critical (3CONTRACT),
.BR ct_tmpl_set_informative (3CONTRACT),
.BR libcontract (3LIB),
.BR process (5),
.BR largefile (7),
.BR lfcompile (7),
.BR privileges (7),
.BR chroot (8)