en:docs:fapi:dossetsighandler

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
en:docs:fapi:dossetsighandler [2018/08/31 14:13] – created prokusheven:docs:fapi:dossetsighandler [2021/09/18 15:04] (current) – prokushev
Line 1: Line 1:
 +{{page>en:templates:fapiint}}
 +
 +====== DosSetSigHandler ======
 +
 This call notifies OS/2 of a handler for a signal. It may also be used to ignore a signal or install a default action for a signal. This call notifies OS/2 of a handler for a signal. It may also be used to ignore a signal or install a default action for a signal.
  
-==Syntax== +===== Syntax ===== 
- DosSetSigHandler (Routine, PrevAddress, PrevAction, Action, SigNumber)+<code c> 
 +DosSetSigHandler (Routine, PrevAddress, PrevAction, Action, SigNumber) 
 +</code> 
 + 
 +===== Parameters ===== 
 + 
 +  * Routine (PFNSIGHANDLER) - input : Address of the entry point of routine that receives control when a signal equal to SigNumber is received. 
 +  * PrevAddress (PFNSIGHANDLER FAR *) - output: Address of the previous signal handler. This operand may be coded as null (= 0), then it is ignored. 
 +  * PrevAction (PUSHORT) - output : Address of the previous signal action. Only values 0 to 3 are returned. This operand may be coded as null (= 0), then it is ignored. 
 +  * Action (USHORT) - input : Indicates what action to take when the specified signal is received: 
 + 
 +^ Value ^ Definition ^ 
 +| 0 | The system default action is installed for the signal. | 
 +| 1 | The signal is to be ignored. | 
 +| 2 | The routine receives control when the SigNumber occurs. | 
 +| 3 | It is an error for any program to signal this SigNumber to this process. | 
 +| 4 | The current signal is reset without affecting the disposition of the signal. | 
 + 
 +  * SigNumber (USHORT) - input : Signal number to be intercepted by this signal handler. The signal numbers defined are: 
 + 
 +^ Value ^ Definition ^ 
 +| 1 | Ctrl-C (SIGINTR) | 
 +| 3 | Program terminated (SIGTERM) | 
 +| 4 | Ctrl-Break (SIGBREAK) | 
 +| 5 | Process flag A (SIGPFA) | 
 +| 6 | Process flag B (SIGPFB) | 
 +| 7 | Process flag C (SIGPFC) |
  
-==Parameters== 
-;Routine (PFNSIGHANDLER) - input : Address of the entry point of routine that receives control when a signal equal to SigNumber is received. 
-;PrevAddress (PFNSIGHANDLER FAR *) - output: Address of the previous signal handler. This operand may be coded as null (= 0), then it is ignored. 
-;PrevAction (PUSHORT) - output : Address of the previous signal action. Only values 0 to 3 are returned. This operand may be coded as null (= 0), then it is ignored. 
-;Action (USHORT) - input : Indicates what action to take when the specified signal is received: 
- '''Value     Definition''' 
- 0     The system default action is installed for the signal. 
- 1     The signal is to be ignored. 
- 2     The routine receives control when the SigNumber occurs. 
- 3     It is an error for any program to signal this SigNumber to this process. 
- 4     The current signal is reset without affecting the disposition of the signal. 
-; SigNumber (USHORT) - input : Signal number to be intercepted by this signal handler. The signal numbers defined are: 
- '''Value  Definition''' 
- 1      Ctrl-C (SIGINTR) 
- 3      Program terminated (SIGTERM) 
- 4      Ctrl-Break (SIGBREAK) 
- 5      Process flag A (SIGPFA) 
- 6      Process flag B (SIGPFB) 
- 7      Process flag C (SIGPFC) 
 '''Note:''' 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. '''Note:''' 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.
                          
 The following chart indicates what signal to specify to cause the signal handler to get control for the CTRL-C and CTRL-Break key sequences in each of the keyboard modes (ASCII and Binary): The following chart indicates what signal to specify to cause the signal handler to get control for the CTRL-C and CTRL-Break key sequences in each of the keyboard modes (ASCII and Binary):
-{|class="wikitable" +^ ^ ASCII Mode ^ BINARY Mode ^ 
-! ||ASCII Mode||BINARY Mode +|CTRL-C|SIGINTR| | 
-|- +|CTRL-Break|SIGINTR|SIGBREAK|
-|CTRL-C||SIGINTR|| +
-|- +
-|CTRL-Break||SIGINTR||SIGBREAK +
-|}+
  
-==Return Code== +===== Return Code ===== 
-;rc (USHORT) - return:Return code descriptions are: + 
-* 0   NO_ERROR +rc (USHORT) - return:Return code descriptions are: 
-*     ERROR_INVALID_FUNCTION + 
-* 209 ERROR_INVALID_SIGNAL_NUMBER  +  * 0   NO_ERROR 
-* 210 ERROR_THREAD_1_INACTIVE+  *     ERROR_INVALID_FUNCTION 
 +  * 209 ERROR_INVALID_SIGNAL_NUMBER  
 +  * 210 ERROR_THREAD_1_INACTIVE 
 + 
 +===== Remarks =====
  
-==Remarks== 
 When the signal indicated by SigNumber occurs, the signal handling routine receives control with: When the signal indicated by SigNumber occurs, the signal handling routine receives control with:
- (SS:SP)     Far return address  + 
- (SS:SP+4)   SigNumber being processed  +(SS:SP)     Far return address  
- (SS:SP+6)   SigArg furnished on the DosFlagProcess request, if appropriate.+(SS:SP+4)   SigNumber being processed  
 +(SS:SP+6)   SigArg furnished on the DosFlagProcess request, if appropriate. 
 Other than SS, SP, CS, IP and flags, all registers contain the same values they contained at the time the signal was received. The handler may exit by executing an intersegment return instruction, or by manually setting the stack frame to some known state and jumping to some known location. If the former option is selected, execution resumes where it was interrupted, and all registers are restored to their values at the time of the interruption. Other than SS, SP, CS, IP and flags, all registers contain the same values they contained at the time the signal was received. The handler may exit by executing an intersegment return instruction, or by manually setting the stack frame to some known state and jumping to some known location. If the former option is selected, execution resumes where it was interrupted, and all registers are restored to their values at the time of the interruption.
  
Line 59: Line 71:
  
 Initially, a session has no signal focus for SIGINTR (or SIGBREAK). A process becomes the signal focus for SIGINTR ( or SIGBREAK) within its session if it calls DosSetSigHandler with ActionCode equal to 1, 2, or 3. A process remains the signal focus until: Initially, a session has no signal focus for SIGINTR (or SIGBREAK). A process becomes the signal focus for SIGINTR ( or SIGBREAK) within its session if it calls DosSetSigHandler with ActionCode equal to 1, 2, or 3. A process remains the signal focus until:
-* The process terminates.  +  * The process terminates.  
-* The process calls DosSetSigHandler with ActionCode equal to zero.  +  * The process calls DosSetSigHandler with ActionCode equal to zero.  
-* Another process calls DosSetSigHandler with ActionCode equal to 1, 2, or 3. +  * Another process calls DosSetSigHandler with ActionCode equal to 1, 2, or 3. 
  
 In the first two cases, the parent or its closest related ancestor process that has a handler installed for the appropriate signal becomes the focus. If no eligible process exists, the session ceases to have a signal focus for that signal. In the first two cases, the parent or its closest related ancestor process that has a handler installed for the appropriate signal becomes the focus. If no eligible process exists, the session ceases to have a signal focus for that signal.
Line 67: Line 79:
 If a device driver makes a SendEvent call for CTRL-C or CTRL-BREAK and the current session has no focus for the corresponding signal, all processes in the session are signaled with SIGTERM to terminate. If a device driver makes a SendEvent call for CTRL-C or CTRL-BREAK and the current session has no focus for the corresponding signal, all processes in the session are signaled with SIGTERM to terminate.
  
-==Family API Considerations==+==== Family API Considerations ==== 
 Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction applies to DosSetSigHandler when coding in DOS mode: Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction applies to DosSetSigHandler when coding in DOS mode:
-* The only signals recognized in DOS are SIGINTR (Ctrl-C) and SIGBREAK. +  * The only signals recognized in DOS are SIGINTR (Ctrl-C) and SIGBREAK. 
-* The option Action=3 generates an "invalid signal number" error. +  * The option Action=3 generates an "invalid signal number" error. 
-* If SigNumber is any value other than SIGINTR or SIGBREAK, then an "invalid signal number" error is generated.+  * If SigNumber is any value other than SIGINTR or SIGBREAK, then an "invalid signal number" error is generated.
  
 SIGINTR is fully supported, and SIGBREAK is related to SIGINTR. Therefore, if SIGINTR is specified, both SIGINTR and SIGBREAK are transferred to the SIGINTR handler. SIGBREAK is permitted as a coded value, but the request to set SIGBREAK is ignored. To be compatible in all environments, SIGBREAK and SIGINTR should be considered together in all cases. SIGINTR is fully supported, and SIGBREAK is related to SIGINTR. Therefore, if SIGINTR is specified, both SIGINTR and SIGBREAK are transferred to the SIGINTR handler. SIGBREAK is permitted as a coded value, but the request to set SIGBREAK is ignored. To be compatible in all environments, SIGBREAK and SIGINTR should be considered together in all cases.
  
-===C Binding=== +===== Bindings ===== 
-<PRE>+ 
 +==== C Binding ==== 
 + 
 +<code c>
 #define INCL_DOSSIGNALS #define INCL_DOSSIGNALS
  
Line 89: Line 105:
  
 USHORT              rc;          /* return code */ USHORT              rc;          /* return code */
-</PRE>+</code> 
 + 
 + 
 +==== MASM Binding ==== 
 + 
 +<code asm> 
 +EXTRN  DosSetSigHandler:FAR 
 +INCL_DOSSIGNALS     EQU 1 
 + 
 +PUSH@  DWORD   Routine        ;Signal handler 
 +PUSH@  DWORD   PrevAddress    ;Previous handler (returned) 
 +PUSH@  WORD    PrevAction     ;Previous action (returned) 
 +PUSH   WORD    Action         ;Indicate request type 
 +PUSH   WORD    SigNumber      ;Signal number of interest 
 +CALL   DosSetSigHandler 
 + 
 +Returns WORD 
 +</code> 
 + 
 +===== Example =====
  
-==Example== 
 The following example illustrates the use of a user-defined flag to signal time-critical events. The main thread installs a routine, named FlagA_Handler(), as the signal handler for user-defined Flag A. It then creates a thread and blocks on a reserved RAM semaphore; this thread obtains its process ID and signals the main thread via Flag A. The main thread responds by executing the signal handler. The following example illustrates the use of a user-defined flag to signal time-critical events. The main thread installs a routine, named FlagA_Handler(), as the signal handler for user-defined Flag A. It then creates a thread and blocks on a reserved RAM semaphore; this thread obtains its process ID and signals the main thread via Flag A. The main thread responds by executing the signal handler.
-<PRE>+<code c>
 #define INCL_DOSPROCESS #define INCL_DOSPROCESS
 #define INCL_DOSSIGNALS #define INCL_DOSSIGNALS
Line 160: Line 194:
   printf("Main thread interrupted while waiting, rc is %d.\n", rc);   printf("Main thread interrupted while waiting, rc is %d.\n", rc);
 } }
-</PRE> +</code>
- +
-===MASM Binding=== +
-<PRE> +
-EXTRN  DosSetSigHandler:FAR +
-INCL_DOSSIGNALS     EQU 1 +
- +
-PUSH@  DWORD   Routine        ;Signal handler +
-PUSH@  DWORD   PrevAddress    ;Previous handler (returned) +
-PUSH@  WORD    PrevAction     ;Previous action (returned) +
-PUSH   WORD    Action         ;Indicate request type +
-PUSH   WORD    SigNumber      ;Signal number of interest +
-CALL   DosSetSigHandler +
- +
-Returns WORD +
-</PRE> +
  
  
-====== Note ======+===== Note =====
  
 Text based on [[http://www.edm2.com/index.php/DosSetSigHandler]] Text based on [[http://www.edm2.com/index.php/DosSetSigHandler]]