no way to compare when less than two revisions
Differences
This shows you the differences between two versions of the page.
Next revision | |||
— | en:docs:fapi:dosholdsignal [2018/08/31 13:16] – created prokushev | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | This call temporarily disables or enables signal processing for the current process. | ||
+ | |||
+ | ==Syntax== | ||
+ | | ||
+ | |||
+ | ==Parameters== | ||
+ | ;ActionCode (USHORT) - input : Disables or enables signals intended for the current process. | ||
+ | ''' | ||
+ | | ||
+ | | ||
+ | |||
+ | ==Return Code== | ||
+ | rc (USHORT) - return | ||
+ | Return code descriptions are: | ||
+ | * 0 NO_ERROR | ||
+ | * 1 ERROR_INVALID_FUNCTION | ||
+ | |||
+ | ==Remarks== | ||
+ | DosHoldSignal with ActionCode = 1 causes signal processing (except central processing errors and numeric processor errors) to be postponed until a DosHoldSignal with ActionCode = 0 is issued. Any signals that occur while processing is disabled are recognized, but not accepted until signal recognition is enabled. | ||
+ | |||
+ | To allow for nesting of requests, a count of the number of outstanding DosHoldSignal requests with ActionCode = 1 are maintained. | ||
+ | |||
+ | DosHoldSignal is used by library routines, subsystems, and similar code that lock critical sections or temporarily reserve resources needed to prevent a signal from terminating a task. A process can have only one signal handling address for each signal. Dynalink routines should not have a signal handler (which might override a handler established by a calling process). | ||
+ | |||
+ | Signals can be held for a short period and should be released and re-held, if necessary. Their guidelines for proper use are similar to hardware interrupt counterparts such as the CLI/STI instructions. | ||
+ | |||
+ | ===Family API Considerations=== | ||
+ | Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following restriction applies to DosHoldSignal when coding for the DOS mode: | ||
+ | |||
+ | The only signal recognized in the DOS mode is SIGINTR (Ctrl-C) and SIGBREAK. Only SIGINTR and SIGBREAK are turned off by this call. | ||
+ | |||
+ | ===C Binding=== | ||
+ | <PRE> | ||
+ | #define INCL_DOSSIGNALS | ||
+ | |||
+ | USHORT | ||
+ | |||
+ | USHORT | ||
+ | |||
+ | USHORT | ||
+ | </ | ||
+ | |||
+ | ==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. | ||
+ | <PRE> | ||
+ | #define INCL_DOSPROCESS | ||
+ | #define INCL_DOSSIGNALS | ||
+ | |||
+ | #include < | ||
+ | |||
+ | #define SLEEPTIME | ||
+ | #define START_PROGRAM | ||
+ | |||
+ | |||
+ | main() | ||
+ | { | ||
+ | CHAR ObjFail[50]; | ||
+ | PSZ Args; | ||
+ | PSZ Envs; | ||
+ | RESULTCODES | ||
+ | USHORT | ||
+ | |||
+ | /* Start process2 and check its PID */ | ||
+ | if(!(DosExecPgm(ObjFail, | ||
+ | sizeof(ObjFail), | ||
+ | EXEC_ASYNC, | ||
+ | Args, /* Ptr. to argument string */ | ||
+ | Envs, /* Ptr. to environment string */ | ||
+ | & | ||
+ | START_PROGRAM))) | ||
+ | printf(" | ||
+ | printf(" | ||
+ | |||
+ | /* Sleep to give time slice to process2 */ | ||
+ | DosSleep(SLEEPTIME); | ||
+ | |||
+ | /*** After process2 sets signal handler, send process2 a signal ***/ | ||
+ | if(!(rc = DosSendSignal(ReturnCodes.codeTerminate, | ||
+ | SIG_CTRLC))) | ||
+ | printf(" | ||
+ | } | ||
+ | |||
+ | /* ----- process2.c ----- */ | ||
+ | |||
+ | #define INCL_DOSPROCESS | ||
+ | #define INCL_DOSSIGNALS | ||
+ | #define INCL_DOSERRORS | ||
+ | |||
+ | #include < | ||
+ | |||
+ | #define SLEEPTIME | ||
+ | #define TIMEOUT | ||
+ | |||
+ | |||
+ | VOID APIENTRY CtrlC_Handler(arg1, | ||
+ | USHORT | ||
+ | USHORT | ||
+ | { | ||
+ | printf(" | ||
+ | return; | ||
+ | } | ||
+ | |||
+ | main() | ||
+ | { | ||
+ | ULONG RamSem = 0L; /* Allocate and initialize Ram | ||
+ | Semaphore */ | ||
+ | ULONG far *RamSemHandle = & | ||
+ | USHORT | ||
+ | |||
+ | /* Establish signal handler */ | ||
+ | if(!(rc=DosSetSigHandler((PFNSIGHANDLER) CtrlC_Handler, | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | printf(" | ||
+ | else | ||
+ | |||
+ | /* Error processing on rc */; | ||
+ | /* Get semaphore for first time */ | ||
+ | if(!(rc=DosSemRequest(RamSemHandle, | ||
+ | TIMEOUT))) | ||
+ | printf(" | ||
+ | |||
+ | /*** Disable and then enable signal-handling ***/ | ||
+ | if(!(rc=DosHoldSignal(HLDSIG_DISABLE))) | ||
+ | { | ||
+ | printf(" | ||
+ | |||
+ | /* Do signal-proof work here */ | ||
+ | if(!(rc=DosHoldSignal(HLDSIG_ENABLE))) | ||
+ | printf(" | ||
+ | } | ||
+ | /* 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(" | ||
+ | if((rc=DosSemRequest(RamSemHandle, | ||
+ | | ||
+ | == ERROR_INTERRUPT) | ||
+ | printf(" | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | ===MASM Binding=== | ||
+ | <PRE> | ||
+ | EXTRN DosHoldSignal: | ||
+ | INCL_DOSSIGNALS | ||
+ | |||
+ | PUSH | ||
+ | CALL | ||
+ | |||
+ | Returns NONE | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ | ====== Note ====== | ||
+ | |||
+ | Text based on [[http:// | ||
+ | |||
+ | {{page> | ||
+ | |||
+ | |||