File Formats contract(4)
NAME
contract - the contract file system
SYNOPSIS
/system/contract
DESCRIPTION
The /system/contract file system acts as the primary inter-
face 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 addi-
tion 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(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
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 subdirec-
tories 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 direc-
tory:
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:
SunOS 5.11 Last change: 11 Jul 2005 1
File Formats contract(4)
>
cttmplactivate(3contract)
cttmplclear(3contract)
cttmplcreate(3contract)
See TERMS for additional template functions.
latest Opening this file returns a file descriptor for
the status file of the last type contract writ-
ten 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
{PRIVCONTRACTOBSERVER} 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 con-
tract, 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 follow-
ing 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.
SunOS 5.11 Last change: 11 Jul 2005 2
File Formats contract(4)
See process(4).
The following libcontract(3LIB) calls can be made
on a ctl file descriptor if the contract is owned
by the caller:
ctctlabandon(3contract)
ctctlnewct(3contract)
ctctlack(3contract)
ctctlqack(3contract)
The following libcontract(3LIB) call can be made
on a ctl file descriptor if the contract doesn't
have an owner:
ctctladopt(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:
ctstatusread(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
{PRIVCONTRACTOBSERVER} 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
cttmplsetcookie(3CONTRACT) to
set this term.
SunOS 5.11 Last change: 11 Jul 2005 3
File Formats contract(4)
informative event set Selects which events are delivered
as informative events. Use
cttmplsetinformative(3CONTRACT)
to set this term.
critical event set Selects which events are delivered
as critical events. Use
cttmplsetcritical(3CONTRACT) to
set this term.
STATUS
A status object returned by ctstatusread(3CONTRACT) con-
tains the following pieces of information:
contract ID
The numeric ID of the contract. Use
ctstatusgetid(3CONTRACT) to obtain this information.
contract type
The type of the contract, specifed as a string. Obtained
using ctstatusgettype(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 ctstatusgetzoneid(3CONTRACT).
ownership state
The state of the contract, specified as CTSOWNED,
CTSINHERITED, CTSORPHAN, or CTSDEAD. Use
ctstatusgetstate(3CONTRACT) to obtain this informa-
tion.
contract holder
If the contract's state is CTSOWNED, the ID of the pro-
cess which owns the contract. If the contract's state is
CTSINHERITED, the ID of the contract which is acting as
regent. If the contract's state is CTSORPHAN or
CTSDEAD, this is undefined. Use
ctstatusgetholder(3CONTRACT) to obtain this
SunOS 5.11 Last change: 11 Jul 2005 4
File Formats contract(4)
information.
number of critical events
The number of unacknowledged critical events pending on
the contract's event queue. Use
ctstatusgetnevents(3CONTRACT) to obtain this informa-
tion.
negotiation time
The time remaining before the current synchronous nego-
tiation times out. Use ctstatusgetntime(3CONTRACT) to
obtain this information.
negotiation quantum time
The time remaining before the current negotiation quan-
tum runs out. Use ctstatusgetqtime(3CONTRACT) to
obtain this information.
negotiation event ID
The ID of the event which initiated the negotiation
timeout. Use ctstatusgetnevid(3CONTRACT) to obtain
this information.
cookie (term)
The contract's cookie term. Use
ctstatusgetcookie(3CONTRACT) to obtain this informa-
tion.
Informative event set (term)
The contract's informative event set. Use
ctstatusgetinformative(3CONTRACT) to obtain this
information.
Critical event set (term)
The contract's critical event set. Use
ctstatusgetcritical(3CONTRACT) to obtain this infor-
mation.
SunOS 5.11 Last change: 11 Jul 2005 5
File Formats contract(4)
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:
cteventread(3contract)
cteventreadcritical(3contract)
cteventreset(3contract)
cteventnext(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, POLIN
is set for that descriptor.
An event object returned by cteventread(3CONTRACT) con-
tains the following information:
contract ID The ID of the contract that gen-
erated the event. Use
cteventread(3CONTRACT) to
obtain this information.
event ID The ID of the contract event.Use
cteventgetevid(3CONTRACT).
flags A bit vector possibly including
CTACK and CTEINFO. Use
cteventgetflags(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 CTEVNEGEND. Use
cteventgettype(3CONTRACT) to
obtain this information.
SunOS 5.11 Last change: 11 Jul 2005 6
File Formats contract(4)
EVENT TYPES
The following event types are defined:
CTEVNEGEND Some time after an exit negotiation is ini-
tiated, the CTEVNEGEND event is sent. This
indicates that the negotiation ended. This
might be because the operation was can-
celled, or because the operation was suc-
cessful. If successful, and the owner
requested that a new contract be written,
this contains the ID of that contract.
CTEVNEGEND cannot be included in a
contract's informative or critical event
set. It is always delivered and always crit-
ical. If CTEVNEGEND indicates that the
operation was successful, no further events
are sent. The contract's owner should use
ctctlabandon(3CONTRACT) to abandon the
contract.
A CTEVNEGEND event contains:
negotiation ID The ID of the negotiation
which ended. Use
cteventgetnevid(3CONTRACT)
to obain this informa-
tion.
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
cteventgetnewct(3CONTRACT)
to obtain this informa-
tion.
FILES
/system/contract
List of all contract types
/system/contract/all
Directory of all contract IDs
SunOS 5.11 Last change: 11 Jul 2005 7
File Formats contract(4)
/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 open-
ing 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
SunOS 5.11 Last change: 11 Jul 2005 8
File Formats contract(4)
SEE ALSO
ctrun(1), ctstat(1), ctwatch(1), chroot(1M), close(2),
ioctl(2), open(2), poll(2), ctctlabandon(3CONTRACT),
cteventread(3CONTRACT), cteventgetevid(3CONTRACT),
cteventgetflags(3CONTRACT),
cteventgetnevid(3CONTRACT),
cteventgetnewct(3CONTRACT), cteventgettype(3CONTRACT),
ctstatusread(3CONTRACT)ctstatusgetcookie(3CONTRACT),
ctstatusgetcritical(3CONTRACT),
ctstatusgetholder(3CONTRACT),
ctstatusgetid(3CONTRACT),
ctstatusgetinformative(3CONTRACT),
ctstatusgetnevid(3CONTRACT),
ctstatusgetnevents(3CONTRACT),
ctstatusgetntime(3CONTRACT),
ctstatusgetqtime(3CONTRACT),
ctstatusgetstate(3CONTRACT),
ctstatusgettype(3CONTRACT),
cttmplsetcookie(3CONTRACT),
cttmplsetcritical(3CONTRACT),
cttmplsetinformative(3CONTRACT), libcontract(3LIB), pro-
cess(4), largefile(5), lfcompile(5), privileges(5)
SunOS 5.11 Last change: 11 Jul 2005 9
|
