Museum

MS_$TRUNCATE                      Domain/OS                       MS_$TRUNCATE


NAME
     ms_$truncate - truncate a mapped object

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

     void ms_$truncate(
          void *&address,
          unsigned long int &length,
          status_$t *status)

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

     procedure ms_$truncate(
          in address: univ_ptr;
          in length: linteger;
          out status: status_$t);

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

           integer*4 status, length

           integer*4 address, dummy
           pointer /address/ dummy

           call ms_$truncate(address, length, status)

DESCRIPTION
     This call sets the length attribute of the object mapped at address to
     the size specified in length.

     If a process extends an object it has mapped, the length attribute of the
     object may not reflect the actual length of the extended object when it
     is unmapped.  After unmapping, the length attribute of the extended
     object may be greater or less than the number of bytes of useful data in
     the object.  The inconsistent length may mislead programs that use the
     attribute into supplying meaningless data from the object, or into
     returning an EOF prematurely and preventing access to all of the object's
     data.  To prevent such problems, use ms_$truncate to set the length
     attribute to an appropriate value before unmapping an object that was
     extended while mapped.

     A process may also use ms_$truncate to trim a (possibly overallocated)
     object it has created to an appropriate size before unmapping it.

     address
          A pointer to the mapped object to truncate.

     length
          The desired value of the object's length attribute, in bytes.

     status
          The completion status.

SEE ALSO
     ios_$intro, ms_$attributes.