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

'\" te
.\" Copyright (c) 2008, 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_PR_TMPL_SET_TRANSFER 3CONTRACT "Feb 25, 2008"
.SH NAME
ct_pr_tmpl_set_transfer, ct_pr_tmpl_set_fatal, ct_pr_tmpl_set_param,
ct_pr_tmpl_set_svc_fmri, ct_pr_tmpl_set_svc_aux, ct_pr_tmpl_get_transfer,
ct_pr_tmpl_get_fatal, ct_pr_tmpl_get_param, ct_pr_tmpl_get_svc_fmri,
ct_pr_tmpl_get_svc_aux \- process contract template functions
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-D_LARGEFILE64_SOURCE\fR \fB -lcontract \fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libcontract.h>
#include <sys/contract/process.h>

\fBint\fR \fBct_pr_tmpl_set_transfer\fR(\fBint\fR \fIfd\fR, \fBctid_t\fR \fIctid\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_tmpl_set_fatal\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIevents\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_tmpl_set_param\fR(\fBint\fR \fIfd\fR, \fBuint_t\fR \fIparams\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_tmpl_set_svc_fmri\fR(\fBint\fR \fIfd\fR, \fBconst char *\fR\fIfmri\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_tmpl_set_svc_aux\fR(\fBint\fR \fIfd\fR, \fBconst char *\fR\fIaux\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_tmpl_get_transfer\fR(\fBint\fR \fIfd\fR, \fBctid_t *\fR\fIctidp\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_tmpl_get_fatal\fR(\fBint\fR \fIfd\fR, \fBuint_t *\fR\fIeventsp\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_tmpl_get_param\fR(\fBint\fR \fIfd\fR, \fBuint_t *\fR\fIparamsp\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_tmpl_get_svc_fmri\fR(\fBint\fR \fIfd\fR, \fBchar *\fR\fIfmri\fR, \fBsize_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_tmpl_get_svc_aux\fR(\fBint\fR \fIfd\fR, \fBchar *\fR\fIaux\fR, \fBsize_t\fR \fIsize\fR);
.fi

.SH DESCRIPTION
.sp
.LP
These functions read and write process contract terms and operate on process
contract template file descriptors obtained from the \fBcontract\fR(5) file
system.
.sp
.LP
The \fBct_pr_tmpl_set_transfer()\fR and \fBct_pr_tmpl_get_transfer()\fR
functions write and read the transfer contract term. The value is the ID of an
empty regent process contract owned by the caller whose inherited contracts are
to be transferred to a newly created contract.
.sp
.LP
The \fBct_pr_tmpl_set_fatal()\fR and \fBct_pr_tmpl_get_fatal()\fR functions
write and read the fatal event set term. The value is a collection of bits as
described in \fBprocess\fR(5).
.sp
.LP
The \fBct_pr_tmpl_set_param()\fR and \fBct_pr_tmpl_get_param()\fR functions
write and read the parameter set term. The value is a collection of bits as
described in \fBprocess\fR(5).
.sp
.LP
The \fBct_pr_tmpl_set_svc_fmri()\fR and  \fBct_pr_tmpl_get_svc_fmri()\fR
functions write and read the service FMRI value of a process contract template.
The \fBct_pr_tmpl_set_svc_fmri()\fR function requires the caller to have the
{\fBPRIV_CONTRACT_IDENTITY\fR} privilege in its effective set.
.sp
.LP
The \fBct_pr_tmpl_set_svc_aux()\fR and \fBct_pr_tmpl_get_svc_aux()\fR functions
write and read the creator's auxiliary value of a process contract template.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBct_pr_tmpl_set_transfer()\fR,
\fBct_pr_tmpl_set_fatal()\fR, \fBct_pr_tmpl_set_param()\fR,
\fBct_pr_tmpl_set_svc_fmri()\fR, \fBct_pr_tmpl_set_svc_aux()\fR,
\fBct_pr_tmpl_get_transfer()\fR, \fBct_pr_tmpl_get_fatal()\fR, and
\fBct_pr_tmpl_get_param()\fR return 0. Otherwise, they return a non-zero error
value.
.sp
.LP
Upon successful completion, \fBct_pr_tmpl_get_svc_fmri()\fR and
\fBct_pr_tmpl_get_svc_aux()\fR return the size required to store the value,
which is the same value return by \fBstrcpy\fR(3C) + 1. Insufficient buffer
size can be checked by:
.sp
.in +2
.nf
if (ct_pr_tmpl_get_svc_fmri(fd, fmri, size) > size)
        /* buffer is too small */
.fi
.in -2

.sp
.LP
Otherwise, \fBct_pr_tmpl_get_svc_fmri()\fR and  \fBct_pr_tmpl_get_svc_aux()\fR
return -1 and set \fBerrno\fR to indicate the error.
.SH ERRORS
.sp
.LP
The \fBct_pr_tmpl_set_param()\fR, \fBct_pr_tmpl_set_svc_fmri()\fR,
\fBct_pr_tmpl_set_svc_aux()\fR, \fBct_pr_tmpl_get_svc_fmri()\fR and
\fBct_pr_tmpl_get_svc_aux()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
An invalid parameter was specified.
.RE

.sp
.LP
The \fBct_pr_tmpl_set_fatal()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
An invalid event was specified.
.RE

.sp
.LP
The \fBct_pr_tmpl_set_transfer()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBESRCH\fR\fR
.ad
.RS 13n
The ID specified by \fIctid\fR does not correspond to a process contract.
.RE

.sp
.ne 2
.na
\fB\fBEACCES\fR\fR
.ad
.RS 13n
The ID specified by \fIctid\fR does not correspond to a process contract owned
by the calling process.
.RE

.sp
.ne 2
.na
\fB\fBENOTEMPTY\fR\fR
.ad
.RS 13n
The ID specified by \fIctid\fR does not correspond to an empty process
contract.
.RE

.sp
.LP
The \fBct_pr_tmpl_set_svc_fmri()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEPERM\fR\fR
.ad
.RS 9n
The calling process does not have {\fBPRIV_CONTRACT_IDENTITY\fR} in its
effective set.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRCreate and activate a process contract template.
.sp
.LP
The following example opens a new template, makes hardware errors and signals
fatal events, makes hardware errors critical events, and activates the
template. It then forks a process in the new contract using the requested
terms.

.sp
.in +2
.nf
#include <libcontract.h>
#include <fcntl.h>
#include <unistd.h>

\&...
int fd;

fd = open("/system/contract/process/template", O_RDWR);
(void) ct_pr_tmpl_set_fatal(fd, CT_PR_EV_HWERR|CT_PR_EV_SIGNAL);
(void) ct_tmpl_set_critical(fd, CT_PR_EV_HWERR);
(void) ct_tmpl_activate(fd);
close(fd);

if (fork()) {
        /* parent - owns new process contract */
        ...
} else {
        /* child - in new process contract */
        ...
}
\&...
.fi
.in -2

.LP
\fBExample 2 \fRClear the process contract template.
.sp
.LP
The following example opens the template file and requests that the active
template be cleared.

.sp
.in +2
.nf
#include <libcontract.h>
#include <fcntl.h>

\&...
int fd;

fd = open("/system/contract/process/template", O_RDWR);
(void) ct_tmpl_clear(fd);
close(fd);
\&...
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) 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
.BR strcpy (3C),
.BR libcontract (3LIB),
.BR contract (5),
.BR process (5),
.BR attributes (7),
.BR lfcompile (7)