sigaction() — Examine or change a signal action

• 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".

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.

             struct sigaction {
                   void       (*sa_handler)(int);
                   sigset_t   sa_mask;
                   int        sa_flags;
                   void       (*sa_sigaction)(int, siginfo_t *, void *);
             };

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, see Handling error conditions, exceptions, 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, 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.

• 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 functionis 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.

• fpathconf()
• raise()
• signal()

• getenv()
• getgrent()
• getgrgid()
• getgrnam()
• getpwent()
• getpwnam()
• getpwuid()
• ttyname()

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.

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.

/* 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

   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"); }