DosKillThread

Description

Flags a process to end, and returns the termination code to its parent (if any).

Syntax

#define INCL_DOSPROCESS
#include <os2.h>

ULONG   action;  /* The processes to be flagged for ending. */
PID     pid;     /* Process ID of the process or root process of the process tree 
                    to be flagged for ending. */
APIRET  ulrc;    /* Return Code. */

ulrc = DosKillProcess(action, pid);

Parameters

action (ULONG) - input

The processes to be flagged for ending.

The values of this field are shown in the following list:

DKP_PROCESSTREE : A process and all its descendant processes. The process must be either the current process, or it must have been directly created by the current process using DosExecPgm with a value of 2 (EXEC_ASYNCRESULT) for execFlag.

After the indicated process ends, its descendants are flagged for ending. The indicated process need not still be executing. If it has ended, its descendants are still flagged for ending.

DKP_PROCESS : Any process. Only the indicated process is flagged for ending.

pid (PID) - input

Process ID of the process or root process of the process tree to be flagged for ending.

Return Code

ulrc (APIRET) - returns

DosKillProcess returns one of the following values:

• 0 NO_ERROR
• 13 ERROR_INVALID_DATA
• 217 ERROR_ZOMBIE_PROCESS
• 303 ERROR_INVALID_PROCID
• 305 ERROR_NOT_DESCENDANT

Remarks

DosKillProcess allows a process to send the KILLPROCESS exception to another process or group of processes. The default action of the system is to end each of the processes. A process may intercept this action by installing an exception handler for the KILLPROCESS exception (see DosSetExceptionHandler). In such a case, the program will ensure the integrity of its files, and then issue DosExit.

If there is no exception handler, or if no handler handles the exception, then DosKillProcess affects the process as if one of its threads has issued DosKillProcess for the entire process. All file buffers are written, and the handles opened by the process are closed. Any internal buffers managed by the program externally of the system are not written. An example of such a buffer is a C-language library internal character buffer.

The parent of the process gets the "Unintercepted DosKillProcess" termination code when it issues DosWaitChild.

The "ERROR_ZOMBIE_PROCESS" error code indicates that the specified process has ended, but its parent has not yet issued DosWaitChild to get its return code.

Example Code

This example uses DosKillProc to kill itself. It creates and opens a queue as a way of getting the PID for the process. In the end, it sleeps for up to 45 seconds, to ensure that the process was killed by this API.

#define INCL_DOSQUEUES   /* DOS Queue values */
#define INCL_DOSPROCESS  /* DOS thread and process values */
#define INCL_DOSERRORS   /* DOS error values */
#include <os2.h>
#include <stdio.h>
#include <string.h>

int main(USHORT argc, PCHAR argv[]) {

   PSZ         szQueueName  = "\\QUEUES\\OF\\DATA\\WAITING\\FOR\\SERVICE";
   HQUEUE      hqSpecialQue = NULLHANDLE; /* Queue handle                   */
   REQUESTDATA Request      = {0};        /* Reques */
   PID         pidOwner     = 0;
   APIRET      rc           = NO_ERROR;   /* Return code                    */

   rc = DosCreateQueue(&hqSpecialQue,    /* Queue handle                    */
             QUE_FIFO |                  /* First-In First-Out order        */
             QUE_CONVERT_ADDRESS,        /* Convert 16-bit addresses to 32  */
             szQueueName);               /* Name of the queue to create     */

   if (rc!= NO_ERROR) {
      printf ("DosCreateQueue error: return code = %u\n", rc);
      return 1;       }

   rc = DosOpenQueue (&pidOwner,         /* PID of queue owner              */
                      &hqSpecialQue,     /* Handle for created queue        */
                      szQueueName);      /* Name of the queue to open       */

   if (rc!= NO_ERROR) {
      printf ("DosOpenQueue error: return code = %u\n", rc);
      return 1;       }

           /* Kill the queue owner (which is us) */

   rc = DosKillProcess(0, pidOwner);
   if (rc != NO_ERROR) {
      printf("DosKillProcess error: return code = %u\n", rc);
      return 1;
   }

   rc = DosSleep(45000L);    /* Dead code */

   return NO_ERROR;
}

Related Functions

• DosExecPgm
• DosExit
• DosExitList
• DosKillThread
• DosWaitChild