Windows PowerShell command on Get-command device

Manual Pages for UNIX Operating System command usage for man device_contract

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 sys-

tem 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 template, setting appropri-

ate 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 sub-

ject 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 con-

figured 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

SunOS 5.11 Last change: 21 Aug 2007 1

File Formats device_contract(4)

"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 con-

tract 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 synchro-

nous or asynchronous.

If the breaking of a contract is asynchronous, then a criti-

cal 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 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 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, nego-

tiated) 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 transition is asynchro-

nous. 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 synchro-

nous. This results in the synchronous breaking of

the contract and a critical event with the CTE_NEG

SunOS 5.11 Last change: 21 Aug 2007 2

File Formats device_contract(4)

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 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 negotia-

tion 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, 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 sub-

system 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 con-

tract 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, transi-

tions to the OFFLINE state will by default result in critical events. Use

SunOS 5.11 Last change: 21 Aug 2007 3

File Formats device_contract(4)

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 con-

tract. 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 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 tem-

plate 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 creat-

ing 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 tem-

plate for the setting of this term.

CTDP_NONEG If set, this term indicates that any negoti-

able 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

SunOS 5.11 Last change: 21 Aug 2007 4

File Formats device_contract(4)

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 tem-

plate 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 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 avail-

able:

SunOS 5.11 Last change: 21 Aug 2007 5

File Formats device_contract(4)

CTDS_MINOR The devfs path of the device which is the sub-

ject of the device contract. Use

ct_dev_status_get_minor() to obtain this

information. EVENTS

No new event related interfaces (beyond the standard con-

tract event interfaces) are defined for device contract events. FILES /usr/include/sys/contract/device.h Contains definitions of events, status fields and event fields

Manual Pages for UNIX Operating System command usage for man device_contract

File Formats device_contract(4)

NAME

device_contract - device contract type

SYNOPSIS

DESCRIPTION

File Formats device_contract(4)

File Formats device_contract(4)

File Formats device_contract(4)

File Formats device_contract(4)

File Formats device_contract(4)

SEE ALSO