MS_$MAPL_STREAM Domain/OS MS_$MAPL_STREAM
NAME
ms_$mapl_stream - permanently map an object via its XOID
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/ms.h>
void *ms_$mapl_stream(
xoid_$t &xoid,
unsigned long int &start,
unsigned long int &desired_length,
ms_$conc_mode_t &concurrency,
ms_$acc_mode_t &access,
boolean &extend,
unsigned long int *length_mapped,
status_$t *status)
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/ms.ins.pas';
function ms_$mapl_stream(
in xoid: xoid_$t;
in start: linteger;
in desired_length: linteger;
in concurrency: ms_$conc_mode_t;
in access: ms_$acc_mode_t;
in extend: boolean;
out length_mapped: linteger;
out status: status_$t): univ_ptr;
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/ms.ins.ftn'
integer*4 xoid(4), uid(2), start,
integer*4 desired_length, length_mapped, status
integer*2 concurrency, access
logical extend
equivalence (xoid(3), uid(1))
integer*4 address, dummy
pointer /address/ dummy
address = ms_$mapl_stream(xoid, start, desired_length,
& concurrency, access, extend,
& length_mapped, status)
DESCRIPTION
This call maps the file system object with the Extended Object Identifier
xoid into the address space of the calling process and returns a pointer
to the mapped portion. Because it accesses an object via its Extended
Object Identifier (XOID), ms_$mapl_stream is primarily for use in type
managers.
The mapped portion will not be released during a subsequent SysV or BSD
exec(2) call (execl, execle, execlp, exect, execv, execve, or execvp).
The executed program retains objects mapped by ms_$mapl_stream in its
address space, and the executed program can access the mapped object via
pointers passed in the exec(2) call. Conversely, objects mapped with
ms_$mapl are unmapped during an exec(2), and the executed program cannot
access them directly without first remapping them.
Ms_$mapl_stream locks an object in addition to mapping it. The lock is
determined by the concurrency and access arguments. Ms_$mapl_stream can
obtain the following types of locks:
______________________________________________________________
| Types of Locks Available |
|_____________________________________________________________|
| Lock | Concurrency | Access |
|________________|_______________|____________________________|
|Protected Read | ms_$nr_xor_1w | ms_$r or ms_$rx |
|________________|_______________|____________________________|
|Protected RIW | ms_$nr_xor_1w | ms_$riw |
|________________|_______________|____________________________|
|Shared Read | ms_$cowriters | ms_$r or ms_$rx or ms_$riw |
|________________|_______________|____________________________|
|Exclusive Write | ms_$nr_xor_1w | ms_$wr or ms_$wrx |
|________________|_______________|____________________________|
|Shared Write | ms_$cowriters | ms_$wr or ms_$wrx |
|________________|_______________|____________________________|
Once a process has locked an object, the system allows other processes to
map the object only if they request a lock that is compatible with exist-
ing locks. The following table describes compatible lock combinations.
A "Y" indicates a compatible combination of locks, a "N" indicates a for-
bidden combination of locks, and a "L" indicates combinations only per-
mitted when locking processes run on the same node.
_______________________________________________________________________
| Lock Compatibility |
|______________________________________________________________________|
| | Requested Lock |
| |_____________________________________________________|
| Existing Lock | Protected | Protected | Shared | Exclusive | Shared |
| | Read | RIW | Read | Write | Write |
|________________|___________|___________|________|___________|________|
|Protected Read | Y | Y | Y | N | N |
|________________|___________|___________|________|___________|________|
|Protected RIW | Y | N | Y | N | N |
|________________|___________|___________|________|___________|________|
|Shared Read | Y | Y | Y | N | L |
|________________|___________|___________|________|___________|________|
|Exclusive Write | N | N | N | N | N |
|________________|___________|___________|________|___________|________|
|Shared Write | N | N | L | N | L |
|________________|___________|___________|________|___________|________|
xoid The XOID of the object to map.
start
The first byte of the object to map. To map from the beginning of
an object, provide a start value of 0.
desired_length
The number of bytes in the object to map.
concurrency
The concurrency mode requested for the object. Specify one of the
following values:
ms_$nr_xor_1w
Allow one writer or any number of readers.
ms_$cowriters
Allow any number of readers and writers.
access
The 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" access.
extend
A Boolean value that indicates whether the object can be extended.
If extend is true, ms_$mapl_stream returns a pointer to at least
desired_length bytes even if the object is shorter. Writing beyond
the current length of the object, but within the mapped portion,
extends the object. If extend is false, writing beyond the current
length of the object will not extend the length of the object.
length_mapped
The number of bytes actually mapped by ms_$mapl_stream. If extend
is true, length_mapped will be at least desired_length.
status
The completion status. Ms_$mapl_stream returns with ms_$bad_access
in status when access is not one of the valid enumerated values.
Ms_$mapl_stream returns with ms_$in_use in status when the object at
name cannot be locked. Ms_$mapl_stream returns with ms_$no_space in
status when the calling process lacks enough virtual address space
to map the requested object.
SEE ALSO
ios_$intro, ms_$crmapl, ms_$crtemp, ms_$mapl, ms_$unmap.