 |
HP OpenVMS System Services Reference Manual
$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 I64 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 I64 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 I64 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 I64)
On Alpha and I64 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 I64 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.
|
$UNWIND
Unwinds the procedure call stack.
Format
SYS$UNWIND [depadr] ,[newpc]
C Prototype
int sys$unwind (unsigned int *depadr, void *newpc);
Arguments
depadr
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Depth to which the procedure call stack is to be unwound. The
depadr argument is the address of a longword value.
The value 0 specifies the call frame of the procedure that was
executing when the condition occurred (that is, no call frames are
unwound); the value 1 specifies the caller of that frame; the value 2
specifies the caller of the caller of that frame, and so on.
If depadr specifies the value 0, no unwind occurs and
$UNWIND returns a successful condition value in R0.
If you do not specify depadr, $UNWIND unwinds the
stack to the call frame of the procedure that called the procedure that
established the condition handler that is calling the $UNWIND service.
This is the default and the normal method of unwinding the procedure
call stack.
newpc
| OpenVMS usage: |
address |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
New value for the program counter (PC); this value replaces the current
value of the PC in the call frame of the procedure that receives
control when the unwinding operation is complete. The
newpc argument is a longword value containing the
address at which execution is to resume.
Execution resumes at this address when the unwinding operation is
complete.
If you do not specify newpc, execution resumes at the
location specified by the PC in the call frame of the procedure that
receives control when the unwinding operation is complete.
Description
The Unwind Call Stack service unwinds the procedure call stack; that
is, it removes a specified number of call frames from the stack.
Optionally, it can return control to a new program counter (PC)
unwinding the stack. The $UNWIND service is intended to be called from
within a condition-handling routine.
The actual unwind is not performed immediately. Rather, the return
addresses in the call stack are modified so that, when the condition
handler returns, the unwind procedure is called from each frame being
unwound.
During the actual unwinding of the call stack, $UNWIND examines each
frame in the call stack to see if a condition handler has been
declared. If a handler has been declared, $UNWIND calls the handler
with the condition value SS$_UNWIND (indicating that the call stack is
being unwound) in the condition name argument of the signal array. When
you call a condition handler with this condition value, that handler
can perform any procedure-specific cleanup operations that might be
required. After the condition handler returns, the call frame is
removed from the stack.
Required Access or Privileges
None
Required Quota
None
Related Services
$DCLCMH, $SETEXV
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The call stack is not accessible to the caller. This condition is
detected when the call stack is scanned to modify the return address.
|
|
SS$_INSFRAME
|
There are insufficient call frames to unwind to the specified depth.
|
|
SS$_NOSIGNAL
|
No signal is currently active for an exception condition.
|
|
SS$_UNWINDING
|
An unwind operation is already in progress.
|
$UPDSEC
Writes all modified pages in an active private or global section back
into the section file on disk. One or more I/O requests are queued,
based on the number of pages that have been modified.
Format
SYS$UPDSEC inadr ,[retadr] ,[acmode] ,[updflg] ,[efn] ,[iosb] ,[astadr]
,[astprm]
C Prototype
int sys$updsec (struct _va_range *inadr, struct _va_range *retadr,
unsigned int acmode, char updflg, unsigned int efn, struct _iosb *iosb,
void (*astadr)(__unknown_params), int astprm);
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 that are to be
written to the section file if they have been modified. The
inadr argument is the address of a 2-longword array
containing, in order, the starting and ending process virtual
addresses. Addresses are adjusted up or down to CPU-specific pages.
Only the virtual page number portion of each virtual address is used;
the low-order byte-within-page bits are ignored.
$UPDSEC scans pages starting at the address contained in the first
longword specified by inadr and ending at the address
contained in the second longword. Within this range, $UPDSEC locates
read/write pages that have been modified and writes them (contiguously,
if possible) to the section file on disk. Unmodified pages are also
written to disk if they share the same cluster with modified pages.
If the starting and ending virtual addresses are the same, a single
page is written to the section file if the page has been modified.
The address specified by the second longword might be smaller than the
address specified by the first longword.
retadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference---array reference or descriptor |
Addresses of the first and last pages that were actually queued for
writing, in the first $QIO request, back to the section file on disk.
The retadr argument is the address of a 2-longword
array containing, in order, the addresses of the first and last pages.
Addresses always are adjusted up or down to fall on CPU-specific
boundaries.
If $UPDSEC returns an error condition value in R0, each longword
specified by retadr contains the value --1. In this
case, an event flag is not set, no asynchonous system trap (AST) is
delivered, and the I/O status block is not written to.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode on behalf of which the service is performed. 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.
A page cannot be written to disk unless the access mode used by $UPDSEC
is equal to or more privileged than the access mode of the owner of the
page to be written.
updflg
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Update specifier for read/write global sections. The
updflg argument is a longword value. The value 0 (the
default) specifies that all read/write pages in the global section are
to be written to the section file on disk, whether or not they have
been modified. The value 1 specifies that the caller is the only or the
last process having the global section mapped for write access and that
only modified pages should be written to the section file on disk.
efn
| OpenVMS usage: |
ef_number |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Event flag to be set when the section file on disk is actually updated.
The efn argument is a longword specifying the number
of the event flag; however, $UPDSEC uses only the low-order byte.
If you do not specify efn, event flag 0 is used.
When you invoke $UPDSEC, the specified event flag or event flag 0 is
cleared; when the update operation is complete, the event flag is set.
iosb
| OpenVMS usage: |
io_status_block |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
I/O status block to receive the final completion status of the updating
operation. The iosb argument is the address of the
quadword I/O status block.
When you invoke $UPDSEC, the I/O status block is cleared. After the
update operation is complete, that is, when all I/O to the disk is
complete, the I/O status block is written as follows:
- The first word contains the condition value returned by $QIO,
indicating the final completion status.
- The first bit in the second word is set only if an error occurred
during the I/O operation and the error was a hardware write error. The
remaining bits of the second word are zeros.
- The second longword contains the virtual address of the first page
that was not written.
Though this argument is optional, HP strongly recommends that you
specify it for the following reasons:
- If you are using an event flag to signal the completion of the
service, you can test the I/O status block for a condition value to be
sure that the event flag was not set by an event other than service
completion.
- If you are using $SYNCH to synchronize completion of the service,
the I/O status block is a required argument for $SYNCH.
- The condition value returned in R0 and the condition value returned
in the I/O status block provide information about different aspects of
the call to $UPDSEC. The condition value returned in R0 gives you
information about the success or failure of the service call itself;
the condition value returned in the I/O status block gives you
information about the success or failure of the service operation.
Therefore, to accurately assess the success or failure of the call to
$UPDSEC, you must check the condition values returned in both R0 and
the I/O status block.
astadr
| OpenVMS usage: |
ast_procedure |
| type: |
procedure value |
| access: |
call without stack unwinding |
| mechanism: |
by reference---procedure reference or
descriptor |
AST routine to be executed when the section file has been updated. The
astadr argument is the address of this routine.
If you specify astadr, the AST routine executes at the
access mode from which the section file update was requested.
astprm
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
AST parameter to be passed to the AST routine. The
astprm argument is this longword parameter.
Description
The Update Section File on Disk service writes all modified pages in an
active private or global section back into the section file on disk.
One or more I/O requests are queued, based on the number of pages that
have been modified.
Proper use of this service requires the caller to synchronize
completion of the update request. You do this by first checking the
condition value returned in R0 by $UPDSEC. If SS$_NOTMODIFIED is
returned, the caller can continue. If SS$_NORMAL is returned, the
caller should wait for the I/O to complete and then check the first
word of the I/O status block for the final completion status. You can
use the Synchronize ($SYNCH) service to determine whether the I/O
operation has actually completed.
On VAX systems, for a global section located in memory shared by
multiple processors, only processes running on the processor that
created the section can specify that global section in a call to
$UPDSEC. Processes on another processor that attempt to update the
section file receive an error condition.
Required Access or Privileges
|
