DosKillProcess (OS/2 1.x)

From EDM2
Jump to: navigation, search

This call flags a process to terminate and returns the termination code to its parent.

Syntax

DosKillProcess (ActionCode, ProcessID)

Parameters

ActionCode (USHORT) - input 
The processes to be flagged for termination.
0 - A process and all its descendant processes. The process must be either the current process or a child process created by the current process. (Detached processes cannot be flagged for termination.) After the indicated process terminates, its descendants are flagged for termination.
1 - Any process. Only the indicated process is flagged for termination.
ProcessID (PID) - input 
Process ID of the process, or root process of the process tree to be flagged for termination.

Return Code

rc (USHORT) - return
Return code descriptions are:
  • 0 NO_ERROR
  • 13 ERROR_INVALID_DATA
  • 303 ERROR_INVALID_PROCID
  • 305 ERROR_NOT_DESCENDANT

Remarks

DosKillProcess allows a process to send the termination signal SIGTERM to another process or group of processes. The default action of the system is to terminate each of the processes. A process can intercept this action by installing a signal handler for SIGTERM with DosSetSigHandler. This gives the process the opportunity to clean up its files before it terminates with DosExit.

If there is no signal handler, the effect on the process is the same as if one of its threads had issued DosExit for the entire process. All file buffers are flushed and the handles opened by the process are closed. However, any internal buffers managed by programs external to OS/2 are not flushed. An example of such a buffer could be a C language library's internal character buffer.

If a parent process is waiting for a child process to end because of a DosCwait request, and the child is sent the SIGTERM signal but does not have a SIGTERM signal handler installed, the DosCwait request returns the "unintercepted DosKillProcess" termination code.

Bindings

C

#define INCL_DOSPROCESS

USHORT  rc = DosKillProcess(ActionCode, ProcessID);

USHORT  ActionCode;    /* Indicate to flag descendant processes */
PID     ProcessID;     /* ID of process or root of process tree */

USHORT  rc;            /* return code */

MASM

EXTRN  DosKillProcess:FAR
INCL_DOSPROCESS     EQU 1

PUSH   WORD    ActionCode    ;Indicator for child process termination
PUSH   WORD    ProcessID     ;ID of the process being terminated
CALL   DosKillProcess

Returns WORD

Example Code

The following example demonstrates how to create a process, obtain process ID information, and kill a process. Process1 invokes process2 to run asynchronously. It obtains and prints some PID information, and then kills process2.

/* ---- process1.c ---- */

#define INCL_DOSPROCESS

#include <os2.h>

#define START_PROGRAM "process2.exe"   /* Program pointer */

main()
{
  CHAR          ObjFail [50];       /* Object name buffer */
  RESULTCODES   ReturnCodes;        /*
  PIDINFO       PidInfo;
  PID           ParentID;           /*
  USHORT        rc;

  printf("Process1 now running. \n");

  /** Start a child process. **/
  if(!(DosExecPgm(ObjFail,            /* Object name buffer */
                  sizeof(ObjFail),    /* Length of obj. name buffer */
                  EXEC_ASYNC,         /* Execution flag - asynchronous */
                  NULL,               /* No args. to pass to process2*/
                  NULL,               /* Process2 inherits process1's environment */
                  &ReturnCodes,       /* Ptr. to resultcodes struct. */
                  START_PROGRAM)))    /* Name of program file */
    printf("Process2 started. \n");

  /** Obtain Process ID information and print it **/
  if(!(rc=DosGetPID(&PidInfo)))       /* Process ID's (returned) */
    printf("DosGetPID: current process ID is %d; thread ID is %d; parent process ID is %d.\n",
            PidInfo.pid, PidInfo.tid, PidInfo.pidParent);
  if(!(rc=DosGetPPID(
           ReturnCodes.codeTerminate, /* Process whose parent is wanted */
           &ParentID)))               /* Address to put parent's PID */
    printf("Child process ID is %d; Parent process ID is %d.\n",
            ReturnCodes.codeTerminate, ParentID);

  /** Terminate process2 **/
  if(!(rc=DosKillProcess(DKP_PROCESSTREE,  /* Action code - kill process and descendants */
                ReturnCodes.codeTerminate)))  /* PID of root of process tree */
    printf("Process2 terminated by process1.\n");
}
/* ---- process2.c ---- */

#define INCL_DOSPROCESS

#include <os2.h>

#define SLEEPTIME   500L
#define RETURN_CODE 0

main()
{
  printf("Process2 now running.\n");

  /* Sleep to allow process1 to kill it */
  DosSleep(SLEEPTIME);                /* Sleep interval */
  DosExit(EXIT_PROCESS,               /* Action Code */
          RETURN_CODE);               /* Result Code */
}