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

FreeBSD Manual Pages


home | help
sigaction(2)							  sigaction(2)

       sigaction - detailed signal management

       #include	<signal.h>

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

       The sigaction() function	allows the calling process to examine or spec-
       ify  the	 action	to be taken on delivery	of a specific signal. See sig-
       nal.h(3HEAD) for	an explanation of general signal concepts.

       The sig argument	specifies the signal and can be	assigned  any  of  the
       signals specified in signal.h(3HEAD) except  SIGKILL and	SIGSTOP.

       If  the	argument act is	not NULL, it points to a structure  specifying
       the new action to be taken when delivering sig. If the argument oact is
       not  NULL, it points to a structure where the action previously associ-
       ated with sig is	to be stored on	return from sigaction().

       The sigaction structure includes	the following members:

       void	 (*sa_handler)();
       void	 (*sa_sigaction)(int, siginfo_t	*, void	*);
       sigset_t	 sa_mask;
       int	 sa_flags;

       The storage occupied by sa_handler and sa_sigaction may overlap,	and  a
       standard-conforming  application	 (see  standards(5)) must not use both

       The sa_handler member identifies	the action to be associated  with  the
       specified signal, if the	 SA_SIGINFO flag (see below) is	cleared	in the
       sa_flags	field of the sigaction structure. It may take any of the  val-
       ues  specified  in  signal.h(3HEAD)  or that of a user specified	signal
       handler.	If the	SA_SIGINFO flag	is set	in  the	 sa_flags  field,  the
       sa_sigaction field specifies a signal-catching function.

       The  sa_mask  member specifies a	set of signals to be blocked while the
       signal handler is active. On entry to the signal	handler, that  set  of
       signals	is  added to the set of	signals	already	being blocked when the
       signal is delivered. In addition, the signal that caused	the handler to
       be  executed will also be blocked, unless the  SA_NODEFER flag has been
       specified. SIGSTOP and  SIGKILL cannot be blocked (the system  silently
       enforces	this restriction).

       The  sa_flags member specifies a	set of flags used to modify the	deliv-
       ery of the signal. It is	formed by a logical OR of any of the following

       SA_ONSTACK      If set and the signal is	caught,	and if the thread that
		       is chosen to processes a	delivered signal has an	alter-
		       nate signal stack declared with sigaltstack(2), then it
		       will process the	signal on that stack.  Otherwise,  the
		       signal is delivered on the thread's normal stack.

       SA_RESETHAND    If set and the signal is	caught,	the disposition	of the
		       signal is reset to SIG_DFL and the signal will  not  be
		       blocked	on  entry  to the signal handler (SIGILL, SIG-
		       TRAP, and SIGPWR	cannot be   automatically  reset  when
		       delivered;  the	system silently	enforces this restric-

       SA_NODEFER      If set and the signal is	caught,	the signal will	not be
		       automatically  blocked  by the kernel while it is being

       SA_RESTART      If set and the signal is	 caught,  functions  that  are
		       interrupted  by	the execution of this signal's handler
		       are  transparently  restarted  by  the  system,	namely
		       fcntl(2),  ioctl(2),  wait(3C), waitid(2), and the fol-
		       lowing  functions  on  slow  devices  like   terminals:
		       getmsg()	 and  getpmsg()	(see getmsg(2));  putmsg() and
		       putpmsg() (see putmsg(2)); pread(), read(), and readv()
		       (see  read(2));	pwrite(),  write(),  and writev() (see
		       write(2));  recv(),  recvfrom(),	 and  recvmsg()	  (see
		       recv(3SOCKET));	and  send(),  sendto(),	 and sendmsg()
		       (see send(3SOCKET). Otherwise, the function returns  an
		       EINTR error.

       SA_SIGINFO      If  cleared  and	the signal is caught, sig is passed as
		       the only	argument to the	signal-catching	 function.  If
		       set and the signal is caught,  two additional arguments
		       are passed to the  signal-catching  function.   If  the
		       second  argument	 is  not equal to NULL,	it points to a
		       siginfo_t structure containing the reason why the  sig-
		       nal  was	 generated  (see  siginfo.h(3HEAD)); the third
		       argument	points to a  ucontext_t	 structure  containing
		       the  receiving  process's  context  when	the signal was
		       delivered (see ucontext.h(3HEAD)).

       SA_NOCLDWAIT    If set and sig equals  SIGCHLD,	the  system  will  not
		       create  zombie  processes  when children	of the calling
		       process	exit.  If  the	calling	 process  subsequently
		       issues  a  wait(3C), it blocks until all	of the calling
		       process's child processes terminate, and	 then  returns
		       -1 with errno set to ECHILD.

       SA_NOCLDSTOP    If set and sig equals SIGCHLD, SIGCHLD will not be sent
		       to the calling process when its child processes stop or

       Upon  successful	 completion, 0 is returned. Otherwise, -1 is returned,
       errno is	set to indicate	the  error,  and  no  new  signal  handler  is

       The sigaction() function	will fail if:

       EINVAL	       The  value  of  the  sig	argument is not	a valid	signal
		       number or is equal to  SIGKILL or SIGSTOP. In addition,
		       if  in a	multithreaded process, it is equal to SIGWAIT-

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Standard			   |
       |MT-Level		     |Async-Signal-Safe		   |

       kill(1),	intro(2), exit(2),  fcntl(2),  getmsg(2),  ioctl(2),  kill(2),
       pause(2),    putmsg(2),	  read(2),   sigaltstack(2),   sigprocmask(2),
       sigsend(2),   sigsuspend(2),   waitid(2),   write(2),	recv(3SOCKET),
       send(3SOCKET),  siginfo.h(3HEAD),  signal(3C),  signal.h(3HEAD),	sigse-
       tops(3C), ucontext.h(3HEAD), wait(3C), attributes(5), standards(5)

       The handler routine can be declared:

       void handler (int sig, siginfo_t	*sip, ucontext_t *ucp);

       The sig argument	is the signal number. The sip argument	is  a  pointer
       (to  space on the stack)	to a siginfo_t structure, which	provides addi-
       tional detail about the delivery	of the signal. The ucp argument	 is  a
       pointer	(again	to  space  on  the  stack)  to	a ucontext_t structure
       (defined	in <sys/ucontext.h>) which contains the	 context  from	before
       the  signal.   It is not	recommended that ucp be	used by	the handler to
       restore the context from	before the signal delivery.

				  23 Mar 2005			  sigaction(2)


Want to link to this manual page? Use this URL:

home | help