Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
contract(4)							   contract(4)

NAME
       contract	- the contract file system

SYNOPSIS
       /system/contract

       The  /system/contract  file system acts as the primary interface	to the
       contract	subsystem. There is a  subdirectory  of	 /system/contract  for
       each available contract type.

       /system/contract	 can be	mounted	on any mount point, in addition	to the
       standard	/system/contract mount	point,	and  can  be  mounted  several
       places  at once.	Such additional	mounts are allowed in order to facili-
       tate the	confinement of processes to subtrees of	the file system	 using
       chroot(1M)  and	yet  allow  such processes to continue to use contract
       commands	and interfaces.

       A combination of	standard system	calls (for example, open(2), close(2),
       and  poll(2))  and  calls  to libcontract(3LIB) access /system/contract
       files.

       Consumers of the	contract file system must be  large  file  aware.  See
       largefile(5) and	lfcompile64(5).

   DIRECTORY STRUCTURE
       At  the	top level, the /system/contract	directory contains subdirecto-
       ries named with each available contract type, and  one  special	direc-
       tory,  all.  Each  of  these  directories  is world-readable and	world-
       searchable.

   STRUCTURE OF	/system/contract/type
       Each /system/contract/type directory contains a fixed number of	files.
       It  also	 contains a variable number of subdirectories corresponding to
       existing	contracts of type type and named with the decimal  representa-
       tion of the contracts' IDs.

       The following files are in a /system/contract/type directory:

       template	       Opening	this  file returns a file descriptor for a new
		       type contract template.

		       You can use the following libcontract(3LIB) calls on  a
		       template	file descriptor:

			ct_tmpl_activate(3contract)
			ct_tmpl_clear(3contract)
			ct_tmpl_create(3contract)

		       See TERMS for additional	template functions.

       latest	       Opening	this  file  returns  a file descriptor for the
		       status file of the last type contract  written  by  the
		       opening LWP. See	STRUCTURE OF /system/contract/type/id.
		       If the opening LWP has not  created  a  type  contract,
		       opening latest fails with ESRCH.

       bundle	       Opening	this  file  returns  a	file descriptor	for an
		       event endpoint which receives events from all type con-
		       tracts  on  the	system.	 No privileges are required to
		       open a type bundle event	endpoint. Events sent by  con-
		       tracts  owned  and  written  by	users  other  than the
		       reader's	effective user id are invisible, that is, they
		       are  silently skipped, unless the reader	has {PRIV_CON-
		       TRACT_OBSERVER} in its effective	set. See EVENTS.

       pbundle	       Opening this file returns  a  file  descriptor  for  an
		       event endpoint which receives events from all type con-
		       tracts held by the opening process. See EVENTS.

   STRUCTURE OF	/system/contract/all
       The /system/contract/all	directory contains a  numerically  named  file
       for  each  contract  in the system. Each	file is	a symbolic link	to the
       type-specific  directory	 for  that  contract,  that  is	  /system/con-
       tract/all/id points to /system/contract/type/id.

   STRUCTURE OF	/system/contract/type/id
       Each /system/contract/type/id directory contains	the following files:

       ctl		       Opening this file returns a file	descriptor for
			       contract	id's control file. The open  fails  if
			       the  opening  process does not hold contract id
			       and the contract	has not	been inherited by  the
			       process	contract  of which the opening process
			       is a member. See	process(4).

			       The following libcontract(3LIB)	calls  can  be
			       made  on	 a ctl file descriptor if the contract
			       is owned	by the caller:

			       ct_ctl_abandon(3contract)
			       ct_ctl_newct(3contract)
			       ct_ctl_ack(3contract)
			       ct_ctl_qack(3contract)

			       The following  libcontract(3LIB)	 call  can  be
			       made  on	 a ctl file descriptor if the contract
			       doesn't have an owner:

			       ct_ctl_adopt(3contract)

       status		       Opening this file returns a file	descriptor for
			       contract	 id's  status file. The	following lib-
			       contract(3LIB) calls can	be made	 on  a	status
			       file descriptor:

			       ct_status_read(3contract)

				See STATUS.

       events		       Opening this file returns a file	descriptor for
			       an event	endpoint which	receives  events  from
			       contract	id. See	EVENTS.

			       Only  a	process	 which	has the	same effective
			       user ID as the process owning the contract, the
			       same   effective	 user  ID  as  the  contract's
			       author, or has {PRIV_CONTRACT_OBSERVER} in  its
			       effective set can open the event	endpoint for a
			       contract.

   TERMS
       The following terms are defined for all contracts:

       cookie

	   Specifies a 64-bit quantity that the	contract  author  can  use  to
	   identify  the  contract.  Use  ct_tmpl_set_cookie(3CONTRACT)	to set
	   this	term.

       informative event set

	   Selects which events	 are  delivered	 as  informative  events.  Use
	   ct_tmpl_set_informative(3CONTRACT) to set this term.

       critical	event set

	   Selects   which  events  are	 delivered  as	critical  events.  Use
	   ct_tmpl_set_critical(3CONTRACT) to set this term.

   STATUS
       A status	object returned	by ct_status_read(3CONTRACT) contains the fol-
       lowing pieces of	information:

       contract	ID

	   The	numeric	ID of the contract. Use	ct_status_get_id(3CONTRACT) to
	   obtain this information.

       contract	type

	   The type of the contract, specifed  as  a  string.  Obtained	 using
	   ct_status_get_type(3CONTRACT).   The	 contract  type	is the same as
	   its subdirectory name under /system/contract.

       creator's zone ID

	   The zone ID of the process which  created  the  contract.  Obtained
	   using ct_status_get_zoneid(3CONTRACT).

       ownership state

	   The	state  of the contract,	specified as CTS_OWNED,	CTS_INHERITED,
	   CTS_ORPHAN,	or  CTS_DEAD.  Use  ct_status_get_state(3CONTRACT)  to
	   obtain this information.

       contract	holder

	   If  the  contract's state is	CTS_OWNED, the ID of the process which
	   owns	the contract. If the contract's	state is CTS_INHERITED,	the ID
	   of  the contract which is acting as regent. If the contract's state
	   is  CTS_ORPHAN  or  CTS_DEAD,  this	is  undefined.	 Use   ct_sta-
	   tus_get_holder(3CONTRACT) to	obtain this information.

       number of critical events

	   The	number	of  unacknowledged critical events pending on the con-
	   tract's event queue.	Use ct_status_get_nevents(3CONTRACT) to	obtain
	   this	information.

       negotiation time

	   The time remaining before the current synchronous negotiation times
	   out.	Use ct_status_get_ntime(3CONTRACT) to obtain this information.

       negotiation quantum time

	   The time remaining before the current negotiation quantum runs out.
	   Use ct_status_get_qtime(3CONTRACT) to obtain	this information.

       negotiation event ID

	   The	ID  of	the event which	initiated the negotiation timeout. Use
	   ct_status_get_nevid(3CONTRACT) to obtain this information.

       cookie (term)

	   The contract's cookie term. Use ct_status_get_cookie(3CONTRACT)  to
	   obtain this information.

       Informative event set (term)

	   The	contract's  informative	 event set. Use	ct_status_get_informa-
	   tive(3CONTRACT) to obtain this information.

       Critical	event set (term)

	   The contract's critical event set. Use ct_status_get_critical(3CON-
	   TRACT) to obtain this information.

   EVENTS
       All  three  event endpoints, /system/contract/type/bundle, /system/con-
       tract/type/pbundle, and /system/contract/type/id/events,	 are  accessed
       in the same manner.

       The  following libcontract(3LIB)	interfaces are used with an event end-
       point file descriptor:

       ct_event_read(3contract)
       ct_event_read_critical(3contract)
       ct_event_reset(3contract)
       ct_event_next(3contract)

       To facilitate processes watching	multiple event endpoints, it is	possi-
       ble to poll(2) on event endpoints. When it is possible to receive on an
       endpoint	file descriptor, POLLIN	is set for that	descriptor.

       An event	object returned	by ct_event_read(3CONTRACT) contains the  fol-
       lowing information:

       contract	ID	       The  ID	of  the	 contract  that	 generated the
			       event.  Use   ct_event_get_ctid(3CONTRACT)   to
			       obtain this information.

       event ID		       The    ID    of	  the	 contract    event.Use
			       ct_event_get_evid(3CONTRACT).

       flags		       A bit  vector  possibly	including  CT_ACK  and
			       CTE_INFO.  Use ct_event_get_flags(3CONTRACT) to
			       obtain this information.

       event type	       The type	of event, equal	to  one	 of  the  con-
			       stants  specified in the	contract type's	manual
			       page	   or	     CT_EV_NEGEND.	   Use
			       ct_event_get_type(3CONTRACT)   to  obtain  this
			       information.

   EVENT TYPES
       The following event types are defined:

       CT_EV_NEGEND

	   Some	time after an exit negotiation is initiated, the  CT_EV_NEGEND
	   event  is  sent.  This  indicates  that the negotiation ended. This
	   might be because the	operation was cancelled, or because the	opera-
	   tion	was successful.	 If successful,	and the	owner requested	that a
	   new contract	be written, this contains the ID of that contract.

	   CT_EV_NEGEND	cannot be included  in	a  contract's  informative  or
	   critical  event set.	It is always delivered and always critical. If
	   CT_EV_NEGEND	indicates that the operation was successful,  no  fur-
	   ther	 events	are sent. The contract's owner should use ct_ctl_aban-
	   don(3CONTRACT) to abandon the contract.

	   A CT_EV_NEGEND event	contains:

	   negotiation ID

	       The    ID    of	  the	 negotiation	which	 ended.	   Use
	       ct_event_get_nevid(3CONTRACT) to	obain this information.

	   new contract	ID

	       The  ID	of  the	 newly created contract. This value is 0 if no
	       contract	was created, or	the ID of the existing contract	if the
	       operation  was not completed. Use ct_event_get_newct(3CONTRACT)
	       to obtain this information.

FILES
       /system/contract

	   List	of all contract	types

       /system/contract/all

	   Directory of	all contract IDs

       /system/contract/all/id

	   Symbolic link to the	type-specific directory	of contract id

       /system/contract/type

	   Specific type directory

       /system/contract/type/templete

	   Template for	the contract type

       /system/contract/type/bundle

	   Listening point for all contracts of	that type

       /system/contract/type/pbundle

	   Listening point for all contracts of	 that  type  for  the  opening
	   process

       /system/contract/type /latest

	   Status of most recent type contract created by the opening LWP

       /system/contract/type/ID

	   Directory for contract id

       /system/contract/type/ID/events

	   Listening point for contract	id's events

       /system/contract/type/ID/ctl

	   Control file	for contract ID

       /system/contract/type/ID/status

	   Status info for contract ID

       ctrun(1),   ctstat(1),	ctwatch(1),  chroot(1M),  close(2),  ioctl(2),
       open(2),	 poll(2),  ct_ctl_abandon(3CONTRACT),  ct_event_get_ctid(3CON-
       TRACT),	 ct_event_get_evid(3CONTRACT),	ct_event_get_flags(3CONTRACT),
       ct_event_get_nevid(3CONTRACT),		ct_event_get_newct(3CONTRACT),
       ct_event_get_type(3CONTRACT),	      ct_status_read(3CONTRACT)ct_sta-
       tus_get_cookie(3CONTRACT),  ct_status_get_critical(3CONTRACT),  ct_sta-
       tus_get_holder(3CONTRACT),     ct_status_get_id(3CONTRACT),     ct_sta-
       tus_get_informative(3CONTRACT), ct_status_get_nevid(3CONTRACT), ct_sta-
       tus_get_nevents(3CONTRACT),   ct_status_get_ntime(3CONTRACT),   ct_sta-
       tus_get_qtime(3CONTRACT),    ct_status_get_state(3CONTRACT),    ct_sta-
       tus_get_type(3CONTRACT),			ct_tmpl_set_cookie(3CONTRACT),
       ct_tmpl_set_critical(3CONTRACT),	   ct_tmpl_set_informative(3CONTRACT),
       libcontract(3LIB),   process(4),	  largefile(5),	 lfcompile(5),	privi-
       leges(5)

				  11 Jul 2005			   contract(4)

NAME | SYNOPSIS | FILES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=contract&sektion=4&manpath=SunOS+5.10>

home | help