Museum

MS_$ADDMAP                        Domain/OS                         MS_$ADDMAP


NAME
     ms_$addmap - map more of a object

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

     void *ms_$addmap(
          void *&old_address,
          unsigned long int &start,
          unsigned long int &desired_length,
          unsigned long int *mapped_length,
          status_$t *status)

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

     function ms_$addmap(
          in old_address: univ_ptr;
          in start: linteger;
          in desired_length: linteger;
          out mapped_length: linteger;
          out status: status_$t): univ_ptr;

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

           integer*4 start, desired_length, mapped_length, status

           integer*4 address, old_address
           integer*4 dummy1, dummy2
           pointer /address/ dummy1
           pointer /old_address/ dummy2

           address = ms_$addmap(old_address, start, desired_length,
          &                     mapped_length, status)

DESCRIPTION
     This call maps another portion of a previously mapped object.  Unlike
     ms_$remap, it does not change the existing pointer to the mapped object
     but returns a new pointer to a different portion of the object.  The new
     mapping is not necessarily contiguous with the old mapping.

     Attributes of the mapping (extend, access, concurrency) and the lock on
     the mapped object are not changed by ms_$addmap.  Also access advice pro-
     vided via ms_$advice for the old mapping is propagated to the new map-
     ping.

     old_address
          Pointer to the currently mapped portion of the object.  Use the
          pointer returned by the most recent call to ms_$mapl, ms_$crmapl, or
          ms_$remap.

     start
          The first byte of the object to be mapped.

     desired_length
          The number of bytes to map.

     mapped_length
          The number of bytes actually mapped.

     status
          The completion status.  If the pointer passed in old_address does
          not point to a mapped object, ms_$addmap will return with
          ms_$not_mapped in status.  If desired_length cannot be satisfied,
          ms_$addmap will return with ms_$bad_length in status.

NOTES
     A mapped object is not unlocked until the portion first mapped is
     unmapped.  A good strategy is to unmap portions of an object in reverse
     order from the order they were mapped in.  This reverse order unmapping
     strategy also avoids the problem of unlocking and consequently losing a
     temporary object by unmapping the first portion of the object mapped
     before finishing with all subsequently mapped portions.