contract(4) File Formats contract(4)NAMEcontract - the contract file system
SYNOPSIS
/system/contract
DESCRIPTION
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 facili‐
tate the confinement of processes to subtrees of the file system using
chroot(1M) 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(5) and lfcompile64(5).
DIRECTORY STRUCTURE
At the top level, the /system/contract directory contains subdirecto‐
ries named with each available contract type, and one special direc‐
tory, all. Each of these directories is world-readable and world-
searchable.
STRUCTURE OF /system/contract/type
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 representa‐
tion 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 con‐
tracts on the system. No privileges are required to
open a type bundle event endpoint. Events sent by con‐
tracts 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_CON‐
TRACT_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 con‐
tracts held by the opening process. See EVENTS.
STRUCTURE OF /system/contract/all
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/con‐
tract/all/id points to /system/contract/type/id.
STRUCTURE OF /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(4).
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 lib‐
contract(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.
TERMS
The following terms are defined for all contracts:
cookie
Specifies a 64-bit quantity that the contract author can use to
identify the contract. Use ct_tmpl_set_cookie(3CONTRACT) to set
this term.
informative event set
Selects which events are delivered as informative events. Use
ct_tmpl_set_informative(3CONTRACT) to set this term.
critical event set
Selects which events are delivered as critical events. Use
ct_tmpl_set_critical(3CONTRACT) to set this term.
STATUS
A status object returned by ct_status_read(3CONTRACT) contains the fol‐
lowing pieces of information:
contract ID
The numeric ID of the contract. Use ct_status_get_id(3CONTRACT) to
obtain this information.
contract type
The type of the contract, specifed 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
The zone ID of the process which created the contract. Obtained
using ct_status_get_zoneid(3CONTRACT).
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_sta‐
tus_get_holder(3CONTRACT) to obtain this information.
number of critical events
The number of unacknowledged critical events pending on the con‐
tract's event queue. Use ct_status_get_nevents(3CONTRACT) to obtain
this information.
negotiation time
The time remaining before the current synchronous negotiation times
out. Use ct_status_get_ntime(3CONTRACT) to obtain this information.
negotiation quantum time
The time remaining before the current negotiation quantum runs out.
Use ct_status_get_qtime(3CONTRACT) to obtain this information.
negotiation event ID
The ID of the event which initiated the negotiation timeout. Use
ct_status_get_nevid(3CONTRACT) to obtain this information.
cookie (term)
The contract's cookie term. Use ct_status_get_cookie(3CONTRACT) to
obtain this information.
Informative event set (term)
The contract's informative event set. Use ct_status_get_informa‐
tive(3CONTRACT) to obtain this information.
Critical event set (term)
The contract's critical event set. Use ct_status_get_critical(3CON‐
TRACT) to obtain this information.
EVENTS
All three event endpoints, /system/contract/type/bundle, /system/con‐
tract/type/pbundle, and /system/contract/type/id/events, are accessed
in the same manner.
The following libcontract(3LIB) interfaces are used with an event end‐
point file descriptor:
ct_event_read(3contract)ct_event_read_critical(3contract)ct_event_reset(3contract)ct_event_next(3contract)
To facilitate processes watching multiple event endpoints, it is possi‐
ble 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 fol‐
lowing information:
contract ID The ID of the contract that generated the
event. Use ct_event_get_ctid(3CONTRACT) to
obtain this information.
event ID The ID of the contract event.Use
ct_event_get_evid(3CONTRACT).
flags A bit vector possibly including CT_ACK and
CTE_INFO. Use ct_event_get_flags(3CONTRACT) to
obtain this information.
event type The type of event, equal to one of the con‐
stants specified in the contract type's manual
page or CT_EV_NEGEND. Use
ct_event_get_type(3CONTRACT) to obtain this
information.
EVENT TYPES
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 opera‐
tion 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 fur‐
ther events are sent. The contract's owner should use ct_ctl_aban‐
don(3CONTRACT) to abandon the contract.
A CT_EV_NEGEND event contains:
negotiation ID
The ID of the negotiation which ended. Use
ct_event_get_nevid(3CONTRACT) to obain this information.
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.
FILES
/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/templete
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
SEE ALSOctrun(1), ctstat(1), ctwatch(1), chroot(1M), close(2), ioctl(2),
open(2), poll(2), ct_ctl_abandon(3CONTRACT), ct_event_get_ctid(3CON‐
TRACT), 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_status_read(3CONTRACT)ct_sta‐
tus_get_cookie(3CONTRACT), ct_status_get_critical(3CONTRACT), ct_sta‐
tus_get_holder(3CONTRACT), ct_status_get_id(3CONTRACT), ct_sta‐
tus_get_informative(3CONTRACT), ct_status_get_nevid(3CONTRACT), ct_sta‐
tus_get_nevents(3CONTRACT), ct_status_get_ntime(3CONTRACT), ct_sta‐
tus_get_qtime(3CONTRACT), ct_status_get_state(3CONTRACT), ct_sta‐
tus_get_type(3CONTRACT), ct_tmpl_set_cookie(3CONTRACT),
ct_tmpl_set_critical(3CONTRACT), ct_tmpl_set_informative(3CONTRACT),
libcontract(3LIB), process(4), largefile(5), lfcompile(5), privi‐
leges(5)SunOS 5.10 11 Jul 2005 contract(4)
