Allows a process to associate (map) a section of its address
space with either a specified section of a file (a disk file
section) or specified physical addresses represented by page
frame numbers (a page frame section). This service also allows
the process to create either type of section and to specify that
the section be available only to the creating process (private
section) or to all processes that map to it (global section).
Format
SYS$CRMPSC [inadr] ,[retadr] ,[acmode] ,[flags] ,[gsdnam]
,[ident] ,[relpag] ,[chan] ,[pagcnt] ,[vbn] ,[prot]
,[pfc]
C Prototype
int sys$crmpsc (struct _va_range *inadr, struct _va_range
*retadr, unsigned int acmode, unsigned int
flags, void *gsdnam, unsigned int relpag,
unsigned short int chan, unsigned int pagcnt,
unsigned int vbn, unsigned int prot,unsigned
int pfc);
1 – Arguments
inadr
OpenVMS usage:address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses into which the section is
to be mapped. The inadr argument is the address of a 2-longword
array containing, in order, the starting and ending process
virtual addresses. Only the virtual page number portion of each
virtual address is used to specify which pages are to be mapped;
the low-order byte-within-page bits are ignored for this purpose.
The interpretation of the inadr argument depends on the setting
of SEC$M_EXPREG in the flags argument and whether you are
using an Alpha or an Integrity server system. For a complete
description of these differences, see the VSI OpenVMS System
Services Reference Manual.
retadr
OpenVMS usage:address_range
type: longword (unsigned)
access: write only
mechanism: by reference-array reference
Starting and ending process virtual addresses into which the
section was actually mapped by $CRMPSC. The retadr argument
is the address of a 2-longword array containing, in order, the
starting and ending process virtual addresses.
On Alpha and Integrity server systems, the retadr argument
returns starting and ending addresses of the usable range of
addresses. This might differ from the total amount mapped.
The retadr argument is required when the relpag argument is
specified. If the section being mapped does not completely
fill the last page used to map the section, the retadr argument
indicates the highest address that actually maps the section.
If the relpag argument is used to specify an offset into the
section, the retadr argument reflects the offset.
acmode
OpenVMS usage:access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during
the mapping. The acmode argument is a longword containing the
access mode.
The $PSLDEF macro defines the following symbols for the four
access modes:
Symbol Access Mode
PSL$C_KERNEL Kernel
PSL$C_EXEC Executive
PSL$C_SUPER Supervisor
PSL$C_USER User
The most privileged access mode used is the access mode of the
caller.
flags
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the type of section to be created or mapped
to, as well as its characteristics. The flags argument is a
longword bit vector wherein each bit corresponds to a flag.
The $SECDEF macro defines a symbolic name for each flag. You
construct the flags argument by performing a logical OR operation
on the symbol names for all desired flags.
The following table describes each flag and the default value
that it supersedes:
Flag Description
SEC$M_CRF Pages are copy-on-reference. By default, pages
are shared.
SEC$M_DZRO Pages are demand-zero pages. By default, they
are not zeroed when copied.
SEC$M_EXECUTE Pages are mapped if the caller has execute
access. This flag takes effect only (1) when
specified from executive or kernel mode, (2)
when the SEC$M_GBL flag is also specified, and
(3) when SEC$M_WRT is not specified. By default
$CRMPSC performs a read access check against the
section.
SEC$M_EXPREG Pages are mapped into the first available space.
By default, pages are mapped into the range
specified by the inadr argument.
See the inadr argument description for a
complete explanation of how to set the SEC$M_
EXPREG flag.
SEC$M_GBL Pages form a global section. The default is
private section.
SEC$M_NO_ Pages cannot overmap existing address space.
OVERMAP Note that, by default, pages can overmap
existing address space.
SEC$M_PAGFIL Pages form a global page file section. By
default, pages form a disk file section. SEC$M_
PAGFIL also implies SEC$M_WRT and SEC$M_DZRO.
SEC$M_PERM Global section is permanent. By default, global
sections are temporary.
SEC$M_PFNMAP Pages form a page frame section. By default,
pages form a disk file section. Pages mapped
by SEC$M_PFNMAP are not included in or charged
against the process's working set; they are
always valid. Do not lock these pages in the
working set by using $LKWSET; this can result in
a machine check if they are in I/O space.
On Alpha and Integrity server systems, when the
SEC$M_PFNMAP flag is set, the pagcnt and relpag
arguments are interpreted in CPU-specific pages,
not as pagelets.
SEC$M_SYSGBL Pages form a system global section. By default,
pages form a group global section.
SEC$M_UNCACHED Flag that must be set when a PFN-mapped section
is created if this section is to be treated
as uncached memory. Flag is ignored on Alpha
systems; it applies only to Integrity server
systems.
SEC$M_WRT Pages form a read/write section. By default,
pages form a read-only section.
gsdnam
OpenVMS usage:section_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the global section. The gsdnam argument is the address of
a character string descriptor pointing to this name string.
For group global sections, the operating system interprets the
UIC group as part of the global section name; thus, the names of
global sections are unique to UIC groups.
You can specify any name from 1 to 43 characters. All processes
mapping to the same global section must specify the same name.
Note that the name is case sensitive.
Use of characters valid in logical names is strongly encouraged.
Valid values include alphanumeric characters, the dollar sign
($), and the underscore (_). If the name string begins with an
underscore (_), the underscore is stripped and the resultant
string is considered to be the actual name. Use of the colon (:)
is not permitted.
Names are first subject to a logical name translation, after
the application of the prefix GBL$ to the name. If the result
translates, it is used as the name of the section. If the
resulting name does not translate, the name specified by the
caller is used as the name of the section.
Additional information on logical name translations and
on section name processing is available in the VSI OpenVMS
Programming Concepts Manual.
ident
OpenVMS usage:section_id
type: quadword (unsigned)
access: read only
mechanism: by reference
Identification value specifying the version number of a global
section and, for processes mapping to an existing global section,
the criteria for matching the identification. The ident argument
is the address of a quadword structure containing three fields.
The version number is in the second longword. The version number
contains two fields: a minor identification in the low-order 24
bits and a major identification in the high-order 8 bits. You
can assign values for these fields by installation convention to
differentiate versions of global sections. If no version number
is specified when a section is created, processes that specify a
version number when mapping cannot access the global section.
The first longword specifies, in its low-order two bits, the
matching criteria. The valid values, symbolic names by which they
can be specified, and their meanings are as follows:
Value/Name Match Criteria
0 SEC$K_MATALL Match all versions of the section.
1 SEC$K_MATEQU Match only if major and minor identifications
match.
2 SEC$K_MATLEQ Match if the major identifications are equal and
the minor identification of the mapper is less
than or equal to the minor identification of the
global section.
When a section is mapped at creation time, the match control
field is ignored.
If you do not specify the ident argument or specify it as 0 (the
default), the version number and match control fields default to
0.
relpag
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Relative page number within the global section of the first page
in the section to be mapped. The relpag argument is a longword
containing this page number.
On Alpha and Integrity server systems, the relpag argument
is interpreted as an index into the section file, measured in
pagelets for a file-backed section or in CPU-specific pages for a
PFN-mapped section.
On Alpha or Integrity servers, you use this argument only for
global sections. If you do not specify the relpag argument or
specify it as 0 (the default), the global section is mapped
beginning with the first virtual block in the file.
chan
OpenVMS usage:channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the channel on which the file has been accessed. The
chan argument is a word containing this number.
The file must have been accessed with the OpenVMS RMS macro
$OPEN; the file options parameter (FOP) in the FAB must indicate
a user file open (UFO keyword). The access mode at which the
channel was opened must be equal to or less privileged than the
access mode of the caller.
pagcnt
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of pagelets in the section. The pagcnt argument is a
longword containing this number.
On Alpha and Integrity server systems, the smallest allocation
is an Alpha or Integrity servers page, which is 8192 bytes. When
requesting pagelets, the size requested is a multiple of 512
bytes, but the actual allocation is rounded to 8192. For example,
when requesting 17 pagelets, the allocation is for two Alpha or
Integrity servers pages, 16384 bytes.
On Alpha and Integrity server systems, if the SEC$M_PFNMAP flag
bit is set, the pagcnt argument is interpreted as CPU-specific
pages, not as pagelets.
On Alpha or Integrity server systems , the specified page count
is compared with the number of blocks in the section file;
if they are different, the lower value is used. If you do not
specify the page count or specify it as 0 (the default), the size
of the section file is used. However, for physical page frame
sections, this argument must not be 0.
vbn
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Virtual block number in the file that marks the beginning of the
section. The vbn argument is a longword containing this number.
If you do not specify the vbn argument or specify it as 0 (the
default), the section is created beginning with the first virtual
block in the file.
If you specified page frame number mapping (by setting the SEC$M_
PFNMAP flag), the vbn argument specifies the CPU-specific page
frame number where the section begins in memory.
To view which arguments are required and which are optional for
three different uses of the $CRMPSC service, see the VSI OpenVMS
System Services Reference Manual.
prot
OpenVMS usage:file_protection
type: longword (unsigned)
access: read only
mechanism: by value
Protection to be applied to the global page file and PFN
sections. For file-backed sections, the protection is taken from
the backing file and the prot argument is ignored.
The mask contains four 4-bit fields. Bits are read from right to
left in each field.
To view the diagram depicting the mask, see the VSI OpenVMS System
Services Reference Manual.
Cleared bits indicate that read, write, execute, and delete
access, in that order, are granted to the particular category
of user.
Only read, write, and execute access are meaningful for section
protection. Delete access bits are ignored. Read access also
grants execute access for those situations where execute access
applies.
Protection is taken from the system or group global section
template for page file or PFN global sections if the prot
argument is not specified.
pfc
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Page fault cluster size indicating how many pagelets are to be
brought into memory when a page fault occurs for a single page.
On Alpha and Integrity server systems, this argument is not used
for page file sections or physical page frame sections. The pfc
argument is rounded up to CPU-specific pages. That is, at least
16 pagelets (on an Alpha or Integrity servers system with an
8KB page size) will be mapped for each physical page. The system
cannot map less than one physical page.