device_contract man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

DEVICE_CONTRACT(4)					    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 /sys‐
       tem/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  cre‐
		  ates	a  contract  based  on the terms in the activated tem‐
		  plate.

	   o	  A process may create a contract after it has opened a device
		  by creating a template, 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 con‐
       tract is valid. This acceptable set (or "A-set", for short)  is	speci‐
       fied 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 syn‐
       chronous,  depending on whether the transition 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 subscribed 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 acknowl‐
       edge (ACK) this change and allow the state change to occur  or  it  may
       negatively  acknowledge (NACK) the change to block it (if it has suffi‐
       cient 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 transi‐
       tioning.	 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 break‐
       ing  of	a contract or it may result in a synchronous (that is, negoti‐
       ated) 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 sub‐
		  scription.

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

	   o	  The device transitions to a state outside the contract's "A-
		  set" and the transition 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 negoti‐
       ations  with  the contract 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 lim‐
       ited 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, blocking 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 indi‐
       cating 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 con‐
       tract 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  OFF‐
			  LINE	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 contract is valid.
		      If a device transitions to a state outside this "A-set",
		      then the contract breaks and is no longer valid. A crit‐
		      ical 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 contract. Used to specify the minor node
		      to be used for creating a contract  when	contract  cre‐
		      ation 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 depar‐
		      ture 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  fol‐
		     lowing 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 following:

			 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(3CON‐
       TRACT),	ct_tmpl_set_informative(3CONTRACT), ct_dev_tmpl_set_aset(3CON‐
       TRACT),	ct_dev_tmpl_get_aset(3CONTRACT),   ct_dev_tmpl_set_minor(3CON‐
       TRACT),	ct_dev_tmpl_get_minor(3CONTRACT),  ct_dev_tmpl_set_noneg(3CON‐
       TRACT),		ct_dev_tmpl_get_noneg(3CONTRACT),	   ct_dev_sta‐
       tus_get_dev_state(3CONTRACT),	    ct_dev_status_get_aset(3CONTRACT),
       ct_dev_status_get_minor(3CONTRACT),   libcontract(3LIB),	  contract(4),
       privileges(5)

				 Aug 21, 2007		    DEVICE_CONTRACT(4)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net