MS_$INTRO Domain/OS MS_$INTRO
NAME
intro - mapping file system objects
SYNOPSIS (C)
#include <apollo/base.h>
#include <apollo/ms.h>
SYNOPSIS (Pascal)
%include '/sys/ins/base.ins.pas';
%include '/sys/ins/ms.ins.pas';
SYNOPSIS (FORTRAN)
%include '/sys/ins/base.ins.ftn'
%include '/sys/ins/ms.ins.ftn'
DESCRIPTION
The ms_$ calls map and unmap file system objects. When a process maps an
object, the system places the requested pages of the object within the
virtual address space of the process. The object is paged in as the pro-
cess references addresses that resolve to mapped portions of the object.
The following is a list of the ms_$ calls.
ms_$addmap map more of an object
ms_$addmapx map more of an object, specifying location
ms_$advice advise the system on mapped object access
ms_$attributes get the file attributes of a mapped object
ms_$crmapl create, map, and lock an object
ms_$crtemp create, map, and lock a temporary object
ms_$fw_file synchronize a mapped object with the file sys-
tem
ms_$fw_partial partially synchronize a mapped object with the
file system
ms_$mapl map and lock an object
ms_$mapl_stream permanently map an object via its XOID
ms_$maplx map objects external to the Apollo file system
ms_$mk_permanent make a temporary object permanent
ms_$mk_temporary make a permanent object temporary
ms_$neighbors find out if two mapped objects are on the same
volume
ms_$relock change the lock on an object
ms_$remap map a different portion of a mapped object
ms_$reprotect change protection on a mapped object
ms_$truncate truncate a mapped object
ms_$unmap unmap an object
Constants
ms_$extend
The object can be extended.
ms_$map_from_bottom
The object should be mapped starting near the bottom of free memory.
ms_$map_from_top
The object should be mapped starting near the top of free memory.
ms_$no_extend
The object cannot be extended.
Data Types
ms_$acc_mode_t
An enumerated type for describing the access mode for an object. It
takes one of the following values:
ms_$nil_access
No access.
ms_$r
Read access.
ms_$riw
"Read with intent to write" (RIW) access.
ms_$rx
Read and execute access.
ms_$w
Write access.
ms_$wr
Read and write access.
ms_$wrx
Read, write, and execute access.
ms_$x
Execute access.
ms_$access_t
An enumerated type for specifying the usage patterns for accessing a
file. It takes one of the following values:
ms_$normal
Normal access.
ms_$random
Random access.
ms_$sequential
Sequential access.
ms_$advice_opt_t
Reserved for future use with ms_$advice. In Pascal, specify an
empty set for arguments of this type. In C and FORTRAN, set
ms_$advice_opt_t arguments to 0.
ms_$advice_t
Four bytes that are reserved for future use.
ms_$attrib_t
An attribute record. The diagram below illustrates the ms_$attrib_t
data type:
175 168 167 160
______________________________________________________________
| permanent | immutable |
|_____________________________________________________________|
| cur_len |
|_____________________________________________________________|
| cur_len |
|_____________________________________________________________|
| blocks_used |
|_____________________________________________________________|
| blocks_used |
|_____________________________________________________________|
| dtu |
|_____________________________________________________________|
| dtu |
|_____________________________________________________________|
| dtm |
|_____________________________________________________________|
| dtm |
|_____________________________________________________________|
| dtcr |
|_____________________________________________________________|
| dtcr |
______________________________________________________________
15 0
permanent
A Boolean value that indicates whether the object is permanent
(true) or temporary (false).
immutable
A Boolean value that indicates whether the object can be modi-
fied. The value true means that the object is immutable. The
value false means that the object is not immutable and can
therefore be modified.
cur_len
The current length in bytes of the object.
blocks_used
The number of blocks used for the object.
dtu Date and time the object was last used, in time_$clockh_t for-
mat.
dtm Date and time the object was last modified, in time_$clockh_t
format.
dtcr Date and time the object was created, in time_$clockh_t format.
ms_$conc_mode_t
An enumerated type for specifying the concurrency mode for an
object. It takes 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/or writers.
ms_$none
No lock at all is applied to the object; the application is
responsible for maintaining consistency itself. Applications
should avoid using this option if at all possible.
ms_$map_flags_set_t
A type for specifying mapping options to ms_$maplx. Takes one or
more of the following values:
ms_$keep_on_exec
The requested mapping should be preserved across exec() system
calls. By default, mappings are released when an exec() call
occurs.
ms_$ok_to_extend
The object being mapped may be extended (grow longer) as a
result of accesses via this mapping.
ms_$no_pager
The operating system should not invoke an external pager to
establish a mapping to a non-native object.
ms_$anon
Requests that a mapping to a temporary, anonymous VM object is
established. If this flag is specified to ms_$maplx, a nil
pathname should be supplied. It is meaningless to specify
ms_$ok_to_extend with this flag.
ms_$share
Requests that anonymous mappings be shared across process
forks. By default, ms_$anon mappings are copied across a fork:
the child gets a copy of the parent's mapping, but the parent
and child do not see changes in the mapping made by the other.
If ms_$share is specified, the mapping is instead shared across
a fork: the parent and child share the same mapping, and
changes made by one are propagated to the other.
ms_$perm_opt_t
An enumerated type for specifying options to ms_$mk_permanent. It
takes one of the following values:
ms_$mk_bak
Make a backup copy of file.
xoid_$t
An extended unique identifier (XOID) for an object. Values of this
type are normally used only by type managers.
127 112
______________________________________________________________
| reserved |
|_____________________________________________________________|
| reserved |
|_____________________________________________________________|
| reserved |
|_____________________________________________________________|
| reserved |
|_____________________________________________________________|
| uid |
|_____________________________________________________________|
| uid |
|_____________________________________________________________|
| uid |
|_____________________________________________________________|
| uid |
______________________________________________________________
15 0
reserved
Reserved for the I/O Switch and type manager.
uid A unique identifier for an object. This element has type
uid_$t.
Errors
ms_$bad_access
Unsupported access rights requested.
ms_$bad_length
Bad length specified.
ms_$different_volumes
One of the pointers passed to ms_$neighbors points to a mapped
object that is locked by a process on another node.
ms_$external_object
The object is mounted on an external (non-Domain/OS) file system.
ms_$in_use
Object is locked by another process or is in an incompatible mode.
ms_$insufficient_rights
The calling process has some rights to the object, but not the ones
it requested.
ms_$name_not_found
No object exists with the given name.
ms_$no_rights
The calling process has no rights to the requested object.
ms_$no_space
There is not enough virtual address space available for the process
to map the requested object.
ms_$not_locked
The object specified to ms_$relock is not locked by the calling pro-
cess.
ms_$not_mapped
No object is mapped at the virtual address supplied.
ms_$not_temp
The object specified to ms_$mk_permanent is already permanent.
ms_$object_not_found
The object does not exist, or it is not accessible over the network.
ms_$wrong_level
The calling process attempted to release an object mapped by the
previous program level.
ms_$wrong_object_type
The object is of the wrong type to be mapped. Files are the only
file-system objects that can be mapped.