 |
HP OpenVMS System Services Reference Manual
Required Access or Privileges
$DELETE_PROXY requires access to the proxy database. To achieve access,
the caller must have either SYSPRV privilege or a UIC group less than
or equal to the MAXSYSGRP system parameter.
Required Quota
None
Related Services
$ADD_PROXY, $DISPLAY_PROXY, $VERIFY_PROXY
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
rem_node,
rem_user,
local_user, or
flags argument cannot be read by the service.
|
|
SS$_BADBUFLEN
|
The length of the
rem_node,
rem_user, or
local_user argument was out of range.
|
|
SS$_BADPARAM
|
An invalid flag was specified in the
flags argument.
|
|
SS$_NOSYSPRV
|
The caller does not have access to the proxy database.
|
|
|
|
|
This service can also return any of the following messages passed from
the security server:
|
|
|
|
|
SECSRV$_BADNODENAMELEN
|
The node name length is out of range.
|
|
SECSRV$_BADREMUSERLEN
|
The remote user name length is out of range.
|
|
SECSRV$_INVALIDDELETE
|
You attempted to remove the last local user with no default user
remaining, or you tried to remove the last default user with no local
user remaining. You must have at least one local user or one default
user.
|
|
SECSRV$_NOSUCHPROXY
|
The proxy specified by the
rem_node and
rem_user arguments does not exist in the proxy
database.
|
|
SECSRV$_NOSUCHUSER
|
The specified local user does not exist in the proxy's local user list,
or is not the proxy's default user.
|
|
SECSRV$_PROXYNOTACTIVE
|
Proxy processing is currently stopped. Try the request again later.
|
|
SECSRV$_SERVERNOTACTIVE
|
The security server is not currently active. Try the request again
later.
|
$DELETE_REGION_64 (Alpha and Integrity servers)
On Alpha and Integrity server systems, deletes a virtual region within
the process's address space, including all created virtual addresses
within the region.
This service accepts 64-bit addresses.
Format
SYS$DELETE_REGION_64 region_id_64 ,acmode ,return_va_64
,return_length_64
C Prototype
nt sys$delete_region_64 (struct _generic_64 *region_id_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 to be deleted. The region ID
specified must be one returned by the $CREATE_REGION_64 service. You
cannot specify VA$C_P0, VA$C_P1, or VA$C_P2.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode associated with the call to $DELETE_REGION_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 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. This 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.
|
|
SS$_VA_IN_USE
|
The existing underlying page cannot be deleted because it is associated
with a buffer object.
|
$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 and Integrity server 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 |
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- or 64-bit address 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 |
Logical name to be deleted. The lognam argument is the
32- or 64-bit address 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 |
Access mode to be used in the delete operation. The
acmode argument is the 32- or 64-bit address 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 and delete access to the logical name table to delete a
logical name
- Write access to the directory table that contains the table name,
or SYSPRV privilege, 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$_INSFMEM
|
There is insufficient dynamic memory to build a message describing the
deletion of a clusterwide name.
|
|
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 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] ,[flags]
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.
flags
| OpenVMS usage: |
mask |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The flags argument can be used to control whether exit
handlers are called by $DELPRC. If the flags argument
is not specified or is specified with a zero, the system parameter
DELPRC_EXIT controls what exit handlers, if any, are called by $DELPRC.
The $DELPRCSYMDEF macro defines a symbolic name for EXIT and NOEXIT.
The EXIT flag should be or'd with the access mode defined by the
$PSLDEF macro for the initial exit handler.
The following table describes each flag:
| Flag |
Description |
|
DELPRC$M_EXIT
|
When set, exit handlers as specified by DELPRC$M_MODE are called. This
flag is ignored for a hard suspended process.
|
|
DELPRC$M_MODE
|
2 bit field: values psl$c_kernel, psl$c_exec, psl$c_super, psl$c_user
(from the $PSLDEF macro)
|
|
DELPRC$M_NOEXIT
|
Set to disable any exit handler execution
|
Note
Deleting the current process:
When $DELPRC is used to delete the current process, execution cannot
continue in the mode from which $DELPRC was called. The first exit
handlers that are called will be in the next more privileged mode
relative to the mode from which $DELPRC was called (subject to options
defined). For example:
- $DELPRC called from user mode can call supervisor mode exit
handlers.
- $DELPRC called from exec mode can only execute kernel mode exit
handlers.
- $DELPRC called from kernel mode cannot call exit handlers.
|
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.)
|
|
