sigdef

sigdef

Define User Signal

Portability: SAS/C extension

SYNOPSIS
DESCRIPTION
RETURN VALUE
SEE ALSO
Signal Generator Routine
Default Routine
Interrupt Control Routine
Executive Routine
Final Routine
Jump Intercept Routine

SYNOPSIS

#include <lcsignal.h>

int sigdef(int signum, void (*dfl)(int),
           int (*intcntl)(int, int, int, int),
           void (*executive)(int, char **, _HANDLER),
           void (*final)(int, char *name);

DESCRIPTION

The signum argument is the signal number. Specify the signal number as one of the codes, SIGUSR1 through SIGUSR8 or SIGASY1 through SIGASY8. Only one definition of each signal number is allowed.

Note: In a UNIX System Services (USS) OS/390 application, SIGUSR1 and SIGUSR2 may be treated as USS signals rather than as SAS/C signals, depending on the use of the oesigsetup function and the way the program is run. Attempting to define a signal controlled by USS OS/390 will cause sigdef to fail. Note that if oesigsetup has not been called when sigdef is invoked, a default call to oesigsetup will be generated, as described in the oesigsetup function description. [cautionend]

The name argument enables you to rename the signal. name is the address of a null-terminated string with a maximum of five characters. The library appends these five characters to the SIG prefix to create the new name. For example, if the name argument specifies EXT , the signal name appears in messages and traces as SIGEXT .

The dfl , intcntl , executive , and final arguments indicate the addresses of functions that provide special processing for the signal. Each of these routines is described in detail later in this appendix. Coding a 0 for any of these arguments indicates that no function is supplied for that type of processing.

Note: If you specify 0 for the dfl argument, the signal is ignored when default handling is in effect. [cautionend]

RETURN VALUE

sigdef returns 0 if it completes successfully or nonzero if it cannot complete. Specifying an invalid signal number or one that has already been defined is the most common reason for failure.

Signal Generator Routine

The signal generator routine is the operating system exit that is invoked when the interrupt occurs; therefore, it is written in assembler language. (This routine can be written in C only if it is always called with C-compatible linkage, including the C use of register 12 and register 13. These conditions are unlikely to be met if this routine is an operating system exit.)

The signal generator routine raises the signal so that the library can detect it by calling the L$CZSYN routine (for synchronous signals) or the L$CZENQ routine (for asynchronous signals). These routines expect calls from assembler code and fully support them. The restrictions described in Restrictions on Synchronous and Asynchronous Signals apply when you can issue calls to L$CZSYN. There are no restrictions on when you can call L$CZENQ. These routines are described in more detail in SAS/C Library Routines for Adding New Signals.

The signal generator routine can build information that is passed to you when the user-defined handler calls siginfo . Refer to the SIGINFO field description in Routine for Synchronous Signals: L$CZSYN for more information.

Default Routine

This routine simply defines what actions should occur when the user does not specify a signal handler for the signal. The default routine is usually coded in C. The initialization routine specifies the address of this routine as the second argument in the call to sigdef . If you do not define this routine, the default action is to ignore the signal. If you prefer to have the program ABEND by default, code this routine to call the abort function.

Note: Refer to the siggen or abend function to specify a particular ABEND code. [cautionend]

Interrupt Control Routine

The interrupt control routine enables you to communicate to the operating system that the handling for a user-defined signal has changed. The interrupt control routine is usually coded in assembler language. The initialization routine specifies the address of this routine as the third argument in the call to sigdef . This routine is called on the following occasions:

when a call to sigblock , sigsetmask , or sigprocmask changes the mask for the signal.
when a call to signal or sigaction requests default or ignore handling, or replaces default or ignore handling with a user-defined handler. If the call to signal merely replaces one user-defined handler function with another, the interrupt control routine may not be called.

The purpose of this routine is to improve performance by eliminating The purpose of this routine is to improve performance by eliminating unnecessary processing. For example, if the operating system's default action for a signal is to ignore the signal, and the C program calls signal with a second argument of SIG_IGN , the interrupt control function can cause the operating system to ignore the signal when it occurs instead of calling an operating system exit. This saves the processing time required to transfer control to the default handler and produces the same results. The linkage to the interrupt control routine is defined as follows: The linkage to the interrupt control routine is defined as follows:

int intcntl(int signum, int ignore, int default, int block,
            int context, struct sigaction *action)

The signum argument to the interrupt control routine specifies the The signum argument to the interrupt control routine specifies the signal number. The ignore and default arguments indicate how your program handles the signal. If ignore is 0, the program has either defined a signal handler or default handling is in effect. If ignore is not 0, the signal is ignored. If default is 0, the program has either defined a signal handler or the signal is to be ignored. If default is not 0, default handling is in effect. (Both ignore and default are nonzero if default handling is in effect and the default action is to ignore the signal.) The block argument is nonzero if the signal is blocked or 0 if the signal is not blocked.

The context argument is an integer indicating the reason that the interrupt control routine was called. The possible values are SC_ACTION , SC_PROCMASK , SC_DEF and SC_COPROCSWT . (These are symbolic values defined in <lcsignal.h> .) SC_ACTION indicates a call as the result of a user call to signal or sigaction , SC_PROCMASK indicates a call as the result of a user call to sigblock , sigsetmask or sigprocmask , SC_DEF indicates a call as the result of the call to sigdef , and SC_COPROCSWT indicates a call as the result of a coprocess switch.

The action argument is meaningful only for calls with context SC_ACTION or SC_DEF . In these cases, action is a pointer to information about the current handling as defined by sigaction . The sa_handler field of the action should be ignored, as it may be different from the current handler. However, the sa_mask and sa_flags fields are guaranteed to be correct. In particular, this functionality allows the interrupt control routine to take special action based on the SA_USRFLAG n flags settings.

The interrupt control routine should return a negative number to indicate an error. If a negative number is returned, the call to signal or sigaction that caused the interrupt control routine to be called returns SIG_ERR . A return code of 1, when the context is SC_BLOCK , indicates that the interrupt control routine takes no action for changes to blocking status. This enables the performance of signal processing to be improved by avoid calls to the interrupt control routine during sigblock , sigsetmask , or sigprocmask processing. Any other positive return code (or a 1 returned when the context is not SC_PROCMASK ) is treated as a success.

Note: An interrupt control routine is rarely required for correct operation of signal code; this routine simply provides improved performance for signals that can be ignored or blocked by the operating system. There may be times, however, when the interrupt control routine actually increases overhead. For example, signals are blocked while I/O is performed, so the interrupt control routine is called several times for each I/O operation. [cautionend]

Executive Routine

The library calls the executive routine, if you code one, instead of calling the handler defined in your program. The executive routine is then expected to call the handler itself. If no executive routine is defined, the handler is called directly. Note that the executive routine is not called for a signal generated by raise or siggen ; thus, the executive routine is entered only when a signal occurs naturally.

The executive routine is usually coded in C. If you code this routine in The executive routine is usually coded in C. If you code this routine in assembler language, use the CENTRY and CEXIT macros to avoid problems calling the user-defined handler. The initialization routine specifies the address of this routine as the fourth argument in the call to sigdef . The linkage to the executive routine is defined as follows:

void executive(int signum, char **infop, void (*handler)(int))

The signum argument is the number of the defined signal. The The signum argument is the number of the defined signal. The infop pointer addresses the pointer that the signal handler in the program can access by a call to siginfo . The executive routine may modify the information addressed by this pointer. The handler argument addresses the user-defined handler or contains 0 if the signal is to be ignored. This address can be used to call the user-defined handler from the executive routine.

The executive routine can be used to monitor or prevent certain handler activity. For instance, you can use blkjmp to prevent successful use of longjmp by the handler, or you can refuse to allow normal return from the handler by calling abort if the handler returns. It is assumed that the executive routine will call the handler using the normal handler linkage, but this cannot be enforced.

Final Routine

The final routine is called on program termination to allow signal-handling to be cancelled. Normally, a final routine is provided to inform the operating system that handling of the interrupt associated with the signal is no longer required. The final routine is usually coded in assembler language.

The final routine is usually coded in assembler language. The initialization routine specifies the address of this routine as the fifth argument in the call to sigdef . The linkage to the final routine is defined as follows:

void final(int signum)

The signum argument is the number of the signal whose handling will be terminated.

The final routine is called after all files have been closed by the library. The final routine is called after all files have been closed by the library. Therefore, this routine is not permitted to use I/O.

Jump Intercept Routine

The jump intercept routine is invoked if a signal handler for a synchronous signal issues a longjmp . This routine must be coded in assembler language. The jump intercept routine can inform the operating system that handling of the interrupt is complete but that control should not return to the point of interrupt. This is sometimes called clearing the interrupt. The jump intercept routine may need to be called before performing the longjmp because the longjmp routine prevents return to the signal generation routine from the handler and, therefore, also prevents normal return to the operating system.

The jump intercept routine is rarely coded because it is frequently impossible to correctly clear the interrupt. If you expect a user-defined handler to call longjmp , you can disallow longjmp or define the signal as asynchronous. The jump intercept routine should not attempt to prevent a longjmp . If you want to disallow jumps, use the executive routine to block them.

The jump intercept routine is not included as an argument in the call to sigdef . To indicate that you want to provide this routine, set the JUMPINT field of the ZSYNARGS DSECT to the address of the jump intercept routine. The jump intercept routine is called using standard OS/390 linkage. Register 1 addresses the save area where registers have been saved (except for register 14 and register 15, which are not available).

Chapter Contents
Previous
Next
Top of Page