 |
OpenVMS System Services Reference Manual
$DELMBX
Marks a permanent mailbox for deletion.
Format
SYS$DELMBX chan
C Prototype
int sys$delmbx (unsigned short int chan);
Argument
chan
| OpenVMS usage: |
channel |
| type: |
word (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of the channel assigned to the mailbox that is to be deleted.
The chan argument is a word containing this number.
Description
The Delete Mailbox service marks a permanent mailbox for deletion. The
actual deletion of the mailbox and of its associated logical name
assignment occurs when no more I/O channels are assigned to the mailbox.
You can delete a mailbox only from an access mode equal to or more
privileged than the access mode from which the mailbox channel was
assigned. Temporary mailboxes are automatically deleted when their
reference count goes to 0.
The $DELMBX service does not deassign the channel assigned by the
caller, if any. The caller must deassign the channel with the Deassign
I/O Channel ($DASSGN) service.
Required Access or Privileges
You need PRMMBX privilege to delete a permanent mailbox.
Required Quota
None
Related Services
$ALLOC, $ASSIGN, $BRKTHRU, $BRKTHRUW, $CANCEL, $CREMBX, $DALLOC,
$DASSGN, $DEVICE_SCAN, $DISMOU, $GETDVI, $GETDVIW, $GETMSG, $GETQUI,
$GETQUIW, $INIT_VOL, $MOUNT, $PUTMSG, $QIO, $QIOW, $SNDERR, $SNDJBC,
$SNDJBCW, $SNDOPR
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_DEVNOTMBX
|
The specified channel is not assigned to a mailbox.
|
|
SS$_IVCHAN
|
You specified an invalid channel number, that is, a channel number of 0
or a number larger than the number of channels available.
|
|
SS$_NOPRIV
|
The specified channel is not assigned to a device; the process does not
have the privilege to delete a permanent mailbox or a mailbox in memory
shared by multiple processors; or the access mode of the caller is less
privileged than the access mode from which the channel was assigned.
|
$DELPRC
Allows a process to delete itself or another process.
Format
SYS$DELPRC [pidadr] ,[prcnam]
C Prototype
int sys$delprc (unsigned int *pidadr, void *prcnam);
Arguments
pidadr
| OpenVMS usage: |
process_id |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Process identification (PID) of the process to be deleted. The
pidadr argument is the address of a longword that
contains the PID. The pidadr argument can refer to a
process running on the local node or a process running on another node
in the OpenVMS Cluster system.
You must specify the pidadr argument to delete
processes in other UIC groups.
prcnam
| OpenVMS usage: |
process_name |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by descriptor--fixed-length string descriptor |
Process name of the process to be deleted. The prcnam
is the address of a character string descriptor pointing to the process
name string. A process running on the local node can be identified with
a 1- to 15-character string. To identify a process on a particular node
on a cluster, specify the full process name, which includes the node
name as well as the process name. The full process name can contain up
to 23 characters.
You use the prcnam argument to delete only processes
in the same UIC group as the calling process, because process names are
unique to UIC groups, and the operating system uses the UIC group
number of the calling process to interpret the process name specified
by the prcnam argument.
You must use the pidadr argument to delete processes
in other groups.
Description
The Delete Process service allows a process to delete itself or another
process. If you specify neither the pidadr nor the
prcnam argument, $DELPRC deletes the calling process;
control is not returned. If the longword at address
pidadr is 0, the PID of the target process is
returned. This system service requires system dynamic memory.
When you delete a process or subprocess, a termination message is sent
to its creating process, provided the mailbox to receive the message
still exists and the creating process has access to the mailbox. The
termination message is sent before the final rundown is initiated;
thus, the creating process might receive the message before the process
deletion is complete.
Due to the complexity of the required rundown operations, a significant
time interval occurs between a delete request and the actual deletion
of the process; however, the $DELPRC service returns to the caller
immediately after initiating the rundown operation.
If you issue subsequent delete requests for a process currently being
deleted, the requests return immediately with a successful completion
status.
Process exit handlers are not invoked when a process is deleted. For
details on exit handlers, see the $DCLEXH service.
Required Access or Privileges
Depending on the operation, the calling process might need one of the
following privileges to use $DELPRC:
- GROUP privilege to delete processes in the same group that do not
have the same UIC
- WORLD privilege to delete any process in the system
Required Quota
None. Deductible resource quotas granted to subprocesses are returned
to the creating process when the subprocesses are deleted.
Related Services
$CANEXH, $CREPRC, $DCLEXH, $EXIT, $FORCEX, $GETJPI, $GETJPIW, $HIBER,
$PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND,
$WAKE
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The process name string or string descriptor cannot be read by the
caller, or the process identification cannot be written by the caller.
|
|
SS$_INCOMPAT
|
The remote node is running an incompatible version of the operating
system.
|
|
SS$_INSFMEM
|
The system dynamic memory is insufficient for completing the operation.
|
|
SS$_NONEXPR
|
The specified process does not exist, or an invalid process
identification was specified.
|
|
SS$_NOPRIV
|
The caller does not have the privilege to delete the specified process.
|
|
SS$_NOSUCHNODE
|
The process name refers to a node that is not currently recognized as
part of the cluster.
|
|
SS$_REMRSRC
|
The remote node has insufficient resources to respond to the request.
(Bring this error to the attention of your system manager.)
|
|
SS$_UNREACHABLE
|
The remote node is a member of the cluster but is not accepting
requests. (This is normal for a brief period early in the system boot
process.)
|
$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 Only)
On Alpha 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 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) |
| 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 systems) or the 32-bit (on VAX systems) of the
16-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.
|
