OpenVMS System Services Reference Manual

The most privileged access mode used is the access mode of the caller. The caller can delete pages only if those pages are owned by an access mode equal to or less privileged than the access mode of the caller.

Once all pages are deleted within the region, the region can be deleted only if the region is owned by an access mode equal to or less privileged than the access mode of the caller.

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 pages that $DELETE_REGION_64 has successfully deleted. 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 of the first page deleted. Virtual addresses are deleted from low address to high address, regardless of the direction in which virtual addresses expand for that region.

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 that $DELETE_REGION_64 has successfully deleted. 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 deleted virtual address range in bytes.

DESCRIPTION

The Delete a Virtual Region service is a kernel mode service that can be called from any mode. The Delete a Virtual Region service deletes the user-defined region specified by the region_id_64 argument. You cannot delete the program (P0), control (P1), or 64-bit program (P2) regions.
The Delete a Virtual Region service also deletes all created virtual addresses within the specified region before deleting the region itself.
If a page within the region is owned by an access mode more privileged than the access mode of the caller, the condition value SS$_PAGOWNVIO is returned. The return_va_64 and return_length_64 arguments contain the virtual address range that was actually deleted by $DELETE_REGION_64. In this case, the region is not deleted because there are still some pages mapped within the region.
To delete a virtual region, the caller's access mode must be at least as privileged as the access mode associated with the region. If the caller is not privileged enough to delete the region, the condition value SS$_REGOWNVIO is returned only if all pages were successfully deleted from within the region.
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 the condition value SS$_ACCVIO is returned, no pages have been deleted, and the region has not been deleted.
If an error other than SS$_ACCVIO occurs, 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 contains 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, $DELTVA_64, $EXPREG_64, $GET_REGION_INFO, $MGBLSC_64, $MGBLSC_GPFN_64

Condition Values Returned

SS$_NORMAL Successful completion. All pages within the region have been deleted as well as the region itself.

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$_REGOWNVIO The region is owned by a more privileged access mode than the access mode of the caller. All pages within the region have been deleted; however, the region has not been deleted.

SS$_PAGOWNVIO A page within the specified region is owned by a more privileged access mode than the access mode of the caller.

$DELLNM

Deletes all logical names with the specified name at the specified access mode or outer access mode, or it deletes all the logical names with the specified access mode or outer access mode in a specified table.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$DELLNM tabnam ,[lognam] ,[acmode]

C Prototype

int sys$dellnm (void *tabnam, void *lognam, unsigned char *acmode);

ARGUMENTS

tabnam

OpenVMS usage: logical_name

type: character-coded text string

access: read only

mechanism: by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)

mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)

Name of a logical name table or a list of tables to be searched for the logical name to be deleted. The tabnam argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a descriptor that points to the table name. This argument is required.
If tabnam is not the name of a logical name table, it is assumed to be a logical name and is translated iteratively until either the name of a logical name table is found or the number of translations allowed by the system has been performed.
If tabnam translates to the name of a list of tables, $DELLNM does the following:

If you specify the lognam argument, $DELLNM searches (in order) each table in the list until it finds the first table that contains the specified logical name. If the logical name is at the specified access mode, $DELLNM then deletes occurrences of the logical name at the specified access mode and at outer access modes within the table.
If you do not specify the lognam argument, $DELLNM deletes all of the logical names at the specified access mode or at outer access modes from the first table in the list whose access mode is equal to or less privileged than the caller's access mode.

lognam

OpenVMS usage: logical_name

type: character-coded text string

access: read only

mechanism: by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)

mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)

Logical name to be deleted. The lognam argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a descriptor that points to the logical name string.
acmode

OpenVMS usage: access_mode

type: byte (unsigned)

access: read only

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Access mode to be used in the delete operation. The acmode argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a byte containing this access mode. The $PSLDEF macro defines symbolic names for the four access modes.
You determine the access mode actually used in the delete operation by maximizing the access mode of the caller with the access mode specified by the acmode argument; that is, the less privileged of the two is used.
However, if you have SYSNAM privilege, the delete operation is executed at the specified access mode regardless of the caller's access mode.
If you omit this argument or specify it as 0, the access mode of the caller is used in the delete operation. The access mode used in the delete operation determines which tables are used and which names are deleted.

DESCRIPTION

The Delete Logical Name service deletes all logical names with the specified name at the specified access mode or outer access mode, or it deletes all the logical names with the specified access mode or outer access mode in a specified table. If any logical names being deleted are also the names of logical name tables, then all of the logical names contained within those tables and all of their subtables are also deleted.
Required Access or Privileges

Depending on the operation, the calling process might need one of the following access or rights privileges to use $DELLNM:

Write access to the logical name table to delete a name
Either delete access to the logical name table or write access to the directory table that contains the table name to delete a shareable logical name table
SYSNAM privilege to delete a logical name or table at an inner access mode
GRPNAM or SYSPRV privilege to delete a logical name from a group table
SYSNAM or SYSPRV privilege to delete a logical name from a system table

Required Quota

None
Related Services

$CRELNM, $CRELNT, $TRNLNM

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO The service cannot access the locations specified by one or more arguments.

SS$_BADPARAM One or more arguments have an invalid value, or a logical name table name was not specified.

SS$_IVLOGNAM The lognam argument specifies a string whose length is not in the required range of 1 through 255 characters.

SS$_IVLOGTAB The tabnam argument does not specify a logical name table.

SS$_NOLOGNAM The specified logical name table does not exist, or a logical name with an access mode equal to or less privileged than the caller's access mode does not exist in the logical name table.

SS$_NOLOGTAB The specified logical name table does not exist.

SS$_NOPRIV The caller lacks the necessary privilege to delete the logical name.

SS$_TOOMANYLNAM The logical name translation of the table name exceeded the allowable depth (10 translations).

$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 occur 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.
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 the 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.

$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.

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  4527P024.HTM
  OSSG Documentation
  22-NOV-1996 12:59:20.35
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

SS$_NORMAL	Successful completion. All pages within the region have been deleted as well as the region itself.
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$_REGOWNVIO	The region is owned by a more privileged access mode than the access mode of the caller. All pages within the region have been deleted; however, the region has not been deleted.
SS$_PAGOWNVIO	A page within the specified region is owned by a more privileged access mode than the access mode of the caller.

OpenVMS usage:	logical_name
type:	character-coded text string
access:	read only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)
mechanism:	by 32-bit descriptor--fixed-length string descriptor (VAX)

OpenVMS usage:	access_mode
type:	byte (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The service cannot access the locations specified by one or more arguments.
SS$_BADPARAM	One or more arguments have an invalid value, or a logical name table name was not specified.
SS$_IVLOGNAM	The lognam argument specifies a string whose length is not in the required range of 1 through 255 characters.
SS$_IVLOGTAB	The tabnam argument does not specify a logical name table.
SS$_NOLOGNAM	The specified logical name table does not exist, or a logical name with an access mode equal to or less privileged than the caller's access mode does not exist in the logical name table.
SS$_NOLOGTAB	The specified logical name table does not exist.
SS$_NOPRIV	The caller lacks the necessary privilege to delete the logical name.
SS$_TOOMANYLNAM	The logical name translation of the table name exceeded the allowable depth (10 translations).

OpenVMS usage:	channel
type:	word (unsigned)
access:	read only
mechanism:	by value

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.

OpenVMS usage:	process_id
type:	longword (unsigned)
access:	modify
mechanism:	by reference

OpenVMS usage:	process_name
type:	character-coded text string
access:	read only
mechanism:	by descriptor--fixed-length string descriptor

OpenVMS usage:	address_range
type:	longword (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	region identifier
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

Symbol	Region
VA$C_P0	Program region
VA$C_P1	Control region
VA$C_P2	64-bit program region