Museum

MS_$RELOCK                        Domain/OS                         MS_$RELOCK


NAME
     ms_$relock - change the lock on an object

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/ms.h>

     void ms_$relock(
          void *&address,
          ms_$acc_mode_t &access,
          status_$t *status)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/ms.ins.pas';

     procedure ms_$relock(
          in address: univ_ptr;
          in access: ms_$acc_mode_t;
          out status: status_$t);

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/ms.ins.ftn'

           integer*4 status
           integer*2 access

           integer*4 address, dummy
           pointer /address/ dummy

           call ms_$relock(address, access, status)

DESCRIPTION
     This call changes the lock on the object mapped at address by changing
     its access mode to access.  The object's concurrency is not affected.

     The new access mode combined with the existing concurrency forms a new
     lock.  The following table illustrates how to obtain a desired lock,
     given the existing lock on the object, by requesting the appropriate
     access mode.
              _______________________________________________________
              |            Relocking by Modifying Access             |
              |______________________________________________________|
              | Desired Lock   |  Existing Lock  | Access to Request |
              |________________|_________________|___________________|
              |                | Protected Read  | ms_$wr or ms_$wrx |
              |Exclusive Write |_________________|___________________|
              |                | Protected RIW   | ms_$wr or ms_$wrx |
              |________________|_________________|___________________|
              |Protected Read  | Exclusive Write | ms_$r             |
              |________________|_________________|___________________|
              |                | Exclusive Write | ms_$riw           |
              |Protected RIW   |_________________|___________________|
              |                | Protected Read  | ms_$riw           |
              |________________|_________________|___________________|
              |Shared Read     | Shared Write    | ms_$r or ms_$riw  |
              |________________|_________________|___________________|
              |Shared Write    | Shared Read     | ms_$wr or ms_$wrx |
              |________________|_________________|___________________|

     Note that ms_$relock cannot change a protected "read with intent to
     write" (RIW) lock to a protected read lock by changing the access to
     ms_$r.

     address
          A pointer to the mapped object to relock.

     access
          The new access mode requested for the object.  The requested access
          must be permitted by the protection on the object.  Specify one of
          the following values:

          ms_$r
               Read access.

          ms_$rx
               Read and execute access.

          ms_$wr
               Read and write access.

          ms_$wrx
               Read, write, and execute access.

          ms_$riw
               "Read with intent to write" (RIW) access.

     status
          The completion status.  Ms_$mapl returns with ms_$bad_access in
          status when access is not one of the valid enumerated values.
          Ms_$mapl returns with ms_$not_locked in status when the object at
          address is not already locked by the calling process.  Ms_$mapl
          returns with ms_$not_mapped in status if no object is mapped at
          address.