Document revision date: 30 March 2001

## OpenVMS System Services Reference Manual

Previous | Contents | Index

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.

Previous | Next | Contents | Index

| privacy and legal statement |
4527PRO_022.HTML