Tribblix: manual page: contract.5

CONTRACT(5) File Formats and Configurations CONTRACT(5)

NAME

contract - 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
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).

DIRECTORY STRUCTURE

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.

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 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.

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/contract/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(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.

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
following 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, 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

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_status_get_holder(3CONTRACT) to obtain this information.

number of critical events

The number of unacknowledged critical events pending on the
contract'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_informative(3CONTRACT) to obtain this information.

Critical event set (term)

The contract's critical event set. Use
ct_status_get_critical(3CONTRACT) to obtain this information.

EVENTS

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
The ID of the contract that generated the
event. Use ct_event_read(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
constants 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 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
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/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