Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

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

device_contract(4)			   File Formats 		       device_contract(4)

NAME
       device_contract - device contract type

SYNOPSIS
       /system/contract/device

DESCRIPTION
       Device  contracts  allow processes to monitor events involving a device of interest and to
       react and/or block state changes involving such devices.

       Device contracts are managed using the contract(4) file system and  the	libcontract(3LIB)
       library. The process contract type directory is /system/contract/device.

   Creation
       A device contract may be created in one of two ways:

	   o	  A  process  may  create and activate a template and then invoke open on a minor
		  node of the device. The act of opening creates a contract based on the terms in
		  the activated template.

	   o	  A process may create a contract after it has opened a device by creating a tem-
		  plate, setting appropriate terms (including the path to a minor  node)  on  the
		  template and then invoking ct_tmpl_create() on the template.

   States, Breaks and Events
       A state refers to the state of the device which is the subject of the contract. Currently,
       three states are defined for device contracts:

       CT_DEV_EV_ONLINE      The device is online and functioning normally.

       CT_DEV_EV_DEGRADED    The device is online, but functioning in a degraded capacity.

       CT_DEV_EV_OFFLINE     The device is offline and is not configured for use.

       A process creates a device contract with the kernel to get a guarantee that the device  is
       in  an  acceptable set of states as long as the contract is valid. This acceptable set (or
       "A-set", for short) is specified as one of the terms of the contract when the contract  is
       created.

       When  a	device moves to a state outside the "A-set", the contract is broken. The breaking
       of the contract may be either asynchronous or synchronous, depending on whether the  tran-
       sition that led to the breaking of the contract is synchronous or asynchronous.

       If the breaking of a contract is asynchronous, then a critical event is generated and sent
       to the contract holder. The event is generated even if the contract holder  has	not  sub-
       scribed to the event via the critical or informative event sets.

       If  the	breaking  of  the contract is synchronous, a critical contract event is generated
       with the CTE_NEG flag set to indicate that this	is  a  negotiation  event.  The  contract
       holder  is  expected to either acknowledge (ACK) this change and allow the state change to
       occur or it may negatively acknowledge (NACK) the change to block it (if it has sufficient
       privileges).

       The term "event" refers to the transition of a device from one state to another. The event
       is named by the state to which the device is transitioning. For instance, if a  device  is
       transitioning  to  the OFFLINE state, the name of the event is CT_DEV_EV_OFFLINE. An event
       may have no consequence for a contract, or it may result in the asynchronous breaking of a
       contract  or  it may result in a synchronous (that is, negotiated) breaking of a contract.
       Events are delivered to a contract holder in three cases:

	   o	  The contract holder has subscribed to the event via the critical or informative
		  event  sets.	The  event  may  be  either  critical or informative in this case
		  depending on the subscription.

	   o	  The device transitions to a state outside the contract's "A-set" and the  tran-
		  sition  is  asynchronous. This results in the asynchronous breaking of the con-
		  tract and a critical event is delivered to the holder.

	   o	  The device transitions to a state outside the contract's "A-set" and the  tran-
		  sition is synchronous. This results in the synchronous breaking of the contract
		  and a critical event with the CTE_NEG flag set is delivered to the holder.

       In the last two cases, a critical event is delivered even if the holder has not subscribed
       to the event via the critical or informative event sets.

   NEGOTIATION
       If the breaking of a contract is synchronous, the kernel begins negotiations with the con-
       tract holder by generating a critical event before the device changes state. The event has
       the  CTE_NEG  flag  set indicating that this is a negotiation event. The contract owner is
       allowed a limited period of time in which to either ACK the contract event (thus, allowing
       the state change) or if it has appropriate privileges, NACK the state change (thus, block-
       ing the state change). ACKs may be sent by the holder via ct_ctl_ack(3CONTRACT) and  NACKs
       may  be	sent via ct_ctl_nack(3CONTRACT). If a contract holder does not send either a NACK
       or ACK within a specified period of time, an ACK is assumed and the kernel  proceeds  with
       the state change.

       Once  the  device  state change is finalized, the contract subsystem sends negotiation end
       (NEGEND) critical messages to the contract owner indicating the final disposition  of  the
       state transition. That is, either success or failure.

       Once  a	contract is broken, a contract owner may choose to create a replacement contract.
       It may do this after the contract is broken or it may choose to do this synchronously with
       the breaking of the old contract via ct_ctl_newct(3CONTRACT).

   TERMS
       The following common contract terms, defined in contract(4), have device-contract specific
       attributes:

       informative set	  The default value for the informative set is CT_DEV_EV_DEGRADE that is,
			  transitions to the DEGRADED state will by default result in informative
			  events. Use ct_tmpl_set_informative(3CONTRACT) to set this term.

       critical set	  The default value for the informative set  is  CT_DEV_EV_OFFLINE.  That
			  is, transitions to the OFFLINE state will by default result in critical
			  events. Use ct_tmpl_set_critical(3CONTRACT) to set this term.

       The following contract terms can be read from or written to  a  device  contract  template
       using  the  named  libcontract(3LIB)  interfaces.  These contract terms are in addition to
       those described in contract(4).

       CTDP_ACCEPT    Acceptable set or "A-set".

		      This term is required for every device contract.	It  defines  the  set  of
		      device states which the contract owner expects to exist as long as the con-
		      tract is valid. If a device transitions to a state  outside  this  "A-set",
		      then  the contract breaks and is no longer valid. A critical contract event
		      is sent to the contract owner to signal this break.

		      Use ct_dev_tmpl_set_aset()  to  set  this  term.	The  default  "A-set"  is
		      CT_DEV_EV_ONLINE	 |   CT_DEV_EV_DEGRADE.   This	term  is  mandatory.  Use
		      ct_dev_tmpl_get_aset() to query a template for this term.

       CTDP_MINOR     Specifies the devfs path to a minor node that is the subject  of	the  con-
		      tract.  Used  to	specify the minor node to be used for creating a contract
		      when contract creation takes place other than at open time.

		      If the contract is created synchronously at open(2) time, then this term is
		      implied to be the minor node being opened. In this case, this term need not
		      be explicitly be set.

		      Use ct_dev_tmpl_set_minor() to set this term. The default setting for  this
		      term is NULL. That is, no minor node is specified.

		      Use  ct_dev_tmpl_get_noneg()  to	query  a template for the setting of this
		      term.

       CTDP_NONEG     If set, this term indicates that any negotiable departure from the contract
		      terms  should  be  NACKed.  That is, the contract subsystem should assume a
		      NACK for any negotiated breaking of the contract. This term is ignored  for
		      asynchronous contract breaks.

		      Use ct_dev_tmpl_set_noneg() to set this term. The default setting is off.

		      Use  ct_dev_tmpl_get_noneg()  to	query  a template for the setting of this
		      term.

   STATUS
       In addition to the standard items, the status object read from a  status  file  descriptor
       contains the following items if CTD_FIXED is specified:

       CTDS_STATE    Returns  the  current  state  of  the device. One of the following states is
		     returned:

			 o	CT_DEV_EV_ONLINE

			 o	CT_DEV_EV_DEGRADED

			 o	CT_DEV_EV_OFFLINE

				Use ct_dev_status_get_dev_state() to obtain this information.

       CTDS_ASET     Returns the acceptable states ("A-set") of the device contract.  The  return
		     value  is	a bitset of device states and may include one or more of the fol-
		     lowing:

			 o	CT_DEV_EV_ONLINE

			 o	CT_DEV_EV_DEGRADED

			 o	CT_DEV_EV_OFFLINE

				Use ct_dev_status_get_aset() to obtain this information.

       CTDS_NONEG    Returns the current setting of the noneg flag. Returns 1 if the  noneg  flag
		     is set, or 0 if the flag is not set. Use ct_dev_status_get_noneg() to obtain
		     this information.

       If CTD_ALL is specified, the following items are also available:

       CTDS_MINOR    The devfs path of the device which is the subject of  the	device	contract.
		     Use ct_dev_status_get_minor() to obtain this information.

   EVENTS
       No  new	event  related	interfaces  (beyond  the  standard contract event interfaces) are
       defined for device contract events.

FILES
       /usr/include/sys/contract/device.h

	   Contains definitions of events, status fields and event fields

SEE ALSO
       ctrun(1),     ctstat(1),     ctwatch(1),     open(2),	 ct_tmpl_set_critical(3CONTRACT),
       ct_tmpl_set_informative(3CONTRACT),			 ct_dev_tmpl_set_aset(3CONTRACT),
       ct_dev_tmpl_get_aset(3CONTRACT), 			ct_dev_tmpl_set_minor(3CONTRACT),
       ct_dev_tmpl_get_minor(3CONTRACT),			ct_dev_tmpl_set_noneg(3CONTRACT),
       ct_dev_tmpl_get_noneg(3CONTRACT),   ct_dev_status_get_dev_state(3CONTRACT),    ct_dev_sta-
       tus_get_aset(3CONTRACT),   ct_dev_status_get_minor(3CONTRACT),	libcontract(3LIB),   con-
       tract(4), privileges(5)

SunOS 5.11				   21 Aug 2007			       device_contract(4)


All times are GMT -4. The time now is 11:10 AM.

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