DosKillProcess (OS/2 1.x)
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 */ }