DosSendSignal
This function has been eliminated since OS/2 2.0 [1]
Contents
Description
This call sends either a SIGINTR or a SIGBREAK signal to a process within a specified process tree.
Syntax
DosSendSignal (PID, SigNumber)
Parameters
- PID (USHORT) - input
- Root process ID of the subtree. It is not necessary that this process be alive, but it is necessary that this process be a direct child process of the process that issues this call.
- SigNumber (USHORT) - input
- Signal to send. It may be:
Value Definition 1 (SIGINTR) Ctrl-C 4 (SIGBREAK) Ctrl-Break.
Return Code
rc (USHORT) - return
Return code descriptions are:
- 0 NO_ERROR
- 1 ERROR_INVALID_FUNCTION
- 156 ERROR_SIGNAL_REFUSED
- 205 ERROR_NO_SIGNAL_SENT
- 209 ERROR_INVALID_SIGNAL_NUMBER
- 303 ERROR_INVALID_PROCID
Remarks
The process that receives the signal is the most distant descendent process among those processes in the tree that have a handler installed for the signal.
The process tree is searched in descending order for processes having a handler installed for the specified signal. If there is at least one eligible process in the tree, the signal is sent to the process that is the most distant descendent process among the eligible processes. The selected process may have descendents, but none of them have the handler installed for the signal. If there is more than one most distant descendent eligible process, the signal is sent to one of them; which one is indeterminate.
Presentation Manager applications may not establish signal handlers for Ctrl-C and Ctrl-Break. Establishing a signal handler for Ctrl-C and Ctrl-Break is supported for VIO-Windowable and full-screen applications.
Example Code
C Binding
#define INCL_DOSSIGNALS USHORT rc = DosSendSignal(PID, SigNumber); USHORT PID; /* PID of root of subtree */ USHORT SigNumber; /* Signal Number to send */ USHORT rc; /* return code */
Example
The following example illustrates the use of the Ctrl-C (SIGINTR) signal to signal time-critical events. Process1 invokes process2, which establishes a signal handler named CtrlC_Handler() and waits, by blocking on a reserved RAM semaphore, for a signal from process1. A portion of process2 is immune to signalling.
/***** process1.c *****/ #define INCL_DOSPROCESS #define INCL_DOSSIGNALS #include <os2.h> #define SLEEPTIME 200L /* Sleep interval */ #define START_PROGRAM "process2.exe" /* Program name */ main() { CHAR ObjFail[50]; PSZ Args; PSZ Envs; RESULTCODES ReturnCodes; USHORT rc; /* Start process2 and check its PID */ if(!(DosExecPgm(ObjFail, /* Object name buffer */ sizeof(ObjFail), /* Length of obj. name buffer */ EXEC_ASYNC, /* Execution flag */ Args, /* Ptr. to argument string */ Envs, /* Ptr. to environment string */ &ReturnCodes, /* Ptr. to resultcodes struct. */ START_PROGRAM))) /* Name of program file */ printf("Process2 started.\n"); printf("Process2 ID is %d\n", ReturnCodes.codeTerminate); /* Sleep to give time slice to process2 */ DosSleep(SLEEPTIME); /* Sleep interval */ /*** After process2 sets signal handler, send process2 a signal ***/ if(!(rc = DosSendSignal(ReturnCodes.codeTerminate, /* PID of process2 */ SIG_CTRLC))) /* Signal to send */ printf("Ctrl-C signal sent from Process1 to Process2.\n"); } /* ----- process2.c ----- */ #define INCL_DOSPROCESS #define INCL_DOSSIGNALS #define INCL_DOSERRORS #include <os2.h> #define SLEEPTIME 50L #define TIMEOUT 5000L VOID APIENTRY CtrlC_Handler(arg1, arg2) /** Define signal handler **/ USHORT arg1; USHORT arg2; { printf("Handler for Ctrl-C now running.\n"); return; } main() { ULONG RamSem = 0L; /* Allocate and initialize Ram Semaphore */ ULONG far *RamSemHandle = &RamSem; /* Ram Semaphore handle */ USHORT rc; /* Establish signal handler */ if(!(rc=DosSetSigHandler((PFNSIGHANDLER) CtrlC_Handler, NULL, /* Previous handler - ignored */ NULL, /* Previous action - ignored */ SIGA_ACCEPT, /* Request type */ SIG_CTRLC))) /* Signal number */ printf("Process2 has set Ctrl-C handler.\n"); else /* Error processing on rc */; /* Get semaphore for first time */ if(!(rc=DosSemRequest(RamSemHandle, /* Semaphore handle */ TIMEOUT))) /* Timeout interval */ printf("Semaphore obtained.\n"); /*** Disable and then enable signal-handling ***/ if(!(rc=DosHoldSignal(HLDSIG_DISABLE))) /** Action code - disable **/ { printf("Signalling DISABLED.\n"); /* Do signal-proof work here */ if(!(rc=DosHoldSignal(HLDSIG_ENABLE))) /** Action code - enable **/ printf("Signalling ENABLED.\n"); } /* At this point, process1 may have sent a Ctrl-C signal. */ /* Try to obtain semaphore again -- resulting in Timeout. */ /* The Timeout, however, may be interrupted by the signal. */ printf("Process2 will now wait on a Ramsem for a while.\n"); if((rc=DosSemRequest(RamSemHandle, /* Semaphore handle */ TIMEOUT)) /* Timeout interval */ == ERROR_INTERRUPT) printf("Process2 interrupted while waiting, rc is %d.\n", rc); }
MASM Binding
EXTRN DosSendSignal:FAR INCL_DOSSIGNALS EQU 1 PUSH WORD PID ;PID of root of subtree PUSH WORD SigNumber ;Signal Number to send CALL DosSendSignal Returns WORD