 |
HP OpenVMS System Services Reference Manual
$ULKPAG
Unlocks pages that were previously locked in memory by the Lock Pages
in Memory ($LCKPAG) service. Locked pages are automatically unlocked
and deleted at image exit.
Format
SYS$ULKPAG inadr ,[retadr] ,[acmode]
C Prototype
int sys$ulkpag (struct _va_range *inadr, struct _va_range *retadr,
unsigned int acmode);
Arguments
inadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Starting and ending virtual addresses of the pages to be unlocked. 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;
the low-order byte-within-page bits are ignored. If the starting and
ending virtual addresses are the same, a single page is unlocked.
If more than one page is being unlocked and you need to determine
specifically which pages had been previously unlocked, you should
unlock the pages one at a time, that is, one page per call to $ULKPAG.
The condition value returned by $ULKPAG indicates whether the page was
previously unlocked.
retadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference---array reference or descriptor |
Starting and ending process virtual addresses of the pages actually
unlocked by $ULKPAG. The retadr argument is the
address of a 2-longword array containing, in order, the starting and
ending process virtual addresses.
If an error occurs while multiple pages are being unlocked,
retadr specifies those pages that were successfully
unlocked before the error occurred. If no pages were successfully
unlocked, both longwords in the retadr array contain
the value --1.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode on behalf of which the request is being made. The
acmode argument is a longword containing the access
mode. The $PSLDEF macro defines the symbols for the four access modes.
The most privileged access mode used is the access mode of the caller.
To unlock any specified page, the resultant access mode must be equal
to or more privileged than the access mode of the owner of that page.
Description
The Unlock Pages from Memory service unlocks pages that were previously
locked in memory by the Lock Pages in Memory ($LCKPAG) service. Locked
pages are automatically unlocked and deleted at image exit.
On Alpha and Integrity server systems, if you are attempting to unlock
executable code, you should issue multiple $ULKPAG calls: one to unlock
the code pages and others to unlock the linkage section references to
these pages.
Required Access or Privileges
To call the $ULKPAG service, a process must have PSWAPM privilege.
Required Quota
None
Related Services
For more information, see the chapter about memory management in the
HP OpenVMS Programming Concepts Manual.
Condition Values Returned
|
SS$_WASCLR
|
The service completed successfully. At least one of the specified pages
was previously unlocked.
|
|
SS$_WASSET
|
The service completed successfully. All of the specified pages were
previously locked.
|
|
SS$_ACCVIO
|
The input array cannot be read by the caller; the output array cannot
be written by the caller; or a page in the specified range is
inaccessible or does not exist.
|
$ULKPAG_64 (Alpha and Integrity servers)
On Alpha and Integrity server systems, unlocks pages that were
previously locked in memory by the Lock Pages in Memory ($LCKPAG_64)
service.
This service accepts 64-bit addresses.
Format
SYS$ULKPAG_64 start_va_64 ,length_64 ,acmode ,return_va_64
,return_length_64
C Prototype
int sys$ulkpag_64 (void *start_va_64, unsigned __int64 length_64,
unsigned int acmode, void *(*(return_va_64)), unsigned __int64
*return_length_64);
Arguments
start_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
read only |
| mechanism: |
by value |
The starting virtual address of the pages to be unlocked. The specified
virtual address will be rounded down to a CPU-specific page boundary.
length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Length of the virtual address space to be unlocked. The specified
length will be rounded up to a CPU-specific page boundary so that it
includes all CPU-specific pages in the requested range.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode on behalf of which the request is being made. 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.
To unlock any specified page, the resultant access mode must be equal
to or more privileged than the access mode of the owner of that page.
return_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The lowest process virtual address of the unlocked virtual address
range. 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 length of the virtual address range unlocked. The
return_length_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword into which the service returns
the length of the virtual address range in bytes.
Description
The Unlock Pages from Memory service unlocks pages that were previously
locked in memory by the Lock Pages in Memory ($LCKPAG_64) service.
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
unlocked before the error occurred. If no pages were unlocked, 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
To call the $ULKPAG_64 service, a process must have PSWAPM privilege.
Required Quota
None
Related Services
$LCKPAG_64, $ULKPAG
Condition Values Returned
|
SS$_WASCLR
|
The service completed successfully. At least one of the specified pages
was previously unlocked.
|
|
SS$_WASSET
|
The service completed successfully. All of the specified pages were
previously locked in the working set.
|
|
SS$_ACCVIO
|
The
return_va_64 or
return_length_64 argument cannot be written by the
caller, or an attempt was made to unlock pages by a caller whose access
mode is less privileged than the access mode associated with the pages.
|
$ULWSET
Unlocks pages that were previously locked in the working set by the
Lock Pages in Working Set ($LKWSET) service.
Format
SYS$ULWSET inadr ,[retadr] ,[acmode]
C Prototype
int sys$ulwset (struct _va_range *inadr, struct _va_range *retadr,
unsigned int acmode);
Arguments
inadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference---array reference or descriptor |
Starting and ending virtual addresses of the pages to be unlocked. 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;
the low-order byte-within-page bits are ignored. If the starting and
ending virtual address are the same, a single page is unlocked.
If more than one page is being unlocked and you need to determine
specifically which pages had been previously unlocked, you should
unlock the pages one at a time, that is, one page per call to $ULWSET.
The condition value returned by $ULWSET indicates whether the page was
previously unlocked.
On Alpha and Integrity server systems, if the first address in the
2-longword array is within an image mapped to your process, the entire
image specified by the address is unlocked from the working set.
retadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference---array reference or descriptor |
Starting and ending process virtual addresses of the pages that were
actually unlocked by $CRMPSC. The retadr argument is
the address of a 2-longword array containing, in order, the starting
and ending process virtual addresses.
If an error occurs while multiple pages are being unlocked,
retadr specifies those pages that were successfully
unlocked before the error occurred. If no pages were successfully
unlocked, both longwords in the retadr array contain
the value --1.
On Alpha and Integrity server systems, if the inadr
argument specifies an address within an image mapped to your process,
retadr specifies only one range of pages unlocked from
the working set. Many ranges of pages might be unlocked.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode on behalf of which the request is being made. The
acmode argument is a longword containing the access
mode. The $PSLDEF macro defines the symbols for the four access modes.
The most privileged access mode used is the access mode of the caller.
To unlock any specified page, the resultant access mode must be equal
to or more privileged than the access mode of the owner of that page.
Description
The Unlock Pages from Working Set service unlocks pages that were
previously locked in the working set by the Lock Pages in Working Set
($LKWSET) service. Unlocked pages become candidates for replacement
within the working set of the process.
On Alpha and Integrity server systems, if the first address specified
to SYS$ULWSET is within an image mapped to your process, a success
status indicates that the entire image containing the specified address
is either unlocked from the working set, or the count of times the
image has been locked in the working set has been decremented. This
behavior helps to ensure that privileged processes entering kernel mode
and raising IPL higher than IPL 2 do not access an invalid page and
cause a PGFIPLHI bugcheck. The system keeps a count of the number of
times each image within your process has been locked in the working
set. This count is maintained so that calls to SYS$ULWSET unlock the
image only when it has been called the same number of times as
SYS$LKWSET.
The LIBRTL routines LIB$LOCK_IMAGE and LIB$UNLOCK_IMAGE are preferable
to SYS$LKWSET and SYS$ULWSET for locking and unlocking code and related
data in the working set. For more information about locking images in
the working set, see the LIBRTL manual and the description of
LIB$LOCK_IMAGE and LIB$UNLOCK_IMAGE.
Required Access or Privileges
None
Required Quota
None
Related Services
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $EXPREG, $LCKPAG,
$LKWSET, $MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $UPDSEC,
$UPDSECW
Condition Values Returned
|
SS$_WASCLR
|
The service completed successfully. At least one of the specified pages
was previously unlocked.
|
|
SS$_WASSET
|
The service completed successfully. All of the specified pages were
previously locked in the working set. If the image has been locked in
the working set, the count of times the image has been locked in the
working set has been decremented. Only when the count is zero is the
image unlocked from the working set.
|
|
SS$_ACCVIO
|
The
inadr argument cannot be read by the caller; the
retadr argument cannot be written by the caller; or a
page in the specified range is inaccessible or does not exist.
|
|
SS$_NOPRIV
|
A page in the specified range is in the system address space.
|
$ULWSET_64 (Alpha and Integrity servers)
On Alpha and Integrity server systems, unlocks a virtual address range
that was previously locked in the working set by the Lock Pages in
Working Set ($LKWSET_64) service.
This service accepts 64-bit addresses.
Format
SYS$ULWSET_64 start_va_64 ,length_64 ,acmode ,return_va_64
,return_length_64
C Prototype
int sys$ulwset_64 (void *start_va_64, unsigned __int64 length_64,
unsigned int acmode, void *(*(return_va_64)), unsigned __int64
*return_length_64);
Arguments
start_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
read only |
| mechanism: |
by value |
The starting virtual address of the pages to be unlocked from the
working set. The specified virtual address will be rounded down to a
CPU-specific page boundary.
length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Length of the virtual address space to be unlocked from the working
set. The specified length will be rounded up to a CPU-specific page
boundary so that it includes all CPU-specific pages in the requested
range.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode on behalf of which the request is being made. 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.
To unlock any specified page, the resultant access mode must be equal
to or more privileged than the access mode of the owner of that page.
return_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The lowest process virtual address of the unlocked virtual address
range. 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 length of the virtual address range unlocked. The
return_length_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword into which the service returns
the length of the virtual address range in bytes.
Description
The Unlock Pages from Working Set service unlocks pages that were
previously locked in the working set by the Lock Pages in Working Set
($LKWSET_64) service. Unlocked pages become candidates for replacement
within the working set of the process.
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
unlocked before the error occurred. If no pages were unlocked, 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.
On Alpha and Integrity server systems, if the first address specified
to SYS$ULWSET_64 is within an image mapped to your process, a success
status indicates that the entire image containing the specified address
is either unlocked from the working set, or the count of times the
image has been locked in the working set has been decremented. This
behavior helps to ensure that privileged processes entering kernel mode
and raising IPL higher than IPL 2 do not access an invalid page and
cause a PGFIPLHI bugcheck. The system keeps a count of the number of
times each image within your process has been locked in the working
set. This count is maintained so that calls to SYS$ULWSET_64 unlock the
image only when it has been called the same number of times as
SYS$LKWSET_64.
The LIBRTL routines LIB$LOCK_IMAGE and LIB$UNLOCK_IMAGE are preferable
to SYS$LKWSET_64 and SYS$ULWSET_64 for locking and unlocking code and
related data in the working set. For more information about locking
images in the working set, see the LIBRTL manual and the description of
LIB$LOCK_IMAGE and LIB$UNLOCK_IMAGE.
Required Privileges
None
Required Quota
None
Related Services
$LKWSET_64, $PURGE_WS, $ULWSET
Condition Values Returned
|
SS$_WASCLR
|
The service completed successfully. At least one of the specified pages
was previously unlocked.
|
|
SS$_WASSET
|
The service completed successfully. All of the specified pages were
previously locked in the working set. If the image had been locked in
the working set, the count of times the image has been locked in the
working set has been decremented. Only when the count is zero is the
image unlocked from the working set.
|
|
SS$_ACCVIO
|
The
return_va_64 or
return_length_64 argument cannot be written by the
caller, or an attempt was made to unlock pages by a caller whose access
mode is less privileged than the access mode associated with the pages.
|
|
SS$_PAGNOTINREG
|
A page in the specified range is not within process private address
space.
|
|
