share/man/man3contract/ct_pr_tmpl_set_transfer.3contract

   1 '\" te
   2 .\" Copyright (c) 2008, 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_PR_TMPL_SET_TRANSFER 3CONTRACT "Feb 25, 2008"
   7 .SH NAME
   8 ct_pr_tmpl_set_transfer, ct_pr_tmpl_set_fatal, ct_pr_tmpl_set_param,
   9 ct_pr_tmpl_set_svc_fmri, ct_pr_tmpl_set_svc_aux, ct_pr_tmpl_get_transfer,
  10 ct_pr_tmpl_get_fatal, ct_pr_tmpl_get_param, ct_pr_tmpl_get_svc_fmri,
  11 ct_pr_tmpl_get_svc_aux \- process contract template functions
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB -lcontract \fR [ \fIlibrary\fR\&.\|.\|. ]
  16 #include <libcontract.h>
  17 #include <sys/contract/process.h>
  18
  19 \fBint\fR \fBct_pr_tmpl_set_transfer\fR(\fBint\fR \fIfd\fR, \fBctid_t\fR \fIctid\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBct_pr_tmpl_set_fatal\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIevents\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBint\fR \fBct_pr_tmpl_set_param\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIparams\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBint\fR \fBct_pr_tmpl_set_svc_fmri\fR(\fBint\fR \fIfd\fR, \fBconst char *\fR\fIfmri\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBint\fR \fBct_pr_tmpl_set_svc_aux\fR(\fBint\fR \fIfd\fR, \fBconst char *\fR\fIaux\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fBint\fR \fBct_pr_tmpl_get_transfer\fR(\fBint\fR \fIfd\fR, \fBctid_t *\fR\fIctidp\fR);
  45 .fi
  46
  47 .LP
  48 .nf
  49 \fBint\fR \fBct_pr_tmpl_get_fatal\fR(\fBint\fR \fIfd\fR, \fBuint_t *\fR\fIeventsp\fR);
  50 .fi
  51
  52 .LP
  53 .nf
  54 \fBint\fR \fBct_pr_tmpl_get_param\fR(\fBint\fR \fIfd\fR, \fBuint_t *\fR\fIparamsp\fR);
  55 .fi
  56
  57 .LP
  58 .nf
  59 \fBint\fR \fBct_pr_tmpl_get_svc_fmri\fR(\fBint\fR \fIfd\fR, \fBchar *\fR\fIfmri\fR, \fBsize_t\fR \fIsize\fR);
  60 .fi
  61
  62 .LP
  63 .nf
  64 \fBint\fR \fBct_pr_tmpl_get_svc_aux\fR(\fBint\fR \fIfd\fR, \fBchar *\fR\fIaux\fR, \fBsize_t\fR \fIsize\fR);
  65 .fi
  66
  67 .SH DESCRIPTION
  68 .sp
  69 .LP
  70 These functions read and write process contract terms and operate on process
  71 contract template file descriptors obtained from the \fBcontract\fR(4) file
  72 system.
  73 .sp
  74 .LP
  75 The \fBct_pr_tmpl_set_transfer()\fR and \fBct_pr_tmpl_get_transfer()\fR
  76 functions write and read the transfer contract term. The value is the ID of an
  77 empty regent process contract owned by the caller whose inherited contracts are
  78 to be transferred to a newly created contract.
  79 .sp
  80 .LP
  81 The \fBct_pr_tmpl_set_fatal()\fR and \fBct_pr_tmpl_get_fatal()\fR functions
  82 write and read the fatal event set term. The value is a collection of bits as
  83 described in \fBprocess\fR(4).
  84 .sp
  85 .LP
  86 The \fBct_pr_tmpl_set_param()\fR and \fBct_pr_tmpl_get_param()\fR functions
  87 write and read the parameter set term. The value is a collection of bits as
  88 described in \fBprocess\fR(4).
  89 .sp
  90 .LP
  91 The \fBct_pr_tmpl_set_svc_fmri()\fR and  \fBct_pr_tmpl_get_svc_fmri()\fR
  92 functions write and read the service FMRI value of a process contract template.
  93 The \fBct_pr_tmpl_set_svc_fmri()\fR function requires the caller to have the
  94 {\fBPRIV_CONTRACT_IDENTITY\fR} privilege in its effective set.
  95 .sp
  96 .LP
  97 The \fBct_pr_tmpl_set_svc_aux()\fR and \fBct_pr_tmpl_get_svc_aux()\fR functions
  98 write and read the creator's auxiliary value of a process contract template.
  99 .SH RETURN VALUES
 100 .sp
 101 .LP
 102 Upon successful completion, \fBct_pr_tmpl_set_transfer()\fR,
 103 \fBct_pr_tmpl_set_fatal()\fR, \fBct_pr_tmpl_set_param()\fR,
 104 \fBct_pr_tmpl_set_svc_fmri()\fR, \fBct_pr_tmpl_set_svc_aux()\fR,
 105 \fBct_pr_tmpl_get_transfer()\fR, \fBct_pr_tmpl_get_fatal()\fR, and
 106 \fBct_pr_tmpl_get_param()\fR return 0. Otherwise, they return a non-zero error
 107 value.
 108 .sp
 109 .LP
 110 Upon successful completion, \fBct_pr_tmpl_get_svc_fmri()\fR and
 111 \fBct_pr_tmpl_get_svc_aux()\fR return the size required to store the value,
 112 which is the same value return by \fBstrcpy\fR(3C) + 1. Insufficient buffer
 113 size can be checked by:
 114 .sp
 115 .in +2
 116 .nf
 117 if (ct_pr_tmpl_get_svc_fmri(fd, fmri, size) > size)
 118         /* buffer is too small */
 119 .fi
 120 .in -2
 121
 122 .sp
 123 .LP
 124 Otherwise, \fBct_pr_tmpl_get_svc_fmri()\fR and  \fBct_pr_tmpl_get_svc_aux()\fR
 125 return -1 and set \fBerrno\fR to indicate the error.
 126 .SH ERRORS
 127 .sp
 128 .LP
 129 The \fBct_pr_tmpl_set_param()\fR, \fBct_pr_tmpl_set_svc_fmri()\fR,
 130 \fBct_pr_tmpl_set_svc_aux()\fR, \fBct_pr_tmpl_get_svc_fmri()\fR and
 131 \fBct_pr_tmpl_get_svc_aux()\fR functions will fail if:
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fBEINVAL\fR\fR
 136 .ad
 137 .RS 10n
 138 An invalid parameter was specified.
 139 .RE
 140
 141 .sp
 142 .LP
 143 The \fBct_pr_tmpl_set_fatal()\fR function will fail if:
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBEINVAL\fR\fR
 148 .ad
 149 .RS 10n
 150 An invalid event was specified.
 151 .RE
 152
 153 .sp
 154 .LP
 155 The \fBct_pr_tmpl_set_transfer()\fR function will fail if:
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fBESRCH\fR\fR
 160 .ad
 161 .RS 13n
 162 The ID specified by \fIctid\fR does not correspond to a process contract.
 163 .RE
 164
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fBEACCES\fR\fR
 169 .ad
 170 .RS 13n
 171 The ID specified by \fIctid\fR does not correspond to a process contract owned
 172 by the calling process.
 173 .RE
 174
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fBENOTEMPTY\fR\fR
 179 .ad
 180 .RS 13n
 181 The ID specified by \fIctid\fR does not correspond to an empty process
 182 contract.
 183 .RE
 184
 185 .sp
 186 .LP
 187 The \fBct_pr_tmpl_set_svc_fmri()\fR function will fail if:
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fBEPERM\fR\fR
 192 .ad
 193 .RS 9n
 194 The calling process does not have {\fBPRIV_CONTRACT_IDENTITY\fR} in its
 195 effective set.
 196 .RE
 197
 198 .SH EXAMPLES
 199 .LP
 200 \fBExample 1 \fRCreate and activate a process contract template.
 201 .sp
 202 .LP
 203 The following example opens a new template, makes hardware errors and signals
 204 fatal events, makes hardware errors critical events, and activates the
 205 template. It then forks a process in the new contract using the requested
 206 terms.
 207
 208 .sp
 209 .in +2
 210 .nf
 211 #include <libcontract.h>
 212 #include <fcntl.h>
 213 #include <unistd.h>
 214
 215 \&...
 216 int fd;
 217
 218 fd = open("/system/contract/process/template", O_RDWR);
 219 (void) ct_pr_tmpl_set_fatal(fd, CT_PR_EV_HWERR|CT_PR_EV_SIGNAL);
 220 (void) ct_tmpl_set_critical(fd, CT_PR_EV_HWERR);
 221 (void) ct_tmpl_activate(fd);
 222 close(fd);
 223
 224 if (fork()) {
 225         /* parent - owns new process contract */
 226         ...
 227 } else {
 228         /* child - in new process contract */
 229         ...
 230 }
 231 \&...
 232 .fi
 233 .in -2
 234
 235 .LP
 236 \fBExample 2 \fRClear the process contract template.
 237 .sp
 238 .LP
 239 The following example opens the template file and requests that the active
 240 template be cleared.
 241
 242 .sp
 243 .in +2
 244 .nf
 245 #include <libcontract.h>
 246 #include <fcntl.h>
 247
 248 \&...
 249 int fd;
 250
 251 fd = open("/system/contract/process/template", O_RDWR);
 252 (void) ct_tmpl_clear(fd);
 253 close(fd);
 254 \&...
 255 .fi
 256 .in -2
 257
 258 .SH ATTRIBUTES
 259 .sp
 260 .LP
 261 See \fBattributes\fR(5) for descriptions of the following attributes:
 262 .sp
 263
 264 .sp
 265 .TS
 266 box;
 267 c | c
 268 l | l .
 269 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 270 _
 271 Interface Stability     Committed
 272 _
 273 MT-Level        Safe
 274 .TE
 275
 276 .SH SEE ALSO
 277 .sp
 278 .LP
 279 \fBlibcontract\fR(3LIB), \fBstrcpy\fR(3C), \fBcontract\fR(4), \fBprocess\fR(4),
 280 \fBattributes\fR(5)