share/man/man3contract/ct_tmpl_activate.3contract

   1 '\" te
   2 .\" Copyright (c) 2004, 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_TMPL_ACTIVATE 3CONTRACT "Apr 1, 2004"
   7 .SH NAME
   8 ct_tmpl_activate, ct_tmpl_clear, ct_tmpl_create, ct_tmpl_set_cookie,
   9 ct_tmpl_set_critical, ct_tmpl_set_informative, ct_tmpl_get_cookie,
  10 ct_tmpl_get_critical, ct_tmpl_get_informative \- common contract template
  11 functions
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB -lcontract \fR [ \fIlibrary\fR\&.\|.\|. ]
  16 #include <libcontract.h>
  17
  18 \fBint\fR \fBct_tmpl_activate\fR(\fBint\fR \fIfd\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBct_tmpl_clear\fR(\fBint\fR \fIfd\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBint\fR \fBct_tmpl_create\fR(\fBint\fR \fIfd\fR, \fBctid_t *\fR\fIidp\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBct_tmpl_set_cookie\fR(\fBint\fR \fIfd\fR, \fBuint64_t\fR \fIcookie\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBint\fR \fBct_tmpl_set_critical\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIevents\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBint\fR \fBct_tmpl_set_informative\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIevents\fR);
  44 .fi
  45
  46 .LP
  47 .nf
  48 \fBint\fR \fBct_tmpl_get_cookie\fR(\fBint\fR \fIfd\fR, \fBuint64_t *\fR\fIcookiep\fR);
  49 .fi
  50
  51 .LP
  52 .nf
  53 \fBint\fR \fBct_tmpl_get_critical\fR(\fBint\fR \fIfd\fR, \fBuint_t *\fR\fIeventsp\fR);
  54 .fi
  55
  56 .LP
  57 .nf
  58 \fBint\fR \fBct_tmpl_get_informative\fR(\fBint\fR \fIfd\fR, \fBuint_t *\fR\fIeventsp\fR);
  59 .fi
  60
  61 .SH DESCRIPTION
  62 .sp
  63 .LP
  64 These functions operate on contract template file descriptors obtained from the
  65 \fBcontract\fR(4) file system.
  66 .sp
  67 .LP
  68 The \fBct_tmpl_activate()\fR function makes the template referenced by the file
  69 descriptor \fIfd\fR the active template for the calling thread.
  70 .sp
  71 .LP
  72 The \fBct_tmpl_clear()\fR function clears calling thread's active template.
  73 .sp
  74 .LP
  75 The \fBct_tmpl_create()\fR function uses the template referenced by the file
  76 descriptor \fIfd\fR to create a new contract. If successful, the ID of the
  77 newly created contract is placed in *\fIidp\fR.
  78 .sp
  79 .LP
  80 The \fBct_tmpl_set_cookie()\fR and \fBct_tmpl_get_cookie()\fR functions write
  81 and read the cookie term of a contract template. The cookie term is ignored by
  82 the system, except to include its value in a resulting contract's status
  83 object. The default cookie term is 0.
  84 .sp
  85 .LP
  86 The \fBct_tmpl_set_critical()\fR and \fBct_tmpl_get_critical()\fR functions
  87 write and read the critical event set term. The value is a collection of bits
  88 as described in the contract type's manual page.
  89 .sp
  90 .LP
  91 The \fBct_tmpl_set_informative()\fR and \fBct_tmpl_get_informative()\fR
  92 functions write and read the informative event set term. The value is a
  93 collection of bits as described in the contract type's manual page.
  94 .SH RETURN VALUES
  95 .sp
  96 .LP
  97 Upon successful completion, \fBct_tmpl_activate()\fR, \fBct_tmpl_create()\fR,
  98 \fBct_tmpl_set_cookie()\fR, \fBct_tmpl_get_cookie()\fR,
  99 \fBct_tmpl_set_critical()\fR, \fBct_tmpl_get_critical()\fR,
 100 \fBct_tmpl_set_informative()\fR, and \fBct_tmpl_get_informative()\fR return 0.
 101 Otherwise, they return a non-zero error value.
 102 .SH ERRORS
 103 .sp
 104 .LP
 105 The \fBct_tmpl_create()\fR function will fail if:
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fBERANGE\fR\fR
 110 .ad
 111 .RS 10n
 112 The terms specified in the template were unsatisfied at the time of the call.
 113 .RE
 114
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fBEAGAIN\fR\fR
 119 .ad
 120 .RS 10n
 121 The \fIproject\fR.\fImax-contracts\fR resource control would have been
 122 exceeded.
 123 .RE
 124
 125 .sp
 126 .LP
 127 The \fBct_tmpl_set_critical()\fR and \fBct_tmpl_set_informative()\fR functions
 128 will fail if:
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fBEINVAL\fR\fR
 133 .ad
 134 .RS 10n
 135 An invalid event was specified.
 136 .RE
 137
 138 .sp
 139 .LP
 140 The \fBct_tmpl_set_critical()\fR function will fail if:
 141 .sp
 142 .ne 2
 143 .na
 144 \fB\fBEPERM\fR\fR
 145 .ad
 146 .RS 9n
 147 One of the specified events was disallowed given other contract terms (see
 148 \fBcontract\fR(4)) and {\fBPRIV_CONTRACT_EVENT\fR} was not in the effective set
 149 for the calling process.
 150 .RE
 151
 152 .SH ATTRIBUTES
 153 .sp
 154 .LP
 155 See \fBattributes\fR(5) for descriptions of the following attributes:
 156 .sp
 157
 158 .sp
 159 .TS
 160 box;
 161 c | c
 162 l | l .
 163 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 164 _
 165 Interface Stability     Evolving
 166 _
 167 MT-Level        Safe
 168 .TE
 169
 170 .SH SEE ALSO
 171 .sp
 172 .LP
 173 \fBlibcontract\fR(3LIB), \fBcontract\fR(4), \fBattributes\fR(5)