unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

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



       netgotiation 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



SEE ALSO
       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)



SunOS 5.10                        8 Oct 2004                       contract(4)