Chapter Contents |
Previous |
Next |
sigdef |
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.
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.
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.
SEE ALSO |
Chapter 5, "Signal-Handling Functions," in SAS/C Library Reference, Volume 1.
Signal Generator Routine |
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.
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:
sigblock
,
sigsetmask
,
or
sigprocmask
changes
the mask for the signal.
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.
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 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.
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 |
Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.