CT_CTL_ADOPT(3CONTRACT) Contract Management Library Functions
NAME
ct_ctl_adopt, ct_ctl_abandon, ct_ctl_newct, ct_ctl_ack, ct_ctl_nack,
ct_ctl_qack - common contract control functions
SYNOPSIS
cc [
flag... ]
file...
-D_LARGEFILE64_SOURCE -lcontract [
library... ]
#include <libcontract.h>
int ct_ctl_adopt(
int fd);
int ct_ctl_abandon(
int fd);
int ct_ctl_newct(
int fd,
uint64_t evid,
int templatefd);
int ct_ctl_ack(
int fd,
uint64_t evid);
int ct_ctl_nack(
int fd,
uint64_t evid);
int ct_ctl_qack(
int fd,
uint64_t evid);
DESCRIPTION
These functions operate on contract control file descriptors obtained
from the
contract(5) file system.
The
ct_ctl_adopt() function adopts the contract referenced by the file
descriptor
fd. After a successful call to
ct_ctl_adopt(), the contract is
owned by the calling process and any events in that contract's event
queue are appended to the process's bundle of the appropriate type.
The
ct_ctl_abandon() function abandons the contract referenced by the
file descriptor
fd. After a successful call to
ct_ctl_abandon() the
process no longer owns the contract, any events sent by that contract are
automatically removed from the process's bundle, and any critical events
on the contract's event queue are automatically acknowledged. Depending
on its type and terms, the contract will either be orphaned or destroyed.
The
ct_ctl_ack() function acknowledges the critical event specified
by
evid. If the event corresponds to an exit negotiation,
ct_ctl_ack() also indicates that the caller is prepared for the system to proceed with
the referenced reconfiguration.
The
ct_ctl_nack() function acknowledges the critical negotiation event
specified by
evid. The
ct_ctl_nack() function also indicates that the
caller wishes to block the proposed reconfiguration indicated by event
evid. Depending on the contract type, this function might require certain
privileges to be asserted in the process's effective set. This function
will fail and return an error if the event represented by
evid is not a
negotiation event.
The
ct_ctl_qack() function requests a new quantum of time for the
negotiation specified by the event ID
evid.
The
ct_ctl_newct() function instructs the contract specified by the file
descriptor
fd that when the current exit negotiation completes, another
contract with the terms provided by the template specified by
templatefd should be automatically written.
RETURN VALUES
Upon successful completion,
ct_ctl_adopt(),
ct_ctl_abandon(),
ct_ctl_newct(),
ct_ctl_ack(), and
ct_ctl_qack() return 0. Otherwise,
they return a non-zero error value.
ERRORS
The
ct_ctl_adopt() function will fail if:
EBUSY The contract is in the owned state.
EINVAL The contract was not inherited by the caller's process contract
or was created by a process in a different zone.
The
ct_ctl_abandon(),
ct_ctl_newct(),
ct_ctl_ack(),
ct_ctl_nack(), and
ct_ctl_qack() functions will fail if:
EBUSY The contract does not belong to the calling process.
The
ct_ctl_newct() and
ct_ctl_qack() functions will fail if:
ESRCH The event ID specified by
evid does not correspond to an
unacknowledged negotiation event.
The
ct_ctl_newct() function will fail if:
EINVAL The file descriptor specified by
fd was not a valid template
file descriptor.
The
ct_ctl_ack() and
ct_ctl_nack() functions will fail if:
ESRCH The event ID specified by
evid does not correspond to an
unacknowledged negotiation event.
The
ct_ctl_nack() function will fail if:
EPERM The calling process lacks the appropriate privileges required to
block the reconfiguration.
The
ct_ctl_qack() function will fail if:
ERANGE The maximum amount of time has been requested.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+
SEE ALSO
libcontract(3LIB),
contract(5),
attributes(7),
lfcompile(7) August 9, 2007
CT_CTL_ADOPT(3CONTRACT)