View source for $DELPRC

'''$DELPRC''', or '''Delete Process''', is a [[System Service|system service]] that deletes a process.

=Description=
The Delete Process service allows a process to delete itself or another process. If you specify neither the [[#pidadr|pidadr]] nor the [[#prcnam|prcnam]] argument, $DELPRC deletes the calling process; control is not returned. If the longword at address [[#pidadr|pidadr]] is 0, the PID of the target process is returned. This system service requires system dynamic memory.

When you delete a [[Process|process]] or [[Subprocess|subprocess]], a termination message is sent to its creating process, provided the [[Mailbox|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.

=Syntax=

 <nowiki>SYS$DELPRC [</nowiki>[[#pidadr|pidadr]]<nowiki>] ,[</nowiki>[[#prcnam|prcnam]]<nowiki>] ,[</nowiki>[[#flags|flags]]<nowiki>] </nowiki>

C prototype:
 <nowiki> int sys$delprc (unsigned int *pidadr, void *prcnam);</nowiki>

=Arguments=
==pidadr==
{{SyservArgument|process_id|longword (unsigned)|modify|by reference}}

[[PID|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==
{{SyservArgument|process_name|character-coded text string|read only|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==
{{SyservArgument|mask|longword(unsigned)|read only|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:
{| class="wikitable"
! colspan="col" | Flag 
| colspan="col" | 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
|}

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


=Condition Values Returned=
{| class="wikitable"
! colspan="col" | Value
! colspan="col" | Description
|-
| SS$_NORMAL
| This 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.)
|}

=Privileges Required=
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

=Quota Required=
None. Deductible resource quotas granted to subprocesses are returned to the creating process when
the subprocesses are deleted.

=See also=
* [[$CANEXH]]
* [[$CREPRC]]
* [[$DCLEXH]]
* [[$EXIT]]
* [[$FORCEX]]
* [[$GETJPI]]
* [[$GETJPIW]]
* [[$HIBER]]
* [[$PROCESS_SCAN]]
* [[$RESUME]]
* [[$SETPRI]]
* [[$SETPRN]]
* [[$SETPRV]]
* [[$SETRWM]]
* [[$SUSPND]]
* [[$WAKE]]