1 CONTRACT(4) File Formats and Configurations CONTRACT(4)
2
3
4
5 NAME
6 contract - the contract file system
7
8 SYNOPSIS
9 /system/contract
10
11
12 DESCRIPTION
13 The /system/contract file system acts as the primary interface to the
14 contract subsystem. There is a subdirectory of /system/contract for
15 each available contract type.
16
17
18 /system/contract can be mounted on any mount point, in addition to the
19 standard /system/contract mount point, and can be mounted several
20 places at once. Such additional mounts are allowed in order to
21 facilitate the confinement of processes to subtrees of the file system
22 using chroot(1M) and yet allow such processes to continue to use
23 contract commands and interfaces.
24
25
26 A combination of standard system calls (for example, open(2), close(2),
27 and poll(2)) and calls to libcontract(3LIB) access /system/contract
28 files.
29
30
31 Consumers of the contract file system must be large file aware. See
32 largefile(5) and lfcompile64(5).
33
34 DIRECTORY STRUCTURE
35 At the top level, the /system/contract directory contains
36 subdirectories named with each available contract type, and one special
37 directory, all. Each of these directories is world-readable and world-
38 searchable.
39
40 STRUCTURE OF /system/contract/type
41 Each /system/contract/type directory contains a fixed number of files.
42 It also contains a variable number of subdirectories corresponding to
43 existing contracts of type type and named with the decimal
44 representation of the contracts' IDs.
45
46
47 The following files are in a /system/contract/type directory:
48
49 template
50 Opening this file returns a file descriptor for a new type
51 contract template.
52
53 You can use the following libcontract(3LIB) calls on a
54 template file descriptor:
55
56 >
57
58 ct_tmpl_activate(3contract)
59 ct_tmpl_clear(3contract)
60 ct_tmpl_create(3contract)
61
62
63 See TERMS for additional template functions.
64
65
66 latest
67 Opening this file returns a file descriptor for the status
68 file of the last type contract written by the opening LWP.
69 See STRUCTURE OF /system/contract/type/id. If the opening
70 LWP has not created a type contract, opening latest fails
71 with ESRCH.
72
73
74 bundle
75 Opening this file returns a file descriptor for an event
76 endpoint which receives events from all type contracts on
77 the system. No privileges are required to open a type
78 bundle event endpoint. Events sent by contracts owned and
79 written by users other than the reader's effective user id
80 are invisible, that is, they are silently skipped, unless
81 the reader has {PRIV_CONTRACT_OBSERVER} in its effective
82 set. See EVENTS.
83
84
85 pbundle
86 Opening this file returns a file descriptor for an event
87 endpoint which receives events from all type contracts held
88 by the opening process. See EVENTS.
89
90
91 STRUCTURE OF /system/contract/all
92 The /system/contract/all directory contains a numerically named file
93 for each contract in the system. Each file is a symbolic link to the
94 type-specific directory for that contract, that is
95 /system/contract/all/id points to /system/contract/type/id.
96
97 STRUCTURE OF /system/contract/type/id
98 Each /system/contract/type/id directory contains the following files:
99
100 ctl
101 Opening this file returns a file descriptor for contract id's
102 control file. The open fails if the opening process does not
103 hold contract id and the contract has not been inherited by
104 the process contract of which the opening process is a
105 member. See process(4).
106
107 The following libcontract(3LIB) calls can be made on a ctl
108 file descriptor if the contract is owned by the caller:
109
110 ct_ctl_abandon(3contract)
111 ct_ctl_newct(3contract)
112 ct_ctl_ack(3contract)
113 ct_ctl_qack(3contract)
114
115
116 The following libcontract(3LIB) call can be made on a ctl
117 file descriptor if the contract doesn't have an owner:
118
119 ct_ctl_adopt(3contract)
120
121
122
123
124 status
125 Opening this file returns a file descriptor for contract id's
126 status file. The following libcontract(3LIB) calls can be
127 made on a status file descriptor:
128
129 ct_status_read(3contract)
130
131 See STATUS.
132
133
134 events
135 Opening this file returns a file descriptor for an event
136 endpoint which receives events from contract id. See EVENTS.
137
138 Only a process which has the same effective user ID as the
139 process owning the contract, the same effective user ID as
140 the contract's author, or has {PRIV_CONTRACT_OBSERVER} in its
141 effective set can open the event endpoint for a contract.
142
143
144 TERMS
145 The following terms are defined for all contracts:
146
147 cookie
148 Specifies a 64-bit quantity that the contract
149 author can use to identify the contract. Use
150 ct_tmpl_set_cookie(3CONTRACT) to set this
151 term.
152
153
154 informative event set
155 Selects which events are delivered as
156 informative events. Use
157 ct_tmpl_set_informative(3CONTRACT) to set this
158 term.
159
160
161 critical event set
162 Selects which events are delivered as critical
163 events. Use ct_tmpl_set_critical(3CONTRACT) to
164 set this term.
165
166
167 STATUS
168 A status object returned by ct_status_read(3CONTRACT) contains the
169 following pieces of information:
170
171 contract ID
172
173 The numeric ID of the contract. Use ct_status_get_id(3CONTRACT) to
174 obtain this information.
175
176
177 contract type
178
179 The type of the contract, specified as a string. Obtained using
180 ct_status_get_type(3CONTRACT). The contract type is the same as its
181 subdirectory name under /system/contract.
182
183
184 creator's zone ID
185
186 The zone ID of the process which created the contract. Obtained
187 using ct_status_get_zoneid(3CONTRACT).
188
189
190 ownership state
191
192 The state of the contract, specified as CTS_OWNED, CTS_INHERITED,
193 CTS_ORPHAN, or CTS_DEAD. Use ct_status_get_state(3CONTRACT) to
194 obtain this information.
195
196
197 contract holder
198
199 If the contract's state is CTS_OWNED, the ID of the process which
200 owns the contract. If the contract's state is CTS_INHERITED, the ID
201 of the contract which is acting as regent. If the contract's state
202 is CTS_ORPHAN or CTS_DEAD, this is undefined. Use
203 ct_status_get_holder(3CONTRACT) to obtain this information.
204
205
206 number of critical events
207
208 The number of unacknowledged critical events pending on the
209 contract's event queue. Use ct_status_get_nevents(3CONTRACT) to
210 obtain this information.
211
212
213 negotiation time
214
215 The time remaining before the current synchronous negotiation times
216 out. Use ct_status_get_ntime(3CONTRACT) to obtain this information.
217
218
219 negotiation quantum time
220
221 The time remaining before the current negotiation quantum runs out.
222 Use ct_status_get_qtime(3CONTRACT) to obtain this information.
223
224
225 negotiation event ID
226
227 The ID of the event which initiated the negotiation timeout. Use
228 ct_status_get_nevid(3CONTRACT) to obtain this information.
229
230
231 cookie (term)
232
233 The contract's cookie term. Use ct_status_get_cookie(3CONTRACT) to
234 obtain this information.
235
236
237 Informative event set (term)
238
239 The contract's informative event set. Use
240 ct_status_get_informative(3CONTRACT) to obtain this information.
241
242
243 Critical event set (term)
244
245 The contract's critical event set. Use
246 ct_status_get_critical(3CONTRACT) to obtain this information.
247
248
249 EVENTS
250 All three event endpoints, /system/contract/type/bundle,
251 /system/contract/type/pbundle, and /system/contract/type/id/events, are
252 accessed in the same manner.
253
254
255 The following libcontract(3LIB) interfaces are used with an event
256 endpoint file descriptor:
257
258 ct_event_read(3contract)
259 ct_event_read_critical(3contract)
260 ct_event_reset(3contract)
261
262
263
264
265 To facilitate processes watching multiple event endpoints, it is
266 possible to poll(2) on event endpoints. When it is possible to receive
267 on an endpoint file descriptor, POLLIN is set for that descriptor.
268
269
270 An event object returned by ct_event_read(3CONTRACT) contains the
271 following information:
272
273 contract ID
274 The ID of the contract that generated the
275 event. Use ct_event_read(3CONTRACT) to
276 obtain this information.
277
278
279 event ID
280 The ID of the contract event.Use
281 ct_event_get_evid(3CONTRACT).
282
283
284 flags
285 A bit vector possibly including CT_ACK and
286 CTE_INFO. Use ct_event_get_flags(3CONTRACT)
287 to obtain this information.
288
289
290 event type
291 The type of event, equal to one of the
292 constants specified in the contract type's
293 manual page or CT_EV_NEGEND. Use
294 ct_event_get_type(3CONTRACT) to obtain this
295 information.
296
297
298 EVENT TYPES
299 The following event types are defined:
300
301 CT_EV_NEGEND
302 Some time after an exit negotiation is initiated, the
303 CT_EV_NEGEND event is sent. This indicates that the
304 negotiation ended. This might be because the operation
305 was cancelled, or because the operation was successful.
306 If successful, and the owner requested that a new
307 contract be written, this contains the ID of that
308 contract.
309
310 CT_EV_NEGEND cannot be included in a contract's
311 informative or critical event set. It is always
312 delivered and always critical. If CT_EV_NEGEND
313 indicates that the operation was successful, no further
314 events are sent. The contract's owner should use
315 ct_ctl_abandon(3CONTRACT) to abandon the contract.
316
317 A CT_EV_NEGEND event contains:
318
319 negotiation ID
320 The ID of the negotiation which
321 ended. Use
322 ct_event_get_nevid(3CONTRACT) to
323 obain this information.
324
325
326 new contract ID
327 The ID of the newly created
328 contract. This value is 0 if no
329 contract was created, or the ID of
330 the existing contract if the
331 operation was not completed. Use
332 ct_event_get_newct(3CONTRACT) to
333 obtain this information.
334
335
336
337 FILES
338 /system/contract
339
340 List of all contract types
341
342
343 /system/contract/all
344
345 Directory of all contract IDs
346
347
348 /system/contract/all/id
349
350 Symbolic link to the type-specific directory of contract id
351
352
353 /system/contract/type
354
355 Specific type directory
356
357
358 /system/contract/type/template
359
360 Template for the contract type
361
362
363 /system/contract/type/bundle
364
365 Listening point for all contracts of that type
366
367
368 /system/contract/type/pbundle
369
370 Listening point for all contracts of that type for the opening
371 process
372
373
374 /system/contract/type /latest
375
376 Status of most recent type contract created by the opening LWP
377
378
379 /system/contract/type/ID
380
381 Directory for contract id
382
383
384 /system/contract/type/ID/events
385
386 Listening point for contract id's events
387
388
389 /system/contract/type/ID/ctl
390
391 Control file for contract ID
392
393
394 /system/contract/type/ID/status
395
396 Status info for contract ID
397
398
399 SEE ALSO
400 ctrun(1), ctstat(1), ctwatch(1), chroot(1M), close(2), ioctl(2),
401 open(2), poll(2), ct_ctl_abandon(3CONTRACT), ct_event_read(3CONTRACT),
402 ct_event_get_evid(3CONTRACT), ct_event_get_flags(3CONTRACT),
403 ct_event_get_nevid(3CONTRACT), ct_event_get_newct(3CONTRACT),
404 ct_event_get_type(3CONTRACT), ct_status_read(3CONTRACT),
405 ct_status_get_cookie(3CONTRACT), ct_status_get_critical(3CONTRACT),
406 ct_status_get_holder(3CONTRACT), ct_status_get_id(3CONTRACT),
407 ct_status_get_informative(3CONTRACT), ct_status_get_nevid(3CONTRACT),
408 ct_status_get_nevents(3CONTRACT), ct_status_get_ntime(3CONTRACT),
409 ct_status_get_qtime(3CONTRACT), ct_status_get_state(3CONTRACT),
410 ct_status_get_type(3CONTRACT), ct_tmpl_set_cookie(3CONTRACT),
411 ct_tmpl_set_critical(3CONTRACT), ct_tmpl_set_informative(3CONTRACT),
412 libcontract(3LIB), process(4), largefile(5), lfcompile(5),
413 privileges(5)
414
415
416
417 November 26, 2017 CONTRACT(4)