 |
HP OpenVMS System Services Reference Manual
$DELTVA
Deletes a range of addresses from a process's virtual address space.
Upon successful completion of the service, the deleted pages are
inaccessible, and references to them cause access violations.
Format
SYS$DELTVA inadr ,[retadr] ,[acmode]
C Prototype
int sys$deltva (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 deleted. The
inadr argument is the address of a 2-longword array
containing, in order, the starting and ending process virtual
addresses. If the starting and ending virtual addresses are the same, a
single page is deleted. The addresses are adjusted up or down to fall
on CPU-specific page boundaries. Only the virtual page number portion
of each virtual address is used; the low-order byte-within-page bits
are ignored.
The $DELTVA service deletes pages starting at the address contained in
the second longword of the inadr argument and ending
at the address in the first longword. Thus, if you use the same address
array for both the Create Virtual Address Space ($CRETVA) and the
$DELTVA services, the pages are deleted in the reverse order from which
they were created.
retadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Starting and ending process virtual addresses of the pages that $DELTVA
has deleted. The retadr argument is the address of a
2-longword array containing, in order, the starting and ending process
virtual addresses.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode on behalf of which the service is to be performed. The
acmode argument is a longword containing the access
mode.
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.
Description
The Delete Virtual Address Space service deletes a range of addresses
from a process's virtual address space. Upon successful completion of
the service, the deleted pages are inaccessible, and references to them
cause access violations. If any of the pages in the specified range
have already been deleted or do not exist, the service continues as if
the pages were successfully deleted.
If an error occurs while pages are being deleted, the
retadr argument specifies the pages that were
successfully deleted before the error occurred. If no pages are
deleted, both longwords in the return address array contain the value
--1.
Required Access or Privileges
None
Required Quota
None
Related Services
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DGBLSC, $EXPREG, $LCKPAG, $LKWSET,
$MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC,
$UPDSECW
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The input address array cannot be read by the caller, or the return
address array cannot be written by the caller.
|
|
SS$_NOPRIV
|
A page in the specified range is in the system address space.
|
|
SS$_PAGOWNVIO
|
A page in the specified range is owned by an access mode more
privileged than the access mode of the caller.
|
|
SS$_NOSHPTS
|
The region ID of a shared page table region was specified.
|
|
SS$_VA_IN_USE
|
The existing underlying page cannot be deleted because it is associated
with a buffer object.
|
$DELTVA_64 (Alpha and I64)
On Alpha and I64 systems, deletes a range of virtual addresses from a
process's virtual address space. Upon successful completion of the
service, the deleted pages are inaccessible, and references to them
cause access violations.
This service accepts 64-bit addresses.
Format
SYS$DELTVA_64 region_id_64 ,start_va_64 ,length_64 ,acmode
,return_va_64 ,return_length_64
C Prototype
int sys$deltva_64 (struct _generic_64 *region_id_64, void *start_va_64,
unsigned __int64 length_64, unsigned int acmode, 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 from which to address the VA
space.
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. Also, the region ID that a virtual address is in can be
obtained by calling the $GET_REGION_INFO service, specifying the
VA$_REGSUM_BY_VA function.
start_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
read only |
| mechanism: |
by value |
The starting virtual address of the pages to be deleted. The specified
address must be a CPU-specific page aligned address. If the
region_id_64 argument specifies a shared page table
region or if the start_va_64 argument lies within a
shared page table region, the specified address must be a CPU-specific
page table page aligned address.
length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Length of the virtual address space to be deleted. The length specified
must be a multiple of CPU-specific pages. If the virtual address space
is being deleted from a shared page table region, the specified length
must be page table page aligned or include the last page in a
memory-resident section.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode associated with the call to $DELTVA_64. 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.
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 deleted virtual address
range. The return_va_64 argument is the 32- or 64-bit
virtual address of a naturally aligned quadword into which the
$DELTVA_64 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 $DELTVA_64 service returns the length in bytes of the virtual
address range deleted.
Description
The Delete Virtual Address Space service is a kernel mode service that
can be called from any mode. This service deletes a range of addresses
from a process's virtual address space.
Upon successful completion of the service, the deleted pages are
inaccessible, and references to them cause access violations. If any of
the pages in the specified range have already been deleted or do not
exist, the service continues as if the pages were successfully deleted.
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 deleted before the error occurred. If no pages were
deleted, 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
None
Related Services
$CREATE_REGION_64, $CRETVA_64, $CRMPSC_FILE_64, $CRMPSC_GFILE_64,
$CRMPSC_GPFILE_64, $CRMPSC_GPFN_64, $CRMPSC_PFN_64, $DELETE_REGION_64,
$EXPREG_64, $MGBLSC_64, $MGBLSC_GPFN_64
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$_IVREGID
|
Invalid region ID specified. This condition value is returned if P0,
P1, or P2 space is specified because these regions cannot be deleted,
or if no region exists for the specified ID.
|
|
SS$_LEN_NOTPAGMULT
|
The
length_64 argument is not a multiple of CPU-specific
pages; or, for shared page table regions, is not a multiple of
CPU-specific page table pages or does not include the last page in a
memory-resident global section.
|
|
SS$_PAGNOTINREG
|
A page in the specified range is not within the specified region.
|
|
SS$_PAGOWNVIO
|
A page in the specified range is owned by an access mode more
privileged than the access mode of the caller.
|
|
SS$_VA_NOTPAGALGN
|
The
start_va_64 argument is not a CPU-specific page table
page aligned address; or, for shared page table regions, is not page
table page aligned.
|
|
SS$_VA_IN_USE
|
The existing underlying page cannot be deleted because it is associated
with a buffer object.
|
$DEQ
Dequeues (unlocks) granted locks; dequeues the sublocks of a lock; or
cancels an ungranted lock request. The calling process must have
previously acquired the lock or queued the lock request by calling the
Enqueue Lock Request ($ENQ) service.
On Alpha and I64 systems, this service accepts 64-bit addresses.
Format
SYS$DEQ [lkid] ,[valblk] ,[acmode] ,[flags]
C Prototype
int sys$deq (unsigned int lkid, void *valblk, unsigned int acmode,
unsigned int flags);
Arguments
lkid
| OpenVMS usage: |
lock_id |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Lock identification of the lock to be dequeued. The
lkid argument specifies this lock identification.
Note that if you do not specify the lkid argument, you
must specify the LCK$M_DEQALL flag in the flags
argument.
When you specify the LCK$M_DEQALL flag in the flags
argument, different values (or no value) for the lkid
argument produce varying behavior:
- When you do not specify the lkid argument (or
specify it as 0) and you do specify the LCK$M_DEQALL flag, $DEQ
dequeues all locks held by the process, at access modes equal to or
less privileged than the effective access mode, on all resources. The
effective access mode is the least privileged of the caller's access
mode and the access mode specified in the acmode
argument.
- When you specify the lkid argument as a nonzero
value together with the LCK$M_DEQALL flag, $DEQ dequeues all sublocks
of the lock identified by lkid; it does not dequeue
the lock identified by lkid. For this operation, $DEQ
ignores the LCK$M_CANCEL flag if it is set. A sublock of a lock is a
lock that was created when the parid argument in the
call to $ENQ was specified, where parid is the lock ID
of the parent lock.
If you omit the lkid argument (or specify it as 0) and
the LCK$M_DEQALL flag is not set, the $DEQ service returns the invalid
lock ID condition value (SS$_IVLOCKID).
valblk
| OpenVMS usage: |
lock_value_block |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by 32- or 64-bit reference (Alpha and I64) |
| mechanism: |
by 32-bit reference (VAX) |
Lock value block for the resource associated with the lock to be
dequeued. The valblk argument is the 32- or 64-bit
address (on Alpha or I64 systems) or the 32-bit (on VAX systems) of the
16-byte lock value block, or, if LKC$M_XVALBLK is specified (on Alpha
or I64 systems), of the 64-byte lock value block. When you specify the
LCK$M_DEQALL flag, you cannot use this argument.
When a protected write (PW) or exclusive (EX) mode lock is being
dequeued and you specify a lock value block in the
valblk argument, the contents of that lock value block
are written to the lock value block in the lock database. Further, if
the lock value block in the lock database was marked as invalid, that
condition is cleared; the block becomes valid.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode of the lock to be dequeued. The acmode
argument is a longword containing the access mode.
The acmode argument is valid only if the LCK$M_DEQALL
flag of the flags argument is set. 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
|
When dequeuing locks, $DEQ maximizes the access mode of the caller and
the specified acmode argument. The maximized access
mode is the less privileged of the caller's access mode and the
acmode argument. If you do not specify the
acmode argument, $DEQ uses the caller's access mode.
Only those locks with an access mode that is equal to or less than the
maximized access mode are dequeued.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flags specifying options for the $DEQ operation. The
flags argument is a longword bit mask that is the
logical OR of each bit set, where each bit corresponds to an option.
Note that if you do not specify the lkid argument, you
must specify the LCK$M_DEQALL flag in the flags
argument.
A symbolic name for each flag bit is defined by the $LCKDEF macro. The
following table describes each flag:
| Flag |
Description |
|
LCK$M_DEQALL
|
When you specify this flag, $DEQ dequeues multiple locks, depending on
the value of the
lkid argument. Refer to the description of the
lkid argument for details. The
acmode argument is ignored if the LCK$M_DQALL flag is
not set. If you specify LCK$M_DEQALL, the LCK$M_CANCEL flag, if set, is
ignored.
|
|
LCK$M_CANCEL
|
When you specify this flag, $DEQ attempts to cancel a lock request that
was queued by $ENQ. You can cancel only a waiting request. When the
request is canceled, $DEQ returns the condition value SS$_NORMAL.
If you attempt to cancel a granted lock, the request fails and $DEQ
returns the condition value SS$_CANCELGRANT. There are two types of
waiting requests that can be canceled:
- A request for a new lock
- A request to convert an existing lock
When canceling a new lock request, the following action is taken:
- If a completion asynchronous system trap (AST) was requested, the
AST is queued for delivery and SS$_ABORT is stored in the lock status
block.
When canceling a request to convert an existing lock, the
conversion request is canceled. The existing granted lock remains
unchanged. The following specific actions are taken:
- The blocking AST address specified for the existing granted lock is
queued for delivery if the granted mode of the existing lock is
blocking other waiting requests.
- If a completion AST was specified by the conversion request, the
completion AST is queued for delivery with SS$_CANCEL status stored in
the lock status block that was specified by the conversion request.
If you specify the LCK$M_DEQALL flag, the LCK$M_CANCEL flag is
ignored.
|
|
LCK$M_INVVALBLK
|
When you specify this flag, $DEQ marks the lock value block, which is
maintained for the resource in the lock database, as invalid. The lock
value block remains marked as invalid until it is again written to. The
Description section of the $ENQ service provides additional information
about lock value block invalidation.
This flag is ignored if (1) the lock mode of the lock being
dequeued is not protected write or exclusive, or (2) you specify the
LCK$M_CANCEL flag.
|
|
LCK$M_XVALBLK
|
When you specify this flag, you must provide a 64-byte lock value block
as the
valblk argument. If you do not specify this flag, only
the first 16 bytes of the buffer specified in the
valblk argument will be written.
If the value block is written without this flag, the value block
will be flagged so that a future reader who specifies the LCK$M_XVALBLK
flag in the $ENQ system service call will receive the warning status
SS$_XVALNOTVALID until a future writer writes to the value block
specifying this flag.
This flag is valid only on Alpha and I64 systems.
|
Description
The Dequeue Lock Request service dequeues (unlocks) granted locks and
waiting lock requests. The calling process must have previously
acquired the lock or queued the lock request by calling the Enqueue
Lock Request ($ENQ) service.
Action taken by the $DEQ service depends on the current state (granted
or waiting) and the type of lock request (new lock or conversion
request) to be dequeued.
When dequeuing a granted lock, the $DEQ service returns the condition
value SS$_NORMAL and the following specific action is taken:
- Any queued blocking ASTs that have not been delivered are removed
from the process's AST queues.
There are two types of waiting requests that can be dequeued:
- A request for a new lock
- A request to convert an existing lock
When dequeuing a new lock request, the $DEQ service returns the
condition value SS$_NORMAL and the following specific action is taken:
- If a completion AST was requested, the completion AST is queued for
delivery with SS$_ABORT stored in the lock status block.
When dequeuing a lock for which there is a conversion request waiting,
the existing lock and its conversion request are dequeued. The $DEQ
service returns the condition value SS$_NORMAL and the following
specific actions are taken:
- If a blocking AST was queued to the process, it is removed from the
process's AST queue.
- If a completion AST was specified by the conversion request, the
completion AST is queued for delivery with SS$_ABORT status stored in
the lock status block that was specified by the conversion request.
When a protected write (PW) or exclusive (EX) mode lock is being
dequeued and you specify a lock value block in the
valblk argument, the contents of that lock value block
are written to the lock value block in the lock database.
If you specify the LCK$M_INVVALBLK flag in the flags
argument and the lock mode of the lock being dequeued is PW or EX, the
lock value block in the lock database is marked as invalid whether or
not a lock value block was specified in the valblk
argument.
The $DEQ, $ENQ, $ENQW, and $GETLKI services together provide the user
interface to the lock management facility. For additional information
about lock management, refer to the descriptions of these other
services and to the OpenVMS Programming Concepts Manual.
Required Access or Privileges
None
Required Quota
None
Related Services
$ENQ, $ENQW, $GETLKI, $GETLKIW
Condition Values Returned
|
SS$_NORMAL
|
The lock was dequeued successfully.
|
|
SS$_ACCVIO
|
The value block specified by the
valblk argument cannot be accessed by the caller.
|
|
SS$_CANCELGRANT
|
The LCK$M_CANCEL flag in the
flags argument was specified, but the lock request
that $DEQ was to cancel had already been granted.
|
|
SS$_ILLRSDM
|
An illegal attempt to modify a value block was made.
|
|
SS$_IVLOCKID
|
An invalid or nonexistent lock identification was specified or the
process does not have the privilege to dequeue a lock at the specified
access mode.
|
|
SS$_SUBLOCKS
|
The lock has sublocks and cannot be dequeued.
|
|
