contract - the contract file system
The /system/contract file system acts as the primary interface to the
contract subsystem. There is a subdirectory of /system/contract for
each available contract type.
/system/contract can be mounted on any mount point, in
addition to the standard /system/contract 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 chroot(8) and yet allow such processes to continue to use
contract commands and interfaces.
A combination of standard system calls (for example,
open(2), close(2), and poll(2)) and calls to
libcontract(3LIB) access /system/contract files.
Consumers of the contract file system must be large file aware.
See largefile(7) and lfcompile64(7).
At the top level, the /system/contract directory contains subdirectories
named with each available contract type, and one special directory,
all. Each of these directories is world-readable and world-searchable.
Each /system/contract/type directory contains a fixed number of
files. It also contains a variable number of subdirectories corresponding to
existing contracts of type type and named with the decimal
representation of the contracts' IDs.
The following files are in a /system/contract/type
directory:
template
Opening this file returns a file descriptor for a new
type contract template.
You can use the following libcontract(3LIB) calls on a
template file descriptor:
>
ct_tmpl_activate(3contract)
ct_tmpl_clear(3contract)
ct_tmpl_create(3contract)
See TERMS for additional template functions.
latest
Opening this file returns a file descriptor for the
status file of the last type contract written by the opening LWP. See
STRUCTURE OF /system/contract/type/id. If the
opening LWP has not created a type contract, opening latest fails with
ESRCH.
bundle
Opening this file returns a file descriptor for an event
endpoint which receives events from all type 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
{PRIV_CONTRACT_OBSERVER} in its effective set. See EVENTS.
pbundle
Opening this file returns a file descriptor for an event
endpoint which receives events from all type contracts held by the
opening process. See EVENTS.
The /system/contract/all 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 /system/contract/all/id
points to /system/contract/type/id.
Each /system/contract/type/id directory contains the
following files:
ctl
Opening this file returns a file descriptor for contract
id's control file. The open fails if the opening process does not hold
contract
id and the contract has not been inherited by the process
contract of which the opening process is a member. See
process(5).
The following libcontract(3LIB) calls can be made on a
ctl file descriptor if the contract is owned by the caller:
ct_ctl_abandon(3contract)
ct_ctl_newct(3contract)
ct_ctl_ack(3contract)
ct_ctl_qack(3contract)
The following libcontract(3LIB) call can be made on a ctl
file descriptor if the contract doesn't have an owner:
ct_ctl_adopt(3contract)
status
Opening this file returns a file descriptor for contract
id's status file. The following
libcontract(3LIB) calls can be
made on a status file descriptor:
ct_status_read(3contract)
See STATUS.
events
Opening this file returns a file descriptor for an event
endpoint which receives events from contract
id. See
EVENTS.
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 {PRIV_CONTRACT_OBSERVER} in its effective set can open the event
endpoint for a contract.
The following terms are defined for all contracts:
cookie
informative event set
critical event set
A status object returned by ct_status_read(3CONTRACT) contains the
following pieces of information:
contract ID
contract type
The type of the contract, specified as a string. Obtained
using
ct_status_get_type(3CONTRACT). The contract type is the same as
its subdirectory name under
/system/contract.
creator's zone ID
ownership state
The state of the contract, specified as
CTS_OWNED,
CTS_INHERITED,
CTS_ORPHAN, or
CTS_DEAD. Use
ct_status_get_state(3CONTRACT) to obtain this information.
contract holder
If the contract's state is
CTS_OWNED, the ID of
the process which owns the contract. If the contract's state is
CTS_INHERITED, the ID of the contract which is acting as regent. If the
contract's state is
CTS_ORPHAN or
CTS_DEAD, this is undefined.
Use
ct_status_get_holder(3CONTRACT) to obtain this information.
number of critical events
negotiation time
negotiation quantum time
negotiation event ID
cookie (term)
Informative event set (term)
Critical event set (term)
All three event endpoints, /system/contract/type/bundle,
/system/contract/type/pbundle, and
/system/contract/type/id/events, are accessed in the same
manner.
The following libcontract(3LIB) interfaces are used with an
event endpoint file descriptor:
ct_event_read(3contract)
ct_event_read_critical(3contract)
ct_event_reset(3contract)
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.
An event object returned by ct_event_read(3CONTRACT)
contains the following information:
contract ID
event ID
flags
event type
The type of event, equal to one of the constants
specified in the contract type's manual page or
CT_EV_NEGEND. Use
ct_event_get_type(3CONTRACT) to obtain this information.
The following event types are defined:
CT_EV_NEGEND
Some time after an exit negotiation is initiated, the
CT_EV_NEGEND 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.
CT_EV_NEGEND cannot be included in a contract's informative
or critical event set. It is always delivered and always critical. If
CT_EV_NEGEND indicates that the operation was successful, no further
events are sent. The contract's owner should use
ct_ctl_abandon(3CONTRACT) to abandon the contract.
A CT_EV_NEGEND event contains:
negotiation ID
new contract ID
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
ct_event_get_newct(3CONTRACT) to obtain this
information.
/system/contract
List of all contract types
/system/contract/all
Directory of all contract IDs
/system/contract/all/id
Symbolic link to the type-specific directory of contract
id
/system/contract/type
Specific type directory
/system/contract/type/template
Template for the contract type
/system/contract/type/bundle
Listening point for all contracts of that type
/system/contract/type/pbundle
Listening point for all contracts of that type for the
opening process
/system/contract/type /latest
Status of most recent type contract created by the
opening LWP
/system/contract/type/ID
Directory for contract id
/system/contract/type/ID/events
Listening point for contract id's events
/system/contract/type/ID/ctl
Control file for contract ID
/system/contract/type/ID/status
Status info for contract ID
ctrun(1), ctstat(1), ctwatch(1), close(2),
ioctl(2), open(2), poll(2),
ct_ctl_abandon(3CONTRACT), ct_event_get_evid(3CONTRACT),
ct_event_get_flags(3CONTRACT), ct_event_get_nevid(3CONTRACT),
ct_event_get_newct(3CONTRACT), ct_event_get_type(3CONTRACT),
ct_event_read(3CONTRACT), ct_status_get_cookie(3CONTRACT),
ct_status_get_critical(3CONTRACT),
ct_status_get_holder(3CONTRACT), ct_status_get_id(3CONTRACT),
ct_status_get_informative(3CONTRACT),
ct_status_get_nevents(3CONTRACT),
ct_status_get_nevid(3CONTRACT), ct_status_get_ntime(3CONTRACT),
ct_status_get_qtime(3CONTRACT), ct_status_get_state(3CONTRACT),
ct_status_get_type(3CONTRACT), ct_status_read(3CONTRACT),
ct_tmpl_set_cookie(3CONTRACT), ct_tmpl_set_critical(3CONTRACT),
ct_tmpl_set_informative(3CONTRACT), libcontract(3LIB),
process(5), largefile(7), lfcompile(7),
privileges(7), chroot(8)