System Services, $CRMPSC
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
/sys$common/syshlp/helplib.hlb System Services, $CRMPSC *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
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);
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 inadr argument and whether you are using
an Alpha or a VAX system. Refer to the OpenVMS System Services
Reference Manual for a complete description of these differences.
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 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_GBL Pages form a global section. The default is
private section.
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. For page file
sections, the default is demand zero.
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_WRT Pages form a read/write section. By default,
pages form a read-only section. For page file
sections, the default is writeable.
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 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_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_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_NO_ Pages cannot overmap existing address space.
OVERMAP Note that, by default, pages can overmap
existing address space.
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 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 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 and VAX systems, 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 pages (on VAX systems) or pagelets (on Alpha systems)
in the section. The pagcnt argument is a longword containing this
number.
On Alpha systems, the smallest allocation is an Alpha 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 pages, 16384 bytes.
On Alpha systems, if the SEC$M_PFNMAP flag bit is set, the pagcnt
argument is interpreted as CPU-specific pages, not as pagelets.
On Alpha and VAX 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.
Refer to the OpenVMS System Services Reference Manual to view
which arguments are required and which are optional for three
different uses of the $CRMPSC service.
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.
Refer to the OpenVMS System Services Reference Manual to view the
diagram depicting the mask.
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 pages (on VAX
systems) or pagelets (on Alpha systems) are to be brought into
memory when a page fault occurs for a single page.
On Alpha 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 system with an 8KB page size) will be mapped for
each physical page. The system cannot map less than one physical
page.
On VAX systems, this argument is not used for page file sections
or physical page frame sections.
|
|
