usr/src/man/man3contract/ct_ctl_adopt.3contract

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH CT_CTL_ADOPT 3CONTRACT "Aug 9, 2007"
   7 .SH NAME
   8 ct_ctl_adopt, ct_ctl_abandon, ct_ctl_newct, ct_ctl_ack, ct_ctl_nack,
   9 ct_ctl_qack \- common contract control functions
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-D_LARGEFILE64_SOURCE\fR \fB -lcontract \fR [ \fIlibrary\fR\&.\|.\|. ]
  14 #include <libcontract.h>
  15
  16 \fBint\fR \fBct_ctl_adopt\fR(\fBint\fR \fIfd\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fBct_ctl_abandon\fR(\fBint\fR \fIfd\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBct_ctl_newct\fR(\fBint\fR \fIfd\fR, \fBuint64_t\fR \fIevid\fR, \fBint\fR \fItemplatefd\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBint\fR \fBct_ctl_ack\fR(\fBint\fR \fIfd\fR, \fBuint64_t\fR \fIevid\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBint\fR \fBct_ctl_nack\fR(\fBint\fR \fIfd\fR, \fBuint64_t\fR \fIevid\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBint\fR \fBct_ctl_qack\fR(\fBint\fR \fIfd\fR, \fBuint64_t\fR \fIevid\fR);
  42 .fi
  43
  44 .SH DESCRIPTION
  45 .sp
  46 .LP
  47 These functions operate on contract control file descriptors obtained from the
  48 \fBcontract\fR(4) file system.
  49 .sp
  50 .LP
  51 The \fBct_ctl_adopt()\fR function adopts the contract referenced by the file
  52 descriptor \fIfd\fR. After a successful call to \fBct_ctl_adopt()\fR, the
  53 contract is owned by the calling process and any events in that contract's
  54 event queue are appended to the process's bundle of the appropriate type.
  55 .sp
  56 .LP
  57 The \fBct_ctl_abandon()\fR function abandons the contract referenced by the
  58 file descriptor \fIfd\fR. After a successful call to \fBct_ctl_abandon()\fR the
  59 process no longer owns the contract, any events sent by that contract are
  60 automatically removed from the process's bundle, and any critical events on the
  61 contract's event queue are automatically acknowledged. Depending on its type
  62 and terms, the contract will either be orphaned or destroyed.
  63 .sp
  64 .LP
  65 The \fBct_ctl_ack()\fR function acknowledges the critical event specified
  66 by\fIevid\fR. If the event corresponds to an exit negotiation,
  67 \fBct_ctl_ack()\fR also indicates that the caller is prepared for the system to
  68 proceed with the referenced reconfiguration.
  69 .sp
  70 .LP
  71 The \fBct_ctl_nack()\fR function acknowledges the critical negotiation event
  72 specified by \fIevid\fR.  The \fBct_ctl_nack()\fR function also indicates that
  73 the caller wishes to block the proposed reconfiguration indicated by event
  74 \fIevid\fR. Depending on the contract type, this function might require certain
  75 privileges to be asserted in the process's effective set. This function will
  76 fail and return an error if the event represented by \fIevid\fR is not a
  77 negotiation event.
  78 .sp
  79 .LP
  80 The \fBct_ctl_qack()\fR function requests a new quantum of time for the
  81 negotiation specified by the event ID \fIevid\fR.
  82 .sp
  83 .LP
  84 The \fBct_ctl_newct()\fR function instructs the contract specified by the file
  85 descriptor \fIfd\fR that when the current exit negotiation completes, another
  86 contract with the terms provided by the template specified by \fItemplatefd\fR
  87 should be automatically written.
  88 .SH RETURN VALUES
  89 .sp
  90 .LP
  91 Upon successful completion, \fBct_ctl_adopt()\fR, \fBct_ctl_abandon()\fR,
  92 \fBct_ctl_newct()\fR, \fBct_ctl_ack()\fR, and \fBct_ctl_qack()\fR return 0.
  93 Otherwise, they return a non-zero error value.
  94 .SH ERRORS
  95 .sp
  96 .LP
  97 The \fBct_ctl_adopt()\fR function will fail if:
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBEBUSY\fR\fR
 102 .ad
 103 .RS 10n
 104 The contract is in the owned state.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBEINVAL\fR\fR
 111 .ad
 112 .RS 10n
 113 The contract was not inherited by the caller's process contract or was created
 114 by a process in a different zone.
 115 .RE
 116
 117 .sp
 118 .LP
 119 The \fBct_ctl_abandon()\fR, \fBct_ctl_newct()\fR, \fBct_ctl_ack()\fR,
 120 \fBct_ctl_nack()\fR, and \fBct_ctl_qack()\fR functions will fail if:
 121 .sp
 122 .ne 2
 123 .na
 124 \fB\fBEBUSY\fR\fR
 125 .ad
 126 .RS 9n
 127 The contract does not belong to the calling process.
 128 .RE
 129
 130 .sp
 131 .LP
 132 The \fBct_ctl_newct()\fR and \fBct_ctl_qack()\fR functions will fail if:
 133 .sp
 134 .ne 2
 135 .na
 136 \fB\fBESRCH\fR\fR
 137 .ad
 138 .RS 9n
 139 The event ID specified by \fIevid\fR does not correspond to an unacknowledged
 140 negotiation event.
 141 .RE
 142
 143 .sp
 144 .LP
 145 The \fBct_ctl_newct()\fR function will fail if:
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBEINVAL\fR\fR
 150 .ad
 151 .RS 10n
 152 The file descriptor specified by \fIfd\fR was not a valid template file
 153 descriptor.
 154 .RE
 155
 156 .sp
 157 .LP
 158 The \fBct_ctl_ack()\fR and \fBct_ctl_nack()\fR functions will fail if:
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fBESRCH\fR\fR
 163 .ad
 164 .RS 9n
 165 The event ID specified by \fIevid\fR does not correspond to an unacknowledged
 166 negotiation event.
 167 .RE
 168
 169 .sp
 170 .LP
 171 The \fBct_ctl_nack()\fR function will fail if:
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBEPERM\fR\fR
 176 .ad
 177 .RS 9n
 178 The calling process lacks the appropriate privileges required to block the
 179 reconfiguration.
 180 .RE
 181
 182 .sp
 183 .LP
 184 The \fBct_ctl_qack()\fR function will fail if:
 185 .sp
 186 .ne 2
 187 .na
 188 \fB\fBERANGE\fR\fR
 189 .ad
 190 .RS 10n
 191 The maximum amount of time has been requested.
 192 .RE
 193
 194 .SH ATTRIBUTES
 195 .sp
 196 .LP
 197 See \fBattributes\fR(5) for descriptions of the following attributes:
 198 .sp
 199
 200 .sp
 201 .TS
 202 box;
 203 c | c
 204 l | l .
 205 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 206 _
 207 Interface Stability     Committed
 208 _
 209 MT-Level        Safe
 210 .TE
 211
 212 .SH SEE ALSO
 213 .sp
 214 .LP
 215 \fBlibcontract\fR(3LIB), \fBcontract\fR(4), \fBattributes\fR(5),
 216 \fBlfcompile\fR(5)