signal: Install signal handler

This function permits a process to choose one of several ways to handle a condition sig from the raise, tpf_process_signals, or wait function.

Note: The signal function is similar to the sigaction function.

Last updated

Changed for PUT14.

Format

#include <signal.h>
void(*signal (int sig, void(*func)(int)))(int);

sig

One of the signals defined in the signal.h header file. Table 1 lists the signals that are supported.

Table 1. Signals supported in the C/C++ environment
Value	Default handler action	Meaning
SIGABND	2	Abnormal end signal.
SIGABRT	1	Abnormal end (sent by the `abort` function).
SIGALRM	1	Timeout signal, such as is started by the `alarm` function.
SIGCHLD	3	Abnormal end, such as is initialized by the `abort` function.
SIGFPE	2	Arithmetic exceptions that are not masked; for example, overflow, division by zero, and incorrect operation.
SIGHUP	1	Hangup detected on controlling terminal or end of controlling process.
SIGILL	2	Detection of an incorrect function image.
SIGINT	1	Interactive attention.
SIGIOERR	3	Intended for input/output (I/O) error.
SIGIQUIT	1	Quit signal.
SIGJVM1	1	Intended for use by the IBM® J9 virtual machine (JVM).
SIGKILL	1	Termination signal. See note.
SIGPIPE	1	An attempt to write to a pipe when the pipe is not open for reading.
SIGSEGV	2	Incorrect access to storage.
SIGTERM	1	Termination request sent to the program. See note.
SIGUSR1	1	Intended for use by user applications.
SIGUSR2	1	Intended for use by user applications.
Note: The SIGKILL signal cannot be caught or ignored; therefore, it cannot be set using the `signal` function. If the `signal` function is coded to catch or ignore the SIGKILL signal, an error is returned. All signals, including the SIGKILL signal, remain pending (are not handled) by applications in the z/TPF system unless the `sleep`, `tpf_process_signals`, `wait`, or `waitpid` function is called.

In Table 1 the default handler actions are:

1: Abnormal termination of the entry control block (ECB).
2: Exit entry control block (ECB) with an OPR-7777 system error dump.
3: Ignored and control returns.

func

One of the macros (SIG_DFL or SIG_IGN), defined in the signal.h header file, or a function address.

The action taken when the interrupt signal is received depends on the value of func.

SIG_DFL: Default handling for the signal occurs. See Table 1 for default handler actions for each signal.
SIG_IGN: Ignore the signal. Control returns to the point where the signal was raised.

Otherwise, func points to a signal handler function.

When the signal is handled, the signal handler is reset to the default handler (the equivalent of signal(sig, SIG_DFL); is run) and func (the equivalent of (*func)(sig);) is run. The func function can end by processing a return statement or by calling the abort, exit, or longjmp function. If func processes a return statement, the program resumes at the point the signal was raised.

Normal return

If successful, the call to signal returns the most recent value of func.

Error return

If there is an error in the call, the signalfunction returns a value of -1 and a positive value in errno.

Programming considerations

When either the sigaction or the signal function is used to change a signal action, the new signal action replaces the previous signal action regardless of whether the previous signal action was installed by a sigaction or signal function.
The default setting is the handler, which is set for each of the signals during C environment initialization and when handler is reset on a call to the raise function.
The default actions for SIG_DFL are in segment CSIGDP. This can be modified to change SIG_DFL actions for each of the signals system-wide.
There is no static storage base switching support in activating the signal processor function set by calling the signal function. This does not cause problems when the signal processor is a library function or a C shared object (CSO). Stub linkage handles static storage base switching.
When the signal handler function is internal to the CSO where the signal function is called to set the handler, the raise function for that signal can only be called from the same CSO.
The z/TPF system does not send any hardware signals. Signals can be sent by the kill function and the SIGCHLD signal can be sent to the parent of an exiting process that was created by the tpf_fork function.
Signal handlers set to SIG_IGN in the parent process are set to SIG_IGN in the child process. Other handlers are set to SIG_DFL in the child process.

Examples

This example shows how to establish a signal handler.

#include <signal.h>
#include <stdio.h>
#include <stdlib.h>
#define  ONE_K  1024
void StrCln(int);
void DoWork(char **, int);
void ADLM(int size) {
  char *buffer;
  if (signal((SIGUSR1), StrCln) == SIG_ERR) {
    printf("Could not install user signal");
    abort();
  DoWork(&buffer, size);
  return;
}
void StrCln(int SIG_TYPE) {
  printf("Failed trying to malloc storage\n");
  return;
}

void DoWork(char **buffer, int size) {
  while (*buffer !=NULL)
    *buffer = (char *)malloc(size*ONE_K);
  if (*buffer == NULL) {
     if (raise(SIGUSR1)) {
        printf("Could not raise user signal");
        abort();
     }
  }
  return;
}

See z/TPF C functions overview for more information about z/TPF C/C++ language support.