MS_$MAPL Domain/OS MS_$MAPL
NAME
ms_$mapl - map and lock an object
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/ms.h>
void *ms_$mapl(
char *name,
short int &name_length,
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(
in name: univ name_$pname_t;
in name_length: integer;
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 start, desired_length, length_mapped, status
integer*2 name_length, concurrency, access
logical extend
character name*1023
integer*4 address, dummy
pointer /address/ dummy
address = ms_$mapl(name, name_length, start, desired_length,
& concurrency, access, extend, length_mapped,
& status)
DESCRIPTION
This call maps the file system object at name into the address space of
the calling process and returns a pointer to the mapped portion.
Ms_$mapl locks an object in addition to mapping it. The lock is deter-
mined by the concurrency and access arguments. Ms_$mapl 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, an "N" indicates a
forbidden combination of locks, and an "L" indicates combinations only
permitted 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 |
|________________|___________|___________|________|___________|________|
name The pathname of the object to be mapped.
name_length
The number of bytes in name.
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" (RIW) access.
extend
A Boolean value that indicates whether the object can be extended.
If extend is true, ms_$mapl 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. If extend is true,
length_mapped will be at least desired_length.
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_$in_use in status when the object at name
cannot be locked. Ms_$mapl returns with ms_$no_space in status when
the calling process lacks enough virtual address space to map the
requested object.
SEE ALSO
ms_$crmapl, ms_$crtemp, ms_$mapl_stream, ms_$unmap.