'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
.TH ct_pr_tmpl_set_transfer 3CONTRACT "25 Feb 2008" "SunOS 5.11" "Contract Management Library Functions"
.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(4) 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(4).
.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(4).
.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
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
An invalid parameter was specified.
.RE

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

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

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

.sp
.ne 2
.mk
.na
\fB\fBENOTEMPTY\fR\fR
.ad
.RS 13n
.rt  
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
.mk
.na
\fB\fBEPERM\fR\fR
.ad
.RS 9n
.rt  
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(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
.TE

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