sigaction() — Examine or change a signal action

Standards

Standards / Extensions C or C++ Dependencies

POSIX.1
XPG4
XPG4.2
Single UNIX Specification, Version 3

both

POSIX(ON)

Format

#define _POSIX_SOURCE
#include <signal.h>

int sigaction(int sig, const struct sigaction *__restrict__ new, 
              struct sigaction *__restrict__ old);

General description

Examines and changes the action associated with a specific signal.

int sig is the number of a recognized signal. sigaction() examines and sets the action to be associated with this signal. See Table 1 for the values of sig, as well as the signals supported by z/OS® UNIX services. The sig argument must be one of the macros defined in the signal.h header file.

const struct sigaction *new may be a NULL pointer. If so, sigaction() merely determines the action currently defined to handle sig. It does not change this action. If new is not NULL, it should point to a sigaction structure. The action specified in this structure becomes the new action associated with sig.

struct sigaction *old points to a memory location where sigaction() can store a sigaction structure. sigaction() uses this memory location to store a sigaction structure describing the action currently associated with sig. old can also be a NULL pointer, in which case sigaction() does not store this information.

This function is supported only in a POSIX program.

Special behavior for C++:
  • The behavior when mixing signal-handling with C++ exception handling is undefined. Also, the use of signal-handling with constructors and destructors is undefined.
  • C++ and C language linkage conventions are incompatible, and therefore sigaction() cannot receive C++ function pointers. If you attempt to pass a C++ function pointer to sigaction(), the compiler will flag it as an error. Therefore, to use the sigaction() function in the C++ language, you must ensure that signal handler routines established have C linkage, by declaring them as extern "C".
Signals: Table 1 lists signal values and their default action and meaning.
Table 1. Signal values and signals supported by z/OS UNIX services
Value Default Action Meaning
SIGABND 1 Abend.
SIGABRT 1 Abnormal termination (sent by abort()).
SIGALRM 1 A timeout signal (sent by alarm()).
SIGBUS 1 Bus error (available only when running on MVS™ 5.2 or higher).
SIGFPE 1 Arithmetic exceptions that are not masked, for example, overflow, division by zero, and incorrect operation.
SIGHUP 1 A controlling terminal is suspended, or the controlling process ended.
SIGILL 1 Detection of an incorrect function image.
SIGINT 1 Interactive attention.
SIGKILL 1 A termination signal that cannot be caught or ignored.
SIGPIPE 1 A write to a pipe that is not being read.
SIGPOLL 1 Pollable event occurred (available only when running on MVS 5.2 or higher).
SIGPROF 1 Profiling timer expired (available only when running on MVS 5.2 or higher).
SIGQUIT 1 A quit signal for a terminal.
SIGSEGV 1 Incorrect access to memory.
SIGSYS 1 Bad system call issued (available only when running on MVS 5.2 or higher).
SIGTERM 1 Termination request sent to the program.
SIGTRAP 1 Internal for use by dbx or ptrace.
SIGURG 2 High bandwidth data is available at a socket (available only when running on MVS 5.2 or higher).
SIGUSR1 1 Intended for use by user applications.
SIGUSR2 1 Intended for use by user applications.
SIGVTALRM 1 Virtual timer has expired (available only when running on MVS 5.2 or higher).
SIGXCPU 1 CPU time limit exceeded (available only when running on MVS 5.2 or higher). If a process runs out of CPU time and SIGXCPU is caught or ignored, a SIGKILL is generated.
SIGXFSZ 1 File size limit exceeded.
SIGCHLD 2 An ended or stopped child process (SIGCLD is an alias name for this signal).
SIGIO 2 Completion of input or output.
SIGIOERR 2 A serious I/O error was detected.
SIGWINCH 2 Window size has changed (available only when running on MVS 5.2 or higher).
SIGSTOP 3 A stop signal that cannot be caught or ignored.
SIGTSTP 3 A stop signal for a terminal.
SIGTTIN 3 A background process attempted to read from a controlling terminal.
SIGTTOU 3 A background process attempted to write to a controlling terminal.
SIGCONT 4 If stopped, continue.
The Default Actions in Table 1 are:
1
Normal termination of the process.
2
Ignore the signal.
3
Stop the process.
4
Continue the process if it is currently stopped. Otherwise, ignore the signal.

If the main program abends in a way that is not caught or handled by the operating system or application, z/OS UNIX terminates the running application with a KILL -9. If z/OS UNIX gets control in EOT or EOM and the terminating status has not been set, z/OS UNIX sets it to appear as if a KILL -9 occurred.

If a signal catcher for a SIGABND, SIGFPE, SIGILL or SIGSEGV signal runs as a result of a program check or an ABEND, and the signal catcher executes a RETURN statement, the process will be terminated.

sigaction structure: The sigaction structure is defined as follows:
             struct sigaction {
                   void       (*sa_handler)(int);
                   sigset_t   sa_mask;
                   int        sa_flags;
                   void       (*sa_sigaction)(int, siginfo_t *, void *);
             };
The following are members of the structure:
void (*)(int) sa_handler
A pointer to the function assigned to handle the signal. The value of this member can also be SIG_DFL (indicating the default action) or SIG_IGN (indicating that the signal is to be ignored).

Special behavior for XPG4.2: This member and sa_sigaction are mutually exclusive of each other. When the SA_SIGINFO flag is set in sa_flags then sa_sigaction is used. Otherwise, sa_handler is used.

sigset_t sa_mask
A signal set identifies a set of signals that are to be added to the signal mask of the calling process before the signal-handling function sa_handler or sa_sigaction (in XPG4.2) is invoked. For more on signal sets, see sigemptyset() — Initialize a signal mask to exclude all signals. You cannot use this mechanism to block SIGKILL, SIGSTOP, or SIGTRACE. If sa_mask includes these signals, they will simply be ignored; sigaction() will not return an error.

sa_mask must be set by using one or more of the signal set manipulation functions: sigemptyset(), sigfillset(), sigaddset(), or sigdelset()

int sa_flags
A collection of flag bits that affect the behavior of signals. The following flag bits can be set in sa_flags:
_SA_IGNORE
This bit is output only and cannot be specified by the application. The handler value will be saved and returned on subsequent calls, but the signal is ignored.
SA_NOCLDSTOP
Tells the system not to issue a SIGCHLD signal when child processes stop. This is relevant only when the sig argument of sigaction() is SIGCHLD.
SA_NOCLDWAIT
Tells the system not to create 'zombie' processes when a child process dies. This is relevant only when the sig argument of sigaction() is SIGCHLD. If the calling process subsequently waits for its children, and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate. The wait(), waitid(), or waitpid() will fail and set errno to ECHILD.
SA_NODEFER
Tells the system to bypass automatically blocking this signal when invoking a signal handler function.
_SA_OLD_STYLE
Tells the C runtime library to use ANSI signal delivery rules, instead of POSIX rules. It is supported for compatibility with applications that use signal() to set signal action. (See signal() — Handle interrupts.) For a description of ANSI and POSIX.1 signal delivery rules, find “Handling Error Conditions and Signals” in z/OS XL C/C++ Programming Guide.
SA_ONSTACK
Tells the system to use the alternate signal stack (see sigaltstack() — Set or get signal alternate stack context or sigstack() — Set or get signal stack context) when invoking a signal handler function. If an alternate signal stack has not been declared, the signal handler function will be invoked with the current stack.
SA_RESETHAND
Tells the system to reset the signal's action to SIG_DFL and clear the SA_SIGINFO flag before invoking a signal handler function (Note: SIGILL and SIGTRAP cannot be automatically reset when delivered. However, no error will be generated should this situation exist). Otherwise, the disposition of the signal will not be modified on entry to the signal handler.

In addition, if this flag is set, sigaction() behaves as if the SA_NODEFER flag were also set.

SA_RESTART
Tells the system to restart certain library functions if they should be interrupted by a signal. The functions that this restartability applies to are all of those that are defined as interruptible by signals and set errno to EINTR (except pause(), sigpause(), and sigsuspend()).
Table 2 lists functions that are restartable if interrupted by a signal.
Table 2. Functions that are restartable if interrupted by a signal
accept() fstatvfs() recvmsg()
catclose() fsync() select()
catgets() ftruncate() semop()
chmod() getgrgid() send()
chown() getgrnam() sendmsg()
close() getmsg() sendto()
closedir() getpass() statvfs()
connect() getpwnam() tcdrain()
creat() getpwuid() tcflow()
dup2() ioctl() tcflush()
endgrent() lchown() tcgetattr()
fchmod() lockf() tcgetpgrp()
fchown() mkfifo() tcsendbreak()
fclose() msgrcv() tcsetattr()
fcntl() msgxrcv() tcsetpgrp()
fflush() msgsnd() tmpfile()
fgetc() open() umount()
fgetwc() poll() wait()
fopen() putmsg() waitid()
fputc() read() waitpid()
fputwc() readv() write()
freopen() recv()  
fseek() recvfrom()  
SA_SIGINFO
Tells the system to use the signal action specified by sa_sigaction instead of sa_handler.
When this flag is off and the action is to catch the signal, the signal handler function specified by sa_handler is invoked as:

   void  function(int signo);

Where signo is the only argument to the signal handler and it specifies the type of signal that has caused the signal handler function to be invoked.
When this flag is on and the action is to catch the signal, the signal handler function specified by sa_sigaction is invoked as:

   void  function(int signo, siginfo_t *info, void *context);

Where two additional arguments are passed to the signal handler function. If the second argument is not a NULL pointer, it will point to an object of type siginfo_t which provides additional information about the source of the signal. A siginfo_t object is a structure contains the following members:
si_signo
Contains the system-generated signal number
si_errno
Contains the implementation-specific error information (it is not used on this implementation)
si_code
Contains a code identifying the cause of the signal (refer to the <signal.h> include file for a list of these codes and for their meanings, see Table 1).

If si_signo contains SIGPOLL then si_code can be set to SI_ASYNCIO. Otherwise, if the value of si_code is less than or equal to zero then the signal was generated by another process and the si_pid and si_uid members respectively indicate the process ID and the real user ID of the sender of this signal.

If the value of si_code is less than or equal to zero, then the signal was generated by another process and the si_pid and si_uid members respectively indicate the process ID and the real user ID of the sender of this signal.

si_pid
If the value of si_code is less than or equal to zero, then this member will indicate the process ID of the sender of this signal. Otherwise, this member is meaningless.
si_uid
If the value of si_code is less than or equal to zero, then this member will indicate the real user ID of the sender of this signal. Otherwise, this member is meaningless.
si_value
If si_code is SI_ASYNCIO the si_value contains the application specified value. Otherwise, the contents of si_value are undefined
The third argument will point to an object of type ucontext_t (refer to the <ucontext.h> include file for a description of the contents of this object).
Note: The remaining flag bits are reserved for system use. There is no guarantee that the integer value of "int sa_flags" will be the same upon return from sigaction(). However, all flag bits defined above will remain unchanged.
void (*)(int, siginfo_t *, void *) sa_sigaction
A pointer to the function assigned to handle the signal, or SIG_DFL, or SIG_IGN. This function will be invoked passing three parameters. The first is of type 'int' that contains the signal type for which this function is being invoked. The second is of type 'pointer to siginfo_t' where the siginfo_t contain additional information about the source of the signal. The third is of type 'pointer to void' but will actually point to a ucontext_t containing the context information at the time of the signal interrupt.
Notes:
  1. The user must cast SIG_IGN or SIG_DFL to match the sa_sigaction definition. (indicating that the signal is to be ignored).
  2. Special behavior for XPG4.2: This member and sa_handler are mutually exclusive of each other. When the SA_SIGINFO flag is set in sa_flags then sa_sigaction is used. Otherwise, sa_handler is used.

When a signal handler installed by sigaction(), with the _SA_OLD_STYLE flag set off, catches a signal, the system calculates a new signal mask by taking the union of the current signal mask, the signals specified by sa_mask, and the signal that was just caught (if the SA_NODEFER flag is not set). This new mask stays in effect until the signal handler returns, or sigprocmask(), sigsuspend(), siglongjmp(), sighold(), sigpause(), or sigrelse() is called. When the signal handler ends, the original signal mask is restored.

After an action has been specified for a particular signal, using sigaction() or signal(), it remains installed until it is explicitly changed with another call to sigaction(), signal(), one of the exec functions, bsd_signal(), sigignore(), sigset(), or until the SA_RESETHAND flag causes it to be reset to SIG_DFL.

After an action has been specified for a particular signal, using sigaction() with the _SA_OLD_STYLE flag not set, it remains installed until it is explicitly changed with another call to sigaction(), signal(), or one of the exec functions.

After an action has been specified for a particular signal, using sigaction() with the _SA_OLD_STYLE flag set or using signal(), it remains installed until it is explicitly changed with another call to sigaction(), signal(), or one of the exec functions, or a signal catcher is driven, where it will be reset to SIG_DFL.

Successful setting of signal action to SIG_IGN for a signal that is pending causes the pending signal to be discarded, whether or not it is blocked. This provides the ability to discard signals that are found to be blocked and pending by sigpending().

Special behavior for XPG4.2:
  • If a process sets the action of the SIGCHLD signal to SIG_IGN, child processes of the calling process will not be transformed into 'zombie' processes when they terminate. If the calling process subsequently waits for its children, and the process has no unwaited for children that were transformed into 'zombie' processes, it will block until all of its children terminate. The wait(), waitid(), or waitpid() function will fail and set errno to ECHILD.
  • If the SA_SIGINFO flag is set, the signal-catching function specified by sa_sigaction is invoked as:

           void  function(int signo, siginfo_t *info, void *context);

    Where function is the specified signal-catching function, signo is the signal number of the signal being delivered, info points to an object of type siginfo_t associated with the signal being delivered, and context points to an object of type ucontext_t.

Considerations for asynchronous signal-catching functions: Some of the functions have been restricted to be serially reusable with respect to asynchronous signals. That is, the library will not allow an asynchronous signal to interrupt the execution of one of these functions until it has completed.

This restriction needs to be taken into consideration when a signal-catching function is invoked asynchronously because it causes the behavior of some of the library functions to become unpredictable.

Thus, when you are producing a strictly compliant POSIX C or X/Open application, only the following functions should be assumed to be reentrant with respect to asynchronous signals. Use only these functions in your signal-catching functions:
access() alarm() cfgetispeed()
cfgetospeed() cfsetispeed() cfsetospeed()
chdir() chmod() chown()
close() creat() dup()
dup2() execle() execve()
_exit() fcntl() fork()
fstat() getegid() geteuid()
getgid() getgroups() getpgrp()
getpid() getppid() getuid()
kill() link() lseek()
mkdir() mkfifo() open()
pathconf() pause() pipe()
pthread_cond_broadcast() pthread_cond_signal() pthread_mutex_trylock()
read() rename() rmdir()
setgid() setpgid() setsid()
setuid() sigaction() sigaddset()
sigdelset() sigemptyset() sigfillset()
sigismember() sigpending() sigprocmask()
sigsuspend() sleep() stat()
sysconf() tcdrain() tcflow()
tcflush() tcgetattr() tcgetpgrp()
tcsendbreak() tcsetattr() tcsetpgrp()
time() times() umask()
uname() unlink() utime()
wait() waitpid() write()
Special behavior for XPG4.2: Adds the following functions to the list of functions above that may be used in signal-catching functions in strictly compliant X/Open applications:
  • fpathconf()
  • raise()
  • signal()

The macro versions of getc() and putc() are not reentrant, even though the library versions of these functions are.

For nonportable POSIX applications, most of the library functions can be used in a signal-catching function. However, do not use the following functions:
  • getenv()
  • getgrent()
  • getgrgid()
  • getgrnam()
  • getpwent()
  • getpwnam()
  • getpwuid()
  • ttyname()
Special behavior for XPLINK-compiled C++: Restrictions concerning setjmp.h and ucontext.h:
  1. All XPLINK programs compiled with the V2R10 or later C compilers that are to run with Language Environment V2R10 or later libraries and use the jmp_buf, sigjmp_buf or ucontext_t types must not be compiled with C headers from Language Environment V2R9 or earlier.
  2. Non-XPLINK functions compiled with any level of Language Environment headers must not define jmp_buf, sigjmp_buf or ucontext_t data items and pass them to XPLINK functions that call getcontext(), longjmp(), _longjmp(), setjmp(), _setjmp(), setcontext(), sigsetjmp(), or swapcontext() with these passed-in data items.
  3. When __XPLINK__ is defined, the Language Environment V2R10 and later headers define a larger jmp_buf, sigjmp_buf or ucontext_t area that is required by setjmp(), getcontext(), and related functions when they are called from an XPLINK routine. If __XPLINK__ is not defined, the Language Environment V2R10 and later headers define a shorter jmp_buf, sigjmp_buf or ucontext_t area. The Language Environment headers before V2R10 also define the shorter version of these data areas. If an XPLINK function calls setjmp(), getcontext() or similar functions with a short jmp_buf, sigjmp_buf or ucontext_t area, a storage overlay or program check may occur when the C library tries to store past the end of the passed-in (too short) data area.
  4. The sigaction() function supersedes the signal() interface, and should be the preferred usage. In particular, sigaction() and signal() must not be used in the same process to control the same signal.

Usage notes

The use of the SIGTHSTOP and SIGTHCONT signal is not supported with this function.

Returned value

If successful, sigaction() returns 0.

If unsuccessful, no new signal handler is installed, sigaction() returns -1, and sets errno to one of the following values:
Error Code
Description
EINVAL
The value of sig is not a valid signal for one of the following reasons:
  • The sig is not recognized.
  • The process tried to ignore a signal that cannot be ignored.
  • The process tried to catch a signal that cannot be caught.

The default action for SIGCHILD and SIGIO is for the signal to be ignored. A sigaction() to set the action to SIG_IGN for SIGIO will result in an error, with errno equal to EINVAL.

Example

CELEBS13
⁄* CELEBS13

   The first part of this example determines whether the SIGCHLD
   signal is currently being ignored.
   With a NULL pointer for the new argument, the current signal
   handler action is not changed.

 *⁄
#define _POSIX_SOURCE
#define _XOPEN_SOURCE_EXTENDED 1
#include <stdio.h>
#include <signal.h>

void main(void) {
struct sigaction info;

if (sigaction(SIGCHLD,NULL,&info) != -1)
    if (info.sa_handler == SIG_IGN)
        printf("SIGCHLD being ignored.\n");
    else if (info.sa_handler == SIG_DFL)
            printf("SIGCHLD being defaulted.\n");
}
CELEBS14
⁄* CELEBS14

   This fragment initializes a sigaction structure to specify
   mysig as a signal handler and then sets the signal handler
   for SIGCHLD.
   Information on the previous signal handler for SIGCHLD is
   stored in info.

 *⁄
#define _XOPEN_SOURCE_EXTENDED 1
#include <signal.h>
#include <stdio.h>
void mysig(int a) { printf("In mysig\n"); }

void main(void) {
   struct sigaction info, newhandler;

   if (sigaction(SIGCHLD,NULL,&info) != -1)
       if (info.sa_handler == SIG_IGN)
           printf("SIGCHLD being ignored.\n");
       else if(info.sa_handler == SIG_DFL)
           printf("SIGCHLD being defaulted.\n");

   newhandler.sa_handler = &mysig;
   sigemptyset(&(newhandler.sa_mask));
   newhandler.sa_flags = 0;
   if (sigaction(SIGCHLD,&newhandler,&info) != -1)
       printf("New handler set.\n"); }

Related information