path: root/usr/src/man/man3contract/ct_ctl_adopt.3contract

'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH CT_CTL_ADOPT 3CONTRACT "Aug 9, 2007"
.SH NAME
ct_ctl_adopt, ct_ctl_abandon, ct_ctl_newct, ct_ctl_ack, ct_ctl_nack,
ct_ctl_qack \- common contract control functions
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-D_LARGEFILE64_SOURCE\fR \fB -lcontract \fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libcontract.h>

\fBint\fR \fBct_ctl_adopt\fR(\fBint\fR \fIfd\fR);
.fi

.LP
.nf
\fBint\fR \fBct_ctl_abandon\fR(\fBint\fR \fIfd\fR);
.fi

.LP
.nf
\fBint\fR \fBct_ctl_newct\fR(\fBint\fR \fIfd\fR, \fBuint64_t\fR \fIevid\fR, \fBint\fR \fItemplatefd\fR);
.fi

.LP
.nf
\fBint\fR \fBct_ctl_ack\fR(\fBint\fR \fIfd\fR, \fBuint64_t\fR \fIevid\fR);
.fi

.LP
.nf
\fBint\fR \fBct_ctl_nack\fR(\fBint\fR \fIfd\fR, \fBuint64_t\fR \fIevid\fR);
.fi

.LP
.nf
\fBint\fR \fBct_ctl_qack\fR(\fBint\fR \fIfd\fR, \fBuint64_t\fR \fIevid\fR);
.fi

.SH DESCRIPTION
.sp
.LP
These functions operate on contract control file descriptors obtained from the
\fBcontract\fR(4) file system.
.sp
.LP
The \fBct_ctl_adopt()\fR function adopts the contract referenced by the file
descriptor \fIfd\fR. After a successful call to \fBct_ctl_adopt()\fR, 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.
.sp
.LP
The \fBct_ctl_abandon()\fR function abandons the contract referenced by the
file descriptor \fIfd\fR. After a successful call to \fBct_ctl_abandon()\fR 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.
.sp
.LP
The \fBct_ctl_ack()\fR function acknowledges the critical event specified
by\fIevid\fR. If the event corresponds to an exit negotiation,
\fBct_ctl_ack()\fR also indicates that the caller is prepared for the system to
proceed with the referenced reconfiguration.
.sp
.LP
The \fBct_ctl_nack()\fR function acknowledges the critical negotiation event
specified by \fIevid\fR.  The \fBct_ctl_nack()\fR function also indicates that
the caller wishes to block the proposed reconfiguration indicated by event
\fIevid\fR. 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 \fIevid\fR is not a
negotiation event.
.sp
.LP
The \fBct_ctl_qack()\fR function requests a new quantum of time for the
negotiation specified by the event ID \fIevid\fR.
.sp
.LP
The \fBct_ctl_newct()\fR function instructs the contract specified by the file
descriptor \fIfd\fR that when the current exit negotiation completes, another
contract with the terms provided by the template specified by \fItemplatefd\fR
should be automatically written.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBct_ctl_adopt()\fR, \fBct_ctl_abandon()\fR,
\fBct_ctl_newct()\fR, \fBct_ctl_ack()\fR, and \fBct_ctl_qack()\fR return 0.
Otherwise, they return a non-zero error value.
.SH ERRORS
.sp
.LP
The \fBct_ctl_adopt()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEBUSY\fR\fR
.ad
.RS 10n
The contract is in the owned state.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The contract was not inherited by the caller's process contract or was created
by a process in a different zone.
.RE

.sp
.LP
The \fBct_ctl_abandon()\fR, \fBct_ctl_newct()\fR, \fBct_ctl_ack()\fR,
\fBct_ctl_nack()\fR, and \fBct_ctl_qack()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBEBUSY\fR\fR
.ad
.RS 9n
The contract does not belong to the calling process.
.RE

.sp
.LP
The \fBct_ctl_newct()\fR and \fBct_ctl_qack()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBESRCH\fR\fR
.ad
.RS 9n
The event ID specified by \fIevid\fR does not correspond to an unacknowledged
negotiation event.
.RE

.sp
.LP
The \fBct_ctl_newct()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The file descriptor specified by \fIfd\fR was not a valid template file
descriptor.
.RE

.sp
.LP
The \fBct_ctl_ack()\fR and \fBct_ctl_nack()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBESRCH\fR\fR
.ad
.RS 9n
The event ID specified by \fIevid\fR does not correspond to an unacknowledged
negotiation event.
.RE

.sp
.LP
The \fBct_ctl_nack()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEPERM\fR\fR
.ad
.RS 9n
The calling process lacks the appropriate privileges required to block the
reconfiguration.
.RE

.sp
.LP
The \fBct_ctl_qack()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBERANGE\fR\fR
.ad
.RS 10n
The maximum amount of time has been requested.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBlibcontract\fR(3LIB), \fBcontract\fR(4), \fBattributes\fR(5),
\fBlfcompile\fR(5)