Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SIGACTION(2)		  FreeBSD System Calls Manual		  SIGACTION(2)

NAME
     sigaction -- software signal facilities

SYNOPSIS
     #include <signal.h>

     struct sigaction {
	     union {	     /*	signal handler */
		     void    (*__sa_handler)(int);
		     void    (*__sa_sigaction)(int, siginfo_t *, void *);
	     } __sigaction_u;
	     sigset_t sa_mask;		/* signal mask to apply	*/
	     int      sa_flags;		/* see signal options below */
     };

     #define sa_handler	     __sigaction_u.__sa_handler
     #define sa_sigaction    __sigaction_u.__sa_sigaction

     int
     sigaction(int sig,	const struct sigaction *act, struct sigaction *oact);

DESCRIPTION
     The system	defines	a set of signals that may be delivered to a process.
     Signal delivery resembles the occurrence of a hardware interrupt: the
     signal is normally	blocked	from further occurrence, the current process
     context is	saved, and a new one is	built.	A process may specify a
     handler to	which a	signal is delivered, or	specify	that a signal is to be
     ignored.  A process may also specify that a default action	is to be taken
     by	the system when	a signal occurs.  A signal may also be blocked,	in
     which case	its delivery is	postponed until	it is unblocked.  The action
     to	be taken on delivery is	determined at the time of delivery.  Normally,
     signal handlers execute on	the current stack of the process.  This	may be
     changed, on a per-handler basis, so that signals are taken	on a special
     signal stack.

     Signal routines normally execute with the signal that caused their	invo-
     cation blocked, but other signals may yet occur.  A global	signal mask
     defines the set of	signals	currently blocked from delivery	to a process.
     The signal	mask for a process is initialized from that of its parent
     (normally empty).	It may be changed with a sigprocmask(2)	call, or when
     a signal is delivered to the process.

     When a signal condition arises for	a process, the signal is added to a
     set of signals pending for	the process.  If the signal is not currently
     blocked by	the process then it is delivered to the	process.  Signals may
     be	delivered any time a process enters the	operating system (e.g.,	during
     a system call, page fault or trap,	or clock interrupt).  If multiple sig-
     nals are ready to be delivered at the same	time, any signals that could
     be	caused by traps	are delivered first.  Additional signals may be	pro-
     cessed at the same	time, with each	appearing to interrupt the handlers
     for the previous signals before their first instructions.	The set	of
     pending signals is	returned by the	sigpending(2) function.	 When a	caught
     signal is delivered, the current state of the process is saved, a new
     signal mask is calculated (as described below), and the signal handler is
     invoked.  The call	to the handler is arranged so that if the signal han-
     dling routine returns normally the	process	will resume execution in the
     context from before the signal's delivery.	 If the	process	wishes to re-
     sume in a different context, then it must arrange to restore the previous
     context itself.

     When a signal is delivered	to a process a new signal mask is installed
     for the duration of the process' signal handler (or until a
     sigprocmask(2) call is made).  This mask is formed	by taking the union of
     the current signal	mask set, the signal to	be delivered, and the signal
     mask sa_mask associated with the handler to be invoked, but always	ex-
     cluding SIGKILL and SIGSTOP.

     sigaction() assigns an action for a signal	specified by sig.  If act is
     non-zero, it specifies an action (SIG_DFL,	SIG_IGN, or a handler routine)
     and mask to be used when delivering the specified signal.	If oact	is
     non-zero, the previous handling information for the signal	is returned to
     the user.

     Once a signal handler is installed, it normally remains installed until
     another sigaction() call is made, or an execve(2) is performed.  The
     value of sa_handler (or, if the SA_SIGINFO	flag is	set, the value of
     sa_sigaction instead) indicates what action should	be performed when a
     signal arrives.  A	signal-specific	default	action may be reset by setting
     sa_handler	to SIG_DFL.  Alternately, if the SA_RESETHAND flag is set the
     default action will be reinstated when the	signal is first	posted.	 The
     defaults are process termination, possibly	with core dump;	no action;
     stopping the process; or continuing the process.  See the signal list be-
     low for each signal's default action.  If sa_handler is SIG_DFL, the de-
     fault action for the signal is to discard the signal, and if a signal is
     pending, the pending signal is discarded even if the signal is masked.
     If	sa_handler is set to SIG_IGN, current and pending instances of the
     signal are	ignored	and discarded.	If sig is SIGCHLD and sa_handler is
     set to SIG_IGN, the SA_NOCLDWAIT flag (described below) is	implied.

     The signal	mask sa_mask is	typically manipulated using the	sigaddset(3)
     family of functions.

     Options may be specified by setting sa_flags.  The	meaning	of the various
     bits is as	follows:

	   SA_NOCLDSTOP	   If this bit is set when installing a	catching func-
			   tion	for the	SIGCHLD	signal,	the SIGCHLD signal
			   will	be generated only when a child process exits,
			   not when a child process stops.

	   SA_NOCLDWAIT	   If this bit is set when calling sigaction() for the
			   SIGCHLD signal, the system will not create zombie
			   processes when children of the calling process
			   exit, though	existing zombies will remain.  If the
			   calling process subsequently	issues a waitpid(2)
			   (or equivalent) and there are no previously exist-
			   ing zombie child processes that match the
			   waitpid(2) criteria,	it blocks until	all of the
			   calling process's child processes that would	match
			   terminate, and then returns a value of -1 with
			   errno set to	ECHILD.

	   SA_ONSTACK	   If this bit is set, the system will deliver the
			   signal to the process on a signal stack, specified
			   with	sigaltstack(2).

	   SA_NODEFER	   If this bit is set, further occurrences of the de-
			   livered signal are not masked during	the execution
			   of the handler.

	   SA_RESETHAND	   If this bit is set, the handler is reset back to
			   SIG_DFL at the moment the signal is delivered.

	   SA_SIGINFO	   If this bit is set, the 2nd argument	of the handler
			   is set to be	a pointer to a siginfo_t structure as
			   described in	<sys/siginfo.h>.  It provides much
			   more	information about the causes and attributes of
			   the signal that is being delivered.

	   SA_RESTART	   If a	signal is caught during	the system calls
			   listed below, the call may be forced	to terminate
			   with	the error EINTR, the call may return with a
			   data	transfer shorter than requested, or the	call
			   may be restarted.  Restarting of pending calls is
			   requested by	setting	the SA_RESTART bit in
			   sa_flags.  The affected system calls	include
			   read(2), write(2), sendto(2), recvfrom(2),
			   sendmsg(2) and recvmsg(2) on	a communications chan-
			   nel or a slow device	(such as a terminal, but not a
			   regular file) and during a wait(2) or ioctl(2).
			   However, calls that have already committed are not
			   restarted, but instead return a partial success
			   (for	example, a short read count).

     After a fork(2) or	vfork(2), all signals, the signal mask,	the signal
     stack, and	the restart/interrupt flags are	inherited by the child.

     execve(2) reinstates the default action for SIGCHLD and all signals which
     were caught; all other signals remain ignored.  All signals are reset to
     be	caught on the user stack and the signal	mask remains the same; signals
     that restart pending system calls continue	to do so.

     The following is a	list of	all signals with names as in the include file
     <signal.h>:

     Name	   Default Action	Description
     SIGHUP	   terminate process	terminal line hangup
     SIGINT	   terminate process	interrupt program
     SIGQUIT	   create core image	quit program
     SIGILL	   create core image	illegal	instruction
     SIGTRAP	   create core image	trace trap
     SIGABRT	   create core image	abort(3) call (formerly	SIGIOT)
     SIGEMT	   create core image	emulate	instruction executed
     SIGFPE	   create core image	floating-point exception
     SIGKILL	   terminate process	kill program (cannot be	caught or
						       ignored)
     SIGBUS	   create core image	bus error
     SIGSEGV	   create core image	segmentation violation
     SIGSYS	   create core image	system call given invalid argument
     SIGPIPE	   terminate process	write on a pipe	with no	reader
     SIGALRM	   terminate process	real-time timer	expired
     SIGTERM	   terminate process	software termination signal
     SIGURG	   discard signal	urgent condition present on socket
     SIGSTOP	   stop	process		stop (cannot be	caught or ignored)
     SIGTSTP	   stop	process		stop signal generated from keyboard
     SIGCONT	   discard signal	continue after stop
     SIGCHLD	   discard signal	child status has changed
     SIGTTIN	   stop	process		background read	attempted from control
						       terminal
     SIGTTOU	   stop	process		background write attempted to control
						       terminal
     SIGIO	   discard signal	I/O is possible	on a descriptor	(see
						       fcntl(2))
     SIGXCPU	   terminate process	CPU time limit exceeded	(see
						       setrlimit(2))
     SIGXFSZ	   terminate process	file size limit	exceeded (see
						       setrlimit(2))
     SIGVTALRM	   terminate process	virtual	time alarm (see	setitimer(2))
     SIGPROF	   terminate process	profiling timer	alarm (see
						       setitimer(2))
     SIGWINCH	   discard signal	window size change
     SIGINFO	   discard signal	status request from keyboard
     SIGUSR1	   terminate process	user defined signal 1
     SIGUSR2	   terminate process	user defined signal 2
     SIGTHR	   discard signal	thread AST

RETURN VALUES
     Upon successful completion, the value 0 is	returned; otherwise the
     value -1 is returned and the global variable errno	is set to indicate the
     error.

EXAMPLES
     The handler routine can be	declared:

	   void
	   handler(int sig)

     If	the SA_SIGINFO option is enabled, the canonical	way to declare it is:

	   void
	   handler(int sig, siginfo_t *sip, void *ctx)

     Here sig is the signal number, into which the hardware faults and traps
     are mapped.  If the SA_SIGINFO option is set, sip is a pointer to a
     siginfo_t as described in <sys/siginfo.h>.	 If SA_SIGINFO is not set,
     this pointer will be NULL instead.	 The function specified	in
     sa_sigaction will be called instead of the	function specified by
     sa_handler	(note that in some implementations these are in	fact the
     same).  ctx may be	cast to	a pointer to ucontext_t	which can be used to
     restore the thread's context from before the signal.  On OpenBSD,
     ucontext_t	is an alias for	the sigcontext structure defined in
     <signal.h>.  The contents of this structure are machine-dependent.

ERRORS
     sigaction() will fail and no new signal handler will be installed if one
     of	the following occurs:

     [EFAULT]		Either act or oact points to memory that is not	a
			valid part of the process address space.

     [EINVAL]		sig is not a valid signal number.

     [EINVAL]		An attempt is made to ignore or	supply a handler for
			SIGKILL	or SIGSTOP.

SEE ALSO
     kill(1), kill(2), ptrace(2), sigaltstack(2), sigprocmask(2),
     sigsuspend(2), wait(2), setjmp(3),	sigaddset(3), sigblock(3),
     sigpause(3), sigvec(3), tty(4)

STANDARDS
     The sigaction() function conforms to IEEE Std 1003.1-2008 ("POSIX.1").

     The SA_ONSTACK flag and the SIGPROF, SIGSYS, SIGTRAP, SIGVTALRM, SIGXCPU,
     and SIGXFSZ signals conform to the	X/Open System Interfaces option	of
     that standard.  The standard marks	SIGPROF	as obsolescent.	 The signals
     SIGEMT, SIGINFO, SIGIO, and SIGWINCH are Berkeley extensions.  These sig-
     nals are available	on most	BSD-derived systems.  The SIGTHR signal	is
     specific to OpenBSD and is	part of	the implementation of thread cancella-
     tion; sigaction and other signal interfaces may reject attempts to	use or
     alter the handling	of SIGTHR.

     The following functions are either	reentrant or not interruptible by sig-
     nals and are async-signal-safe.  Therefore	applications may invoke	them,
     without restriction, from signal-catching functions:

     Standard Interfaces:

     _exit(), _Exit(), abort(),	accept(), access(), alarm(), bind(),
     cfgetispeed(), cfgetospeed(), cfsetispeed(), cfsetospeed(), chdir(),
     chmod(), chown(), clock_gettime(),	close(), connect(), creat(), dup(),
     dup2(), execl(), execle(),	execv(), execve(), faccessat(),	fchdir(),
     fchmod(), fchmodat(), fchown(), fchownat(), fcntl(), fdatasync(), fork(),
     fpathconf(), fstat(), fstatat(), fsync(), ftruncate(), futimens(),
     futimes(),	getegid(), geteuid(), getgid(),	getgroups(), getpeername(),
     getpgrp(),	getpid(), getppid(), getsockname(), getsockopt(), getuid(),
     kill(), link(), linkat(), listen(), lseek(), lstat(), mkdir(), mkdirat(),
     mkfifo(), mkfifoat(), mknod(), mknodat(), open(), openat(), pathconf(),
     pause(), pipe(), poll(), pselect(), pthread_sigmask(), raise(), read(),
     readlink(), readlinkat(), recv(), recvfrom(), recvmsg(), rename(),
     renameat(), rmdir(), select(), send(), sendmsg(), sendto(), setgid(),
     setpgid(),	setsid(), setsockopt(),	setuid(), shutdown(), sigaction(),
     sigaddset(), sigdelset(), sigemptyset(), sigfillset(), sigismember(),
     signal(), sigpause(), sigpending(), sigprocmask(),	sigsuspend(), sleep(),
     sockatmark(), socket(), socketpair(), stat(), strcat(), strcpy(),
     strncat(),	strncpy(), symlink(), symlinkat(), sysconf(), tcdrain(),
     tcflow(), tcflush(), tcgetattr(), tcgetpgrp(), tcsendbreak(),
     tcsetattr(), tcsetpgrp(), time(), times(),	umask(), uname(), unlink(),
     unlinkat(), utime(), utimensat(), utimes(), wait(), waitpid(), write(),
     and perhaps some others.

     Extension Interfaces:

     accept4(),	chflags(), chflagsat(),	dup3(),	fchflags(), getentropy(),
     getresgid(), getresuid(), pipe2(),	ppoll(), sendsyslog(), setresgid(),
     setresuid(), strlcat(), strlcpy(),	wait3(), wait4().

     In	addition, access and updates to	errno are guaranteed to	be safe.  Most
     functions not in the above	lists are considered to	be unsafe with respect
     to	signals.  That is to say, the behaviour	of such	functions when called
     from a signal handler is undefined.  In general though, signal handlers
     should do little more than	set a flag, ideally of type volatile
     sig_atomic_t; most	other actions are not safe.

     Additionally, it is advised that signal handlers guard against modifica-
     tion of the external symbol errno by the above functions, saving it at
     entry and restoring it on return, thus:

	   void
	   handler(int sig)
	   {
		   int save_errno = errno;

		   ...
		   errno = save_errno;
	   }

     The functions below are async-signal-safe in OpenBSD except when used
     with floating-point arguments or directives, but are probably unsafe on
     other systems:

	   dprintf()	 Safe.
	   vdprintf()	 Safe.
	   snprintf()	 Safe.
	   vsnprintf()	 Safe.
	   syslog_r()	 Safe if the syslog_data struct	is initialized as a
			 local variable.

FreeBSD	13.0		       February	27, 2018		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | ERRORS | SEE ALSO | STANDARDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sigaction&sektion=2&manpath=OpenBSD+6.9>

home | help