Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

OpenSolaris 2009.06 - man page for contract (opensolaris section 4)

contract(4)				   File Formats 			      contract(4)

NAME
       contract - the contract file system

SYNOPSIS
       /system/contract

DESCRIPTION
       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  /sys-
       tem/contract  mount  point,  and  can  be  mounted several places at once. Such additional
       mounts are allowed in order to facilitate the confinement of processes to subtrees of  the
       file system using chroot(1M) and yet allow such processes to continue to use contract com-
       mands 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 subdirectories named  with  each
       available  contract  type,  and	one  special directory, 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 representation 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  descrip-
		   tor:

		     >

		      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/con-
		   tract/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  contracts  on the system. No privileges are
		   required to open a type bundle event endpoint. Events sent by contracts  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 contracts  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/contract/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 libcontract(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_CON-
		 TRACT_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  following  pieces  of
       information:

       contract ID

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

       contract type

	   The	type  of  the  contract,  specifed  as	 a   string.   Obtained   using   ct_sta-
	   tus_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_sta-
	   tus_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_status_get_holder(3CONTRACT) to obtain this information.

       number of critical events

	   The	number	of  unacknowledged critical events pending on the contract'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_sta-
	   tus_get_ntime(3CONTRACT) to obtain this information.

       negotiation quantum time

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

       negotiation event ID

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

       cookie (term)

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

       Informative event set (term)

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

       Critical event set (term)

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

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

       The  following  libcontract(3LIB) interfaces are used with an event endpoint file descrip-
       tor:

	 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 possible  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 following information:

       contract ID		   The	ID  of	the  contract  that  generated	the  event.   Use
				   ct_event_read(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 constants 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 operation 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 further events  are  sent.
		       The  contract's	owner should use ct_ctl_abandon(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 informa-
					  tion.

		       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 informa-
					  tion.

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

SEE ALSO
       ctrun(1),  ctstat(1),  ctwatch(1),  chroot(1M),	close(2),  ioctl(2),  open(2),	 poll(2),
       ct_ctl_abandon(3CONTRACT),     ct_event_read(3CONTRACT),     ct_event_get_evid(3CONTRACT),
       ct_event_get_flags(3CONTRACT),	ct_event_get_nevid(3CONTRACT),	 ct_event_get_newct(3CON-
       TRACT),	ct_event_get_type(3CONTRACT), ct_status_read(3CONTRACT)ct_status_get_cookie(3CON-
       TRACT),	 ct_status_get_critical(3CONTRACT),   ct_status_get_holder(3CONTRACT),	  ct_sta-
       tus_get_id(3CONTRACT),	ct_status_get_informative(3CONTRACT),	ct_status_get_nevid(3CON-
       TRACT),	  ct_status_get_nevents(3CONTRACT),    ct_status_get_ntime(3CONTRACT),	  ct_sta-
       tus_get_qtime(3CONTRACT),  ct_status_get_state(3CONTRACT),  ct_status_get_type(3CONTRACT),
       ct_tmpl_set_cookie(3CONTRACT),	 ct_tmpl_set_critical(3CONTRACT),    ct_tmpl_set_informa-
       tive(3CONTRACT), libcontract(3LIB), process(4), largefile(5), lfcompile(5), privileges(5)

SunOS 5.11				   11 Jul 2005				      contract(4)


All times are GMT -4. The time now is 07:31 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password