ct_pr_tmpl_set_transfer(3contract)

1ct_pr_tmpl_set_transfeCro(n3tCrOaNcTtRAMCaTn)agement Librcatr_yprF_utnmcptli_osnest_transfer(3CONTRACT)
2
3
4

NAME

6       ct_pr_tmpl_set_transfer,   ct_pr_tmpl_set_fatal,  ct_pr_tmpl_set_param,
7       ct_pr_tmpl_set_svc_fmri, ct_pr_tmpl_set_svc_aux,  ct_pr_tmpl_get_trans‐
8       fer,             ct_pr_tmpl_get_fatal,            ct_pr_tmpl_get_param,
9       ct_pr_tmpl_get_svc_fmri, ct_pr_tmpl_get_svc_aux - process contract tem‐
10       plate functions
11

SYNOPSIS

13       cc [ flag... ] file... -D_LARGEFILE64_SOURCE  -lcontract  [ library... ]
14       #include <libcontract.h>
15       #include <sys/contract/process.h>
16
17       int ct_pr_tmpl_set_transfer(int fd, ctid_t ctid);
18
19
20       int ct_pr_tmpl_set_fatal(int fd, uint_t events);
21
22
23       int ct_pr_tmpl_set_param(int fd, uint_t params);
24
25
26       int ct_pr_tmpl_set_svc_fmri(int fd, const char *fmri);
27
28
29       int ct_pr_tmpl_set_svc_aux(int fd, const char *aux);
30
31
32       int ct_pr_tmpl_get_transfer(int fd, ctid_t *ctidp);
33
34
35       int ct_pr_tmpl_get_fatal(int fd, uint_t *eventsp);
36
37
38       int ct_pr_tmpl_get_param(int fd, uint_t *paramsp);
39
40
41       int ct_pr_tmpl_get_svc_fmri(int fd, char *fmri, size_t size);
42
43
44       int ct_pr_tmpl_get_svc_aux(int fd, char *aux, size_t size);
45
46

DESCRIPTION

48       These  functions  read  and write process contract terms and operate on
49       process contract template  file  descriptors  obtained  from  the  con‐
50       tract(4) file system.
51
52
53       The  ct_pr_tmpl_set_transfer()  and ct_pr_tmpl_get_transfer() functions
54       write and read the transfer contract term. The value is the  ID  of  an
55       empty  regent process contract owned by the caller whose inherited con‐
56       tracts are to be transferred to a newly created contract.
57
58
59       The ct_pr_tmpl_set_fatal() and ct_pr_tmpl_get_fatal()  functions  write
60       and read the fatal event set term. The value is a collection of bits as
61       described in process(4).
62
63
64       The ct_pr_tmpl_set_param() and ct_pr_tmpl_get_param()  functions  write
65       and  read  the parameter set term. The value is a collection of bits as
66       described in process(4).
67
68
69       The ct_pr_tmpl_set_svc_fmri() and  ct_pr_tmpl_get_svc_fmri()  functions
70       write  and  read the service FMRI value of a process contract template.
71       The ct_pr_tmpl_set_svc_fmri() function requires the caller to have  the
72       {PRIV_CONTRACT_IDENTITY} privilege in its effective set.
73
74
75       The  ct_pr_tmpl_set_svc_aux()  and  ct_pr_tmpl_get_svc_aux()  functions
76       write and read the creator's auxiliary value of a process contract tem‐
77       plate.
78

RETURN VALUES

80       Upon       successful       completion,      ct_pr_tmpl_set_transfer(),
81       ct_pr_tmpl_set_fatal(),                         ct_pr_tmpl_set_param(),
82       ct_pr_tmpl_set_svc_fmri(),                    ct_pr_tmpl_set_svc_aux(),
83       ct_pr_tmpl_get_transfer(),         ct_pr_tmpl_get_fatal(),          and
84       ct_pr_tmpl_get_param()  return  0.  Otherwise,  they  return a non-zero
85       error value.
86
87
88       Upon    successful    completion,     ct_pr_tmpl_get_svc_fmri()     and
89       ct_pr_tmpl_get_svc_aux()  return  the size required to store the value,
90       which is the same value return by strcpy(3C) + 1.  Insufficient  buffer
91       size can be checked by:
92
93         if (ct_pr_tmpl_get_svc_fmri(fd, fmri, size) > size)
94                 /* buffer is too small */
95
96
97
98       Otherwise,   ct_pr_tmpl_get_svc_fmri()   and   ct_pr_tmpl_get_svc_aux()
99       return -1 and set errno to indicate the error.
100

ERRORS

102       The         ct_pr_tmpl_set_param(),          ct_pr_tmpl_set_svc_fmri(),
103       ct_pr_tmpl_set_svc_aux(),         ct_pr_tmpl_get_svc_fmri()         and
104       ct_pr_tmpl_get_svc_aux() functions will fail if:
105
106       EINVAL    An invalid parameter was specified.
107
108
109
110       The ct_pr_tmpl_set_fatal() function will fail if:
111
112       EINVAL    An invalid event was specified.
113
114
115
116       The ct_pr_tmpl_set_transfer() function will fail if:
117
118       ESRCH        The ID specified by ctid does not correspond to a  process
119                    contract.
120
121
122       EACCES       The  ID specified by ctid does not correspond to a process
123                    contract owned by the calling process.
124
125
126       ENOTEMPTY    The ID specified by ctid does not correspond to  an  empty
127                    process contract.
128
129
130
131       The ct_pr_tmpl_set_svc_fmri() function will fail if:
132
133       EPERM    The  calling process does not have {PRIV_CONTRACT_IDENTITY} in
134                its effective set.
135
136

EXAMPLES

138       Example 1 Create and activate a process contract template.
139
140
141       The following example opens a new template, makes hardware  errors  and
142       signals  fatal events, makes hardware errors critical events, and acti‐
143       vates the template. It then forks a process in the new  contract  using
144       the requested terms.
145
146
147         #include <libcontract.h>
148         #include <fcntl.h>
149         #include <unistd.h>
150
151         ...
152         int fd;
153
154         fd = open("/system/contract/process/template", O_RDWR);
155         (void) ct_pr_tmpl_set_fatal(fd, CT_PR_EV_HWERR|CT_PR_EV_SIGNAL);
156         (void) ct_tmpl_set_critical(fd, CT_PR_EV_HWERR);
157         (void) ct_tmpl_activate(fd);
158         close(fd);
159
160         if (fork()) {
161                 /* parent - owns new process contract */
162                 ...
163         } else {
164                 /* child - in new process contract */
165                 ...
166         }
167         ...
168
169
170       Example 2 Clear the process contract template.
171
172
173       The  following  example  opens  the template file and requests that the
174       active template be cleared.
175
176
177         #include <libcontract.h>
178         #include <fcntl.h>
179
180         ...
181         int fd;
182
183         fd = open("/system/contract/process/template", O_RDWR);
184         (void) ct_tmpl_clear(fd);
185         close(fd);
186         ...
187
188

ATTRIBUTES

190       See attributes(5) for descriptions of the following attributes:
191
192
193
194
195       ┌─────────────────────────────┬─────────────────────────────┐
196       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
197       ├─────────────────────────────┼─────────────────────────────┤
198       │Interface Stability          │Committed                    │
199       ├─────────────────────────────┼─────────────────────────────┤
200       │MT-Level                     │Safe                         │
201       └─────────────────────────────┴─────────────────────────────┘
202