 |
OpenVMS System Services Reference Manual
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.
Description
The Create and Map Section service allows a process to associate (map)
a section of its address space with (1) a specified section of a file
(a disk file section) or (2) 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).
Creating a disk file section involves defining all or part of a disk
file as a section. Mapping a disk file section involves making a
correspondence between virtual blocks in the file and pages (on VAX
systems) or pagelets (on Alpha systems) in the caller's virtual address
space. If the $CRMPSC service specifies a global section that already
exists, the service maps it.
Any section created is created as entire pages. Refer to the memory
management section in the OpenVMS Programming Concepts Manual.
Depending on the actual operation requested, certain arguments are
required or optional. Table SYS-6 summarizes how the $CRMPSC service
interprets the arguments passed to it and under what circumstances it
requires or ignores arguments.
The $CRMPSC service returns the virtual addresses of the virtual
address space created in the retadr argument, if
specified. The section is mapped from a low address to a high address,
whether the section is mapped in the program or control region.
If an error occurs during the mapping of a global section, the
retadr argument, if specified, indicates the pages
that were successfully mapped when the error occurred. If no pages were
mapped, the value of the longwords is indeterminate. In this case,
either both longwords of the retadr argument will
contain the value --1, or the value of the longwords will be unaltered.
The SEC$M_PFNMAP flag setting identifies the memory for the section as
starting at the page frame number specified in the vbn
argument and extending for the number of CPU-specific pages specified
in the pagcnt argument. Setting the SEC$M_PFNMAP flag
places restrictions on the following arguments:
| Argument |
Restriction |
|
chan
|
Must be 0
|
|
pagcnt
|
Must be specified; cannot be 0
|
|
vbn
|
Specifies first page frame to be mapped
|
|
pfc
|
Does not apply
|
|
SEC$M_CRF
|
Must be 0
|
|
SEC$M_DZRO
|
Must be 0
|
|
SEC$M_PERM
|
Must be 1 if the flags SEC$M_GBL or SEC$M_SYSGBL are set
|
Setting the SEC$M_PAGFIL flag places the following restrictions on the
following flags:
| Flag |
Restriction |
|
SEC$M_CRF
|
Must be 0
|
|
SEC$M_DZRO
|
Assumed to be 0
|
|
SEC$M_GBL
|
Must be 1
|
|
SEC$M_PFNMAP
|
Must be 0
|
|
SEC$M_WRT
|
Assumed to be 0
|
The flags argument bits 4 through 13 and 18 through 31
must be 0.
If the global section is mapped to a file (neither SEC$M_PAGFIL nor
SEC$M_PFNMAP is set), the security profile of the file is used to
determine access to the global section.
On VAX systems, by default, the initial security profile created for a
page file or PFN global section is taken from the group global section
template. If the SEC$M_SYSGBL flag is set, the profile is taken from
the system global section template. The owner is then set to the
process UIC. If the prot argument is nonzero, it
replaces the protection mask from the template.
On Alpha and VAX systems, the flag bit SEC$M_WRT applies only to the
way in which the newly created section is mapped. For a file to be made
writable, the channel used to open the file must allow write access to
the file.
If the flag bit SEC$M_SYSGBL is set, the flag bit SEC$M_GBL must be set
also.
Required Access or Privileges
If $CRMPSC specifies a global section and the SS$_NOPRIV condition
value is returned, the process does not have the required privilege to
create that section. To create global sections, the process must have
the following privileges:
- SYSGBL privilege to create a system global section
- PRMGBL privilege to create a permanent global section
- PFNMAP privilege to create a page frame section
- SHMEM privilege to create a global section in memory shared by
multiple processors (VAX only)
Note that you do not need PFNMAP privilege to map an existing page
frame section.
Required Quota
If the section pages are copy-on-reference, the process must have
sufficient paging file quota (PGFLQUOTA). The systemwide number of
global page file pages is limited by the system parameter GBLPAGFIL.
Related Services
$ADJSTK, $ADJWSL, $CRETVA, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG, $LKWSET,
$MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC,
$UPDSECW
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully. The specified global section
already exists and has been mapped.
|
|
SS$_CREATED
|
The service completed successfully. The specified global section did
not previously exist and has been created.
|
|
SS$_ACCVIO
|
The
inadr argument,
gsdnam argument, or name descriptor cannot be read by
the caller; the
inadr argument was omitted; or the
retadr argument cannot be written by the caller.
|
|
SS$_ENDOFFILE
|
The starting virtual block number specified is beyond the logical
end-of-file, or the value in the
relpag argument is greater than or equal to the actual
size of the global section.
|
|
SS$_EXBYTLM
|
The process has exceeded the byte count quota; the system was unable to
map the requested file.
|
|
SS$_EXGBLPAGFIL
|
The process has exceeded the systemwide limit on global page file
pages; no part of the section was mapped.
|
|
SS$_EXQUOTA
|
The process exceeded its paging file quota while creating
copy-on-reference or page file backing store pages.
|
|
SS$_GPTFULL
|
There is no more room in the system global page table to set up page
table entries for the section.
|
|
SS$_GSDFULL
|
There is no more room in the system space allocated to maintain control
information for global sections.
|
|
SS$_ILLPAGCNT
|
The page count value is negative or is 0 for a physical page frame
section.
|
|
SS$_INSFMEM
|
Not enough pages are available in the specified shared memory to create
the section.
|
|
SS$_INSFWSL
|
The process's working set limit is not large enough to accommodate the
increased size of the address space.
|
|
SS$_IVCHAN
|
An invalid channel number was specified, that is, a channel number of 0
or a number larger than the number of channels available.
|
|
SS$_IVCHNLSEC
|
The channel number specified is currently active.
|
|
SS$_IVLOGNAM
|
The specified global section name has a length of 0 or has more than 43
characters.
|
|
SS$_IVLVEC
|
The specified section was not installed using the /PROTECT qualifier.
|
|
SS$_IVSECFLG
|
An invalid flag, a reserved flag, a flag requiring a privilege you
lack, or an invalid combination of flags was specified.
|
|
SS$_IVSECIDCTL
|
The match control field of the global section identification is invalid.
|
|
SS$_NOPRIV
|
The process does not have the privileges to create a system global
section (SYSGBL) or a permanent group global section (PRMGBL).
The process does not have the privilege to create a section
starting at a specific physical page frame number (PFNMAP).
The process does not have the privilege to create a global section
in memory shared by multiple processors (SHMEM).
A page in the input address range is in the system address space.
The specified channel is not assigned or was assigned from a more
privileged access mode.
|
|
SS$_NOSHPTS
|
A virtual address within a shared page table region was specified.
|
|
SS$_NOTFILEDEV
|
The device is not a file-oriented, random-access, or directory device.
|
|
SS$_NOWRT
|
The section cannot be written to because the flag bit SEC$M_WRT is set,
the file is read only, and the flag bit SEC$M_CRF is not set.
|
|
SS$_PAGOWNVIO
|
A page in the specified input address range is owned by a more
privileged access mode.
|
|
SS$_SECREFOVF
|
The maximum number of references for a global section has been reached
(2,147,483,647).
|
|
SS$_SECTBLFUL
|
There are no entries available in the system global section table or in
the process section table.
|
|
SS$_TOOMANYLNAM
|
The logical name translation of the
gsdnam argument exceeded the allowed depth.
|
|
SS$_VA_IN_USE
|
A page in the specified input address range is already mapped, and the
flag SEC$M_NO_OVERMAP is set, or the existing underlying page cannot be
deleted because it is associated with a buffer object.
|
|
SS$_VASFULL
|
The process's virtual address space is full; no space is available in
the page tables for the pages created to contain the mapped global
section.
|
$CRMPSC_FILE_64 (Alpha Only)
On Alpha systems, allows a process to map a section of its address
space to a specified portion of a file. This service creates and maps a
private disk file section.
This service accepts 64-bit addresses.
Format
SYS$CRMPSC_FILE_64 region_id_64 ,file_offset_64 ,length_64 ,chan
,acmode ,flags ,return_va_64 ,return_length_64 [,fault_cluster
[,start_va_64]]
C Prototype
int sys$crmpsc_file_64 (struct _generic_64 *region_id_64, unsigned
__int64 file_offset_64, unsigned __int64 length_64, unsigned short int
chan, unsigned int acmode, unsigned int flags, void *(*(return_va_64)),
unsigned __int64 *return_length_64,...);
Arguments
region_id_64
| OpenVMS usage: |
region identifier |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
The region ID associated with the region to map the private disk file
section. The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in
STARLET.MLB define a symbolic name for each of the three default
regions in P0, P1, and P2 space.
The following region IDs are defined:
| Symbol |
Region |
|
VA$C_P0
|
Program region
|
|
VA$C_P1
|
Control region
|
|
VA$C_P2
|
64-bit program region
|
Other region IDs, as returned by the $CREATE_REGION_64 service, can be
specified.
file_offset_64
| OpenVMS usage: |
byte offset |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Byte offset into the file that marks the beginning of the section. The
file_offset_64 argument is a quadword containing this
number. If you specify the file_offset_64 argument as
0, the section is created beginning with the first byte in the file.
The file_offset_64 argument must be a multiple of
virtual disk blocks.
length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
value |
Length, in bytes, of the private disk file section to be created and
mapped to. The length specified must be 0 or a multiple of virtual disk
blocks. If the length specified is 0 or extends beyond end-of-file
(EOF), the disk file is mapped up to and including the virtual block
number that contains EOF.
chan
| OpenVMS usage: |
longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the channel on which the file has been accessed. The
chan argument is a longword containing this number.
The access mode at which the channel was opened must be equal to or
less privileged than the access mode of the caller.
Use the OpenVMS Record Management Services (RMS) macro $OPEN to access
a file; the file options parameter in the file access block must
indicate a user file open (UFO) keyword.
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 in STARLET.MLB and the file PSLDEF.H in
SYS$STARLET_C.TLB define the following symbols and their values for the
four access modes:
| Value |
Symbolic Name |
Access Mode |
|
0
|
PSL$C_KERNEL
|
Kernel
|
|
1
|
PSL$C_EXEC
|
Executive
|
|
2
|
PSL$C_SUPER
|
Supervisor
|
|
3
|
PSL$C_USER
|
User
|
The most privileged access mode used is the access mode of the caller.
The calling process can delete pages only if those pages are owned by
an access mode equal to or less privileged than the access mode of the
calling process.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flag mask specifying the characteristics of the private section to be
created. The flags argument is a longword bit vector
in which each bit corresponds to a flag. The $SECDEF macro and the
SECDEF.H file define 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 that is valid for the
$CRMPSC_FILE_64 service:
| Flag |
Description |
|
SEC$M_CRF
|
Pages are copy-on-reference.
|
|
SEC$M_DZRO
|
Pages are demand-zero pages. By default, they are not zeroed when
copied.
Note that SEC$M_DZRO and SEC$M_CRF cannot both be set and that
SEC$M_DZRO set and SEC$M_WRT clear is an invalid combination.
|
|
SEC$M_EXPREG
|
Pages are mapped into the first available space at the current end of
the specified region.
|
|
SEC$M_NO_OVERMAP
|
Pages cannot overmap existing address space. By default, pages can
overmap existing address space.
|
|
SEC$M_WRT
|
Pages form a read/write section. By default, pages form a read-only
section.
|
All other bits in the flags argument are reserved for
future use by Compaq and should be specified as 0. The condition value
SS$_IVSECFLG is returned if any undefined bits are set or if an illegal
combination of flags is set.
return_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The lowest process virtual address into which the private disk file
section was mapped. The return_va_64 argument is the
32- or 64-bit virtual address of a naturally aligned quadword into
which the service returns the virtual address.
return_length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The 32- or 64-bit virtual address of a naturally aligned quadword into
which the service returns the length of the usable virtual address
range mapped in bytes. This length might differ from the total amount
mapped. If the section being mapped does not completely fill the last
page used to map the section, the return_va_64 and
return_length_64 arguments indicate the highest
address that actually maps the section.
fault_cluster
| OpenVMS usage: |
byte count |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Page fault cluster in byte units indicating how many pages are to be
brought into memory when a page fault occurs for a single page. The
fault cluster specified will be rounded up to a multiple of
CPU-specific pages.
If this argument is specified as 0, the process default page fault
cluster will be used. If this argument is specified as more than the
maximum allowed for the system, no condition value will be returned.
The systemwide maximum will be used.
start_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
read only |
| mechanism: |
by value |
The starting virtual address to map the private disk file section. The
specified virtual address must be a CPU-specific page aligned address.
If the flag SEC$M_EXPREG is specified, the start_va_64
argument must not be specified or must be specified as 0. If
SEC$M_EXPREG is set and the start_va_64 argument is
nonzero, the condition value SS$_IVSECFLG is returned.
Description
The Create and Map Private Disk File Section service allows a process
to create a map to a private disk file section. Creating a private disk
file section involves mapping all or part of a disk file as a section.
The section is mapped from a low address to a high address whether the
section is mapped in a region that grows from low to high addresses or
from high to low addresses.
The flag SEC$M_WRT applies only to the way in which the newly created
section is mapped. For a file to be made writable, the channel used to
open the file must allow write access to the file.
If the condition value SS$_ACCVIO is returned by this service, a value
cannot be returned in the memory locations pointed to by the
return_va_64 and return_length_64
arguments.
If a condition value other than SS$_ACCVIO is returned, the returned
address and returned length indicate the pages that were successfully
mapped before the error occurred. If no pages were mapped, the
return_va_64 argument will contain the value --1, and
a value cannot be returned in the memory location pointed to
by the return_length_64 argument.
Required Privileges
None
Required Quota
The working set quota (WSQUOTA) of the process must be sufficient to
accommodate the increased length of the process page table required by
the increase in virtual address space.
The process must have sufficient byte count quota to satisfy the
request.
If the section pages are copy-on-reference, the process must have
sufficient paging file quota (PGFLQUOTA).
Related Services
$CREATE_REGION_64, $CRMPSC, $CRMPSC_GFILE_64, $CRMPSC_GPFILE_64,
$CRMPSC_GPFN_64, $CRMPSC_PFN_64, $DELETE_REGION_64, $DELTVA_64,
$LCKPAG_64, $LKWSET_64, $PURGE_WS, $SETPRT_64, $ULKPAG_64, $ULWSET_64,
$UPDSEC_64, $UPDSEC_64W
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
return_va_64 argument or the
return_length_64 argument cannot be written by the
caller.
|
|
SS$_CHANVIO
|
The specified channel was assigned from a more privileged access mode.
|
|
SS$_ENDOFFILE
|
The
file_offset_64 argument specified is beyond the
logical end-of-file.
|
|
SS$_EXBYTLM
|
The process has exceeded the byte count quota; the system was unable to
map the requested file.
|
|
SS$_EXPGFLQUOTA
|
The process exceeded its paging file quota.
|
|
SS$_INSFWSL
|
The process's working set limit is not large enough to accommodate the
increased virtual address space.
|
|
SS$_IVCHAN
|
An invalid channel number was specified; the channel number specified
was 0 or a channel that is unassigned.
|
|
SS$_IVCHNLSEC
|
The channel number specified is currently active, or there are no files
opened on the specified channel.
|
|
SS$_IVIDENT
|
An invalid channel number was specified; the channel number specified
is larger than the number of channels available.
|
|
SS$_IVLOGNAM
|
The specified global section name has a length of 0 or has more than 43
characters.
|
|
SS$_IVREGID
|
Invalid region ID specified.
|
|
SS$_IVSECFLG
|
An invalid flag, a reserved flag, or an invalid combination of flags
and arguments was specified.
|
|
SS$_LEN_NOTBLKMULT
|
The
length_64 argument is not a multiple of virtual disk
blocks.
|
|
SS$_NOSHPTS
|
A virtual address within a shared page table region was specified.
|
|
SS$_NOTFILEDEV
|
The device is not a file-oriented, random-access, or directory device.
|
|
SS$_OFF_NOTBLKALGN
|
The
file_offset_64 argument is not a multiple of virtual
disk blocks.
|
|
SS$_NOWRT
|
The file is read-only, the flag bit SEC$M_WRT was set, and the flag bit
SEC$M_CRF is not set.
|
|
SS$_PAGNOTINREG
|
A page in the specified range is not within the specified region.
|
|
SS$_PAGOWNVIO
|
A page in the specified range already exists and cannot be deleted
because it is owned by a more privileged access mode than that of the
caller.
|
|
SS$_REGISFULL
|
The specified virtual region is full; no space is available in the
region for the pages created to contain the mapped section.
|
|
SS$_VA_IN_USE
|
A page in the specified input address range is already mapped and the
flag SEC$M_NO_OVERMAP is set, or the existing underlying page cannot be
deleted because it is associated with a buffer object.
|
|
SS$_VA_NOTPAGALGN
|
The
start_va_64 argument is not CPU-specific page aligned.
|
|
