contract(4) - osol9

1contract(4)                      File Formats                      contract(4)
2
3
4

NAME

6       contract - the contract file system
7

SYNOPSIS

9       /system/contract
10
11

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 facili‐
21       tate the confinement of processes to subtrees of the file system  using
22       chroot(1M)  and  yet  allow  such processes to continue to use contract
23       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 subdirecto‐
36       ries named with each available contract type, and  one  special  direc‐
37       tory,  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  representa‐
44       tion of the contracts' IDs.
45
46
47       The following files are in a /system/contract/type directory:
48
49       template    Opening  this file returns a file descriptor for a new type
50                   contract template.
51
52                   You can use the following libcontract(3LIB) calls on a tem‐
53                   plate file descriptor:
54
55                     >
56
57                      ct_tmpl_activate(3contract)
58                      ct_tmpl_clear(3contract)
59                      ct_tmpl_create(3contract)
60
61
62                   See TERMS for additional template functions.
63
64
65       latest      Opening  this file returns a file descriptor for the status
66                   file of the last type contract written by the opening  LWP.
67                   See  STRUCTURE  OF /system/contract/type/id. If the opening
68                   LWP has not created a type contract, opening  latest  fails
69                   with ESRCH.
70
71
72       bundle      Opening  this  file  returns a file descriptor for an event
73                   endpoint which receives events from all type  contracts  on
74                   the  system. No privileges are required to open a type bun‐
75                   dle event endpoint. Events  sent  by  contracts  owned  and
76                   written  by users other than the reader's effective user id
77                   are invisible, that is, they are silently  skipped,  unless
78                   the  reader  has  {PRIV_CONTRACT_OBSERVER} in its effective
79                   set. See EVENTS.
80
81
82       pbundle     Opening this file returns a file descriptor  for  an  event
83                   endpoint which receives events from all type contracts held
84                   by the opening process. See EVENTS.
85
86
87   STRUCTURE OF /system/contract/all
88       The /system/contract/all directory contains a  numerically  named  file
89       for  each  contract  in the system. Each file is a symbolic link to the
90       type-specific  directory  for  that  contract,  that  is   /system/con‐
91       tract/all/id points to /system/contract/type/id.
92
93   STRUCTURE OF /system/contract/type/id
94       Each /system/contract/type/id directory contains the following files:
95
96       ctl       Opening this file returns a file descriptor for contract id's
97                 control file. The open fails if the opening process does  not
98                 hold  contract  id and the contract has not been inherited by
99                 the process contract of which the opening process is  a  mem‐
100                 ber. See process(4).
101
102                 The  following  libcontract(3LIB)  calls can be made on a ctl
103                 file descriptor if the contract is owned by the caller:
104
105                   ct_ctl_abandon(3contract)
106                   ct_ctl_newct(3contract)
107                   ct_ctl_ack(3contract)
108                   ct_ctl_qack(3contract)
109
110
111                 The following libcontract(3LIB) call can be  made  on  a  ctl
112                 file descriptor if the contract doesn't have an owner:
113
114                   ct_ctl_adopt(3contract)
115
116
117
118
119       status    Opening this file returns a file descriptor for contract id's
120                 status file. The following  libcontract(3LIB)  calls  can  be
121                 made on a status file descriptor:
122
123                 ct_status_read(3contract)
124
125                  See STATUS.
126
127
128       events    Opening this file returns a file descriptor for an event end‐
129                 point which receives events from contract id. See EVENTS.
130
131                 Only a process which has the same effective user  ID  as  the
132                 process  owning  the  contract, the same effective user ID as
133                 the contract's author, or has {PRIV_CONTRACT_OBSERVER} in its
134                 effective set can open the event endpoint for a contract.
135
136
137   TERMS
138       The following terms are defined for all contracts:
139
140       cookie                   Specifies  a 64-bit quantity that the contract
141                                author can use to identify the  contract.  Use
142                                ct_tmpl_set_cookie(3CONTRACT)   to   set  this
143                                term.
144
145
146       informative event set    Selects which events are delivered as informa‐
147                                tive events. Use ct_tmpl_set_informative(3CON‐
148                                TRACT) to set this term.
149
150
151       critical event set       Selects which events are delivered as critical
152                                events. Use ct_tmpl_set_critical(3CONTRACT) to
153                                set this term.
154
155
156   STATUS
157       A status object returned by ct_status_read(3CONTRACT) contains the fol‐
158       lowing pieces of information:
159
160       contract ID
161
162           The  numeric ID of the contract. Use ct_status_get_id(3CONTRACT) to
163           obtain this information.
164
165
166       contract type
167
168           The type of the contract, specifed  as  a  string.  Obtained  using
169           ct_status_get_type(3CONTRACT). The contract type is the same as its
170           subdirectory name under /system/contract.
171
172
173       creator's zone ID
174
175           The zone ID of the process which  created  the  contract.  Obtained
176           using ct_status_get_zoneid(3CONTRACT).
177
178
179       ownership state
180
181           The  state  of the contract, specified as CTS_OWNED, CTS_INHERITED,
182           CTS_ORPHAN,  or  CTS_DEAD.  Use  ct_status_get_state(3CONTRACT)  to
183           obtain this information.
184
185
186       contract holder
187
188           If  the  contract's state is CTS_OWNED, the ID of the process which
189           owns the contract. If the contract's state is CTS_INHERITED, the ID
190           of  the contract which is acting as regent. If the contract's state
191           is  CTS_ORPHAN  or  CTS_DEAD,  this  is  undefined.   Use   ct_sta‐
192           tus_get_holder(3CONTRACT) to obtain this information.
193
194
195       number of critical events
196
197           The  number  of  unacknowledged critical events pending on the con‐
198           tract's event queue. Use ct_status_get_nevents(3CONTRACT) to obtain
199           this information.
200
201
202       negotiation time
203
204           The time remaining before the current synchronous negotiation times
205           out. Use ct_status_get_ntime(3CONTRACT) to obtain this information.
206
207
208       negotiation quantum time
209
210           The time remaining before the current negotiation quantum runs out.
211           Use ct_status_get_qtime(3CONTRACT) to obtain this information.
212
213
214       negotiation event ID
215
216           The  ID  of  the event which initiated the negotiation timeout. Use
217           ct_status_get_nevid(3CONTRACT) to obtain this information.
218
219
220       cookie (term)
221
222           The contract's cookie term. Use ct_status_get_cookie(3CONTRACT)  to
223           obtain this information.
224
225
226       Informative event set (term)
227
228           The  contract's  informative  event set. Use ct_status_get_informa‐
229           tive(3CONTRACT) to obtain this information.
230
231
232       Critical event set (term)
233
234           The contract's critical event set. Use ct_status_get_critical(3CON‐
235           TRACT) to obtain this information.
236
237
238   EVENTS
239       All  three  event endpoints, /system/contract/type/bundle, /system/con‐
240       tract/type/pbundle, and /system/contract/type/id/events,  are  accessed
241       in the same manner.
242
243
244       The  following libcontract(3LIB) interfaces are used with an event end‐
245       point file descriptor:
246
247         ct_event_read(3contract)
248         ct_event_read_critical(3contract)
249         ct_event_reset(3contract)
250         ct_event_next(3contract)
251
252
253
254
255       To facilitate processes watching multiple event endpoints, it is possi‐
256       ble to poll(2) on event endpoints. When it is possible to receive on an
257       endpoint file descriptor, POLLIN is set for that descriptor.
258
259
260       An event object returned by ct_event_read(3CONTRACT) contains the  fol‐
261       lowing information:
262
263       contract ID                 The  ID  of the contract that generated the
264                                   event.  Use   ct_event_read(3CONTRACT)   to
265                                   obtain this information.
266
267
268       event ID                    The    ID   of   the   contract   event.Use
269                                   ct_event_get_evid(3CONTRACT).
270
271
272       flags                       A bit vector possibly including CT_ACK  and
273                                   CTE_INFO. Use ct_event_get_flags(3CONTRACT)
274                                   to obtain this information.
275
276
277       event type                  The type of event, equal to one of the con‐
278                                   stants  specified  in  the  contract type's
279                                   manual   page    or    CT_EV_NEGEND.    Use
280                                   ct_event_get_type(3CONTRACT) to obtain this
281                                   information.
282
283
284   EVENT TYPES
285       The following event types are defined:
286
287       CT_EV_NEGEND    Some time after an exit negotiation is  initiated,  the
288                       CT_EV_NEGEND  event  is  sent.  This indicates that the
289                       negotiation ended. This might be because the  operation
290                       was cancelled, or because the operation was successful.
291                       If successful, and the owner requested that a new  con‐
292                       tract  be  written,  this  contains the ID of that con‐
293                       tract.
294
295                       CT_EV_NEGEND cannot be included in a contract's  infor‐
296                       mative  or  critical  event set. It is always delivered
297                       and always critical. If CT_EV_NEGEND indicates that the
298                       operation  was  successful, no further events are sent.
299                       The contract's owner  should  use  ct_ctl_abandon(3CON‐
300                       TRACT) to abandon the contract.
301
302                       A CT_EV_NEGEND event contains:
303
304                       negotiation ID     The  ID  of  the  negotiation  which
305                                          ended. Use  ct_event_get_nevid(3CON‐
306                                          TRACT) to obain this information.
307
308
309                       new contract ID    The  ID  of  the  newly created con‐
310                                          tract. This value is 0  if  no  con‐
311                                          tract  was created, or the ID of the
312                                          existing contract if  the  operation
313                                          was      not      completed.     Use
314                                          ct_event_get_newct(3CONTRACT)     to
315                                          obtain this information.
316
317
318

FILES

320       /system/contract
321
322           List of all contract types
323
324
325       /system/contract/all
326
327           Directory of all contract IDs
328
329
330       /system/contract/all/id
331
332           Symbolic link to the type-specific directory of contract id
333
334
335       /system/contract/type
336
337           Specific type directory
338
339
340       /system/contract/type/templete
341
342           Template for the contract type
343
344
345       /system/contract/type/bundle
346
347           Listening point for all contracts of that type
348
349
350       /system/contract/type/pbundle
351
352           Listening  point  for  all  contracts  of that type for the opening
353           process
354
355
356       /system/contract/type /latest
357
358           Status of most recent type contract created by the opening LWP
359
360
361       /system/contract/type/ID
362
363           Directory for contract id
364
365
366       /system/contract/type/ID/events
367
368           Listening point for contract id's events
369
370
371       /system/contract/type/ID/ctl
372
373           Control file for contract ID
374
375
376       /system/contract/type/ID/status
377
378           Status info for contract ID
379
380

NAME

SYNOPSIS

DESCRIPTION

FILES

SEE ALSO