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

FreeBSD Manual Pages


home | help
signal.h(3HEAD)						       signal.h(3HEAD)

       signal.h, signal	- base signals

       #include	<signal.h>

       A  signal is an asynchronous notification of an event. A	signal is said
       to be generated for (or sent to)	a process when	the  event  associated
       with that signal	first occurs. Examples of such events include hardware
       faults, timer expiration	and terminal activity, as well as the  invoca-
       tion  of	 the  kill(2) or sigsend(2) functions.	In some	circumstances,
       the same	event generates	signals	for multiple processes.	A process  may
       request	a  detailed  notification  of the source of the	signal and the
       reason why it was generated. See	siginfo.h(3HEAD).

       Signals can be generated	synchronously or  asynchronously.  Events  di-
       rectly caused by	the execution of code by a thread, such	as a reference
       to an unmapped, protected, or bad memory	can generate SIGSEGV  or  SIG-
       BUS;  a floating	point exception	can generate SIGFPE; and the execution
       of an illegal instruction can generate SIGILL. Such events are referred
       to  as  traps;  signals generated by traps are said to be synchronously
       generated.  Synchronously generated signals are initiated by a specific
       thread and are delivered	to and handled by that thread.

       Signals	may  also  be  generated  by  calling  kill(),	sigqueue(), or
       sigsend(). Events such as keyboard interrupts generate signals, such as
       SIGINT,	which are sent to the target process. Such events are referred
       to as interrupts; signals generated by interrupts are said to be	 asyn-
       chronously generated. Asynchronously generated signals are not directed
       to a particular thread but are handled  by  an  arbitrary  thread  that
       meets either of the following conditions:

	 o  The	 thread	 is blocked in a call to sigwait(2) whose argument in-
	    cludes the type of signal generated.

	 o  The	thread has a signal mask that does not	include	 the  type  of
	    signal  generated. See pthread_sigmask(3C).	Each process can spec-
	    ify	a system action	to be taken in response	to each	signal sent to
	    it,	 called	 the  signal's disposition. All	threads	in the process
	    share the disposition. The set of  system  signal  actions	for  a
	    process  is	initialized from that of its parent. Once an action is
	    installed for a specific signal, it	usually	remains	installed  un-
	    til	 another  disposition is explicitly requested by a call	to ei-
	    ther  sigaction(), signal()	or  sigset(), or until the process ex-
	    ecs(). See sigaction(2) and	 signal(3C). When a process execs, all
	    signals whose disposition has been set to catch the	signal will be
	    set	to SIG_DFL. Alternatively, a process may request that the sys-
	    tem	automatically reset the	disposition of a  signal  to   SIG_DFL
	    after it has been caught. See sigaction(2) and signal(3C).

       A  signal is said to be delivered to a process when a thread within the
       process takes the appropriate action for	 the disposition of  the  sig-
       nal.  Delivery  of  a  signal can be blocked. There are two methods for
       handling	delivery of a signal in	a multithreaded	application. The first
       method  specifies  a signal handler function to execute when the	signal
       is received by the process. See sigaction(2). The  second  method  uses
       sigwait(2)  to create a thread to handle	the receipt of the signal. The
       sigaction() function can	be  used  for  both  synchronously  and	 asyn-
       chronously generated signals. The sigwait() function will work only for
       asynchronously generated	signals, as  synchronously  generated  signals
       are sent	to the thread that caused the event. The sigwait() function is
       the recommended for use with a multithreaded application.

       Each thread has a signal	mask  that defines the	set  of	 signals  cur-
       rently  blocked from delivery to	it. The	signal mask of the main	thread
       is inherited from the signal mask of the	thread that created it in  the
       parent  process.	The selection of the thread within the process that is
       to take the appropriate action for the signal is	based on the method of
       signal  generation and the signal masks of the threads in the receiving
       process.	Signals	that are generated by action of	 a  particular	thread
       such  as	 hardware  faults  are delivered to the	thread that caused the
       signal. See pthread_sigmask(3C) or  sigprocmask(2).  See	 alarm(2)  for
       current	semantics of delivery of SIGALRM. Signals that are directed to
       a  particular  thread   are  delivered  to  the	targeted  thread.  See
       pthread_kill(3C). If the	selected thread	has blocked the	signal,	it re-
       mains pending on	the thread until it is unblocked.  For all other types
       of  signal  generation  (for example, kill(2), sigsend(2), terminal ac-
       tivity, and other  external  events  not	 ascribable  to	 a  particular
       thread) one of the threads that does not	have the signal	blocked	is se-
       lected to process the signal. If	all the	 threads  within  the  process
       block  the  signal, it remains pending on the process until a thread in
       the process unblocks it.	If the action associated with a	signal is  set
       to  ignore the signal then both currently pending and subsequently gen-
       erated signals of this type are discarded immediately for this process.

       The determination of which action is taken in response to a signal   is
       made  at	 the  time  the	 signal	 is  delivered	to a thread within the
       process,	allowing for any changes since the time	of generation.	  This
       determination is	independent of the means by which the signal was orig-
       inally generated.

       The signals currently defined by	<signal.h> are as follows:

       Name		Value	Default	   Event
       SIGHUP		1	Exit	   Hangup (see termio(7I))
       SIGINT		2	Exit	   Interrupt (see termio(7I))
       SIGQUIT		3	Core	   Quit	(see termio(7I))
       SIGILL		4	Core	   Illegal Instruction
       SIGTRAP		5	Core	   Trace or Breakpoint Trap
       SIGABRT		6	Core	   Abort
       SIGEMT		7	Core	   Emulation Trap
       SIGFPE		8	Core	   Arithmetic Exception
       SIGKILL		9	Exit	   Killed
       SIGBUS		10	Core	   Bus Error
       SIGSEGV		11	Core	   Segmentation	Fault
       SIGSYS		12	Core	   Bad System Call
       SIGPIPE		13	Exit	   Broken Pipe
       SIGALRM		14	Exit	   Alarm Clock
       SIGTERM		15	Exit	   Terminated
       SIGUSR1		16	Exit	   User	Signal 1
       SIGUSR2		17	Exit	   User	Signal 2
       SIGCHLD		18	Ignore	   Child Status	Changed
       SIGPWR		19	Ignore	   Power Fail or Restart
       SIGWINCH		20	Ignore	   Window Size Change
       SIGURG		21	Ignore	   Urgent Socket Condition
       SIGPOLL		22	Exit	   Pollable Event (see streamio(7I))
       SIGSTOP		23	Stop	   Stopped (signal)
       SIGTSTP		24	Stop	   Stopped (user) (see termio(7I))
       SIGCONT		25	Ignore	   Continued
       SIGTTIN		26	Stop	   Stopped (tty	input) (see termio(7I))
       SIGTTOU		27	Stop	   Stopped (tty	output)	(see termio(7I))
       SIGVTALRM	28	Exit	   Virtual Timer Expired

       SIGPROF		29	Exit	   Profiling Timer Expired
       SIGXCPU		30	Core	   CPU time limit  exceeded  (see  getr-
       SIGXFSZ		31	Core	   File	 size  limit exceeded (see getr-
       SIGWAITING	32	Ignore	   Reserved
       SIGLWP		33	Ignore	   Reserved
       SIGFREEZE	34	Ignore	   Check point Freeze
       SIGTHAW		35	Ignore	   Check point Thaw
       SIGCANCEL	36	Ignore	   Reserved for	threading support
       SIGLOST		37	Exit	   Resource lost (for  example,	 record-
					   lock	lost)
       SIGXRES		38	Ignore	   Resource    control	 exceeded   (see
       SIGJVM1		39	Ignore	   Reserved for	Java Virtual Machine 1
       SIGJVM2		40	Ignore	   Reserved for	Java Virtual Machine 2
       SIGRTMIN		*	Exit	   First real time signal
       (SIGRTMIN+1)	*	Exit	   Second real time signal
       (SIGRTMAX-1)	*	Exit	   Second-to-last real time signal
       SIGRTMAX		*	Exit	   Last	real time signal

       The symbols SIGRTMIN through SIGRTMAX are evaluated dynamically to per-
       mit future configurability.

       Applications should not use any of the signals marked "reserved"	in the
       above table for any purpose, to avoid interfering with their use	by the

       A  process  using  a signal(3C),	sigset(3C) or sigaction(2) system call
       can specify one of three	dispositions for a signal:  take  the  default
       action for the signal, ignore the signal, or catch the signal.

   Default Action: SIG_DFL
       A disposition of	 SIG_DFL specifies the default action. The default ac-
       tion for	each signal is listed in the table above and is	selected  from
       the following:

       Exit	When it	gets the signal, the receiving process is to be	termi-
		nated with all the consequences	outlined in exit(2).

       Core	When it	gets the signal, the receiving process is to be	termi-
		nated  with all	the consequences outlined in exit(2). In addi-
		tion, a	``core image'' of the process is  constructed  in  the
		current	working	directory.

       Stop	When  it  gets	the  signal, the receiving process is to stop.
		When a process is stopped, all the threads within the  process
		also stop executing.

       Ignore	When  it  gets	the signal, the	receiving process is to	ignore
		it. This is identical to setting the disposition to SIG_IGN.

   Ignore Signal: SIG_IGN
       A disposition of	SIG_IGN	specifies that the signal is  to  be  ignored.
       Setting	a signal action	to SIG_IGN for a signal	that is	pending	causes
       the pending signal to be	discarded, whether or not it is	 blocked.  Any
       queued  values  pending	are  also discarded, and the resources used to
       queue them are released and made	available to queue other signals.

   Catch Signal: function address
       A disposition that is a function	address	specifies that,	when  it  gets
       the  signal,  the thread	within the process that	is selected to process
       the signal will execute the signal handler at  the  specified  address.
       Normally,  the  signal  handler is passed the signal number as its only
       argument.  If the disposition was set with the  sigaction(2)  function,
       however,	additional arguments can be requested. When the	signal handler
       returns,	the receiving process resumes execution	at the	point  it  was
       interrupted,  unless the	signal handler makes other arrangements. If an
       invalid function	address	is specified, results are undefined.

       If the disposition has been set with the	sigset() or  sigaction(),  the
       signal is automatically blocked in the thread while it is executing the
       signal catcher. If a longjmp() is used to  leave	 the  signal  catcher,
       then  the  signal  must	be  explicitly	unblocked  by  the  user.  See
       setjmp(3C), signal(3C) and sigprocmask(2).

       If execution of the signal handler interrupts a blocked function	 call,
       the  handler  is	executed and the interrupted function call returns  -1
       to the calling process with errno set to	EINTR. If the SA_RESTART  flag
       is   set,   however,  certain  function	calls  will  be	 transparently

       Some signal-generating functions, such as high resolution timer expira-
       tion,  asynchronous  I/O	completion, inter-process message arrival, and
       the sigqueue(3RT) function, support the specification of	an application
       defined	value, either explicitly as a parameter	to the function, or in
       a sigevent structure parameter. The sigevent structure  is  defined  by
       <signal.h> and contains at least	the following members:

       Member		    Member
       Type		    Name		  Description
       int		    sigev_notify	  Notification type
       int		    sigev_signo		  Signal number
       union sigval	    sigev_value		  Signal value

       The  sigval  union  is  defined by <signal.h> and contains at least the
       following members:

       Member		Member
       Type		Name		Description
       int		sival_int	Integer	signal value
       void *		sival_ptr	Pointer	signal value

       The  sigev_notify member	specifies the notification  mechanism  to  use
       when  an	 asynchronous event occurs. The	sigev_notify member may	be de-
       fined with the following	values:

       SIGEV_NONE      No asynchronous	notification  is  delivered  when  the
		       event of	interest occurs.

       SIGEV_SIGNAL    A queued	signal,	with its value application-defined, is
		       generated when the event	of interest occurs.

       SIGEV_PORT      An asynchronous notification is delivered to  an	 event
		       port  when  the event of	interest occurs. The sival_ptr
		       member  points  to  a  port_notify_t   structure	  (see
		       port_associate(3C)).  The event port identifier as well
		       as  an  application-defined  cookie  are	 part  of  the
		       port_notify_t structure.

       Your implementation may define additional notification mechanisms.

       The sigev_signo member specifies	the signal to be generated.

       The  sigev_value	 member	references the application defined value to be
       passed to the signal-catching function at the time of the signal	deliv-
       ery as the si_value member of the siginfo_t structure.

       The  sival_int  member is used when the application defined value is of
       type int, and the sival_ptr member is used when the application defined
       value is	a pointer.

       When  a	signal	is generated by	sigqueue(3RT) or any signal-generating
       function	which supports the specification  of  an  application  defined
       value, the signal is marked pending and,	if the	SA_SIGINFO flag	is set
       for that	signal,	the signal is queued to	the process along with the ap-
       plication  specified  signal  value. Multiple occurrences of signals so
       generated are queued in FIFO order. If the  SA_SIGINFO flag is not  set
       for  that signal, later occurrences of that signal's generation,	when a
       signal is already queued, are silently discarded.

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

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Standard			   |

       lockd(1M),  intro(2),  alarm(2),	  exit(2),   fcntl(2),	 getrlimit(2),
       ioctl(2),  kill(2), pause(2), setrctl(2), sigaction(2), sigaltstack(2),
       sigprocmask(2),	sigsend(2),  sigsuspend(2),   sigwait(2),   port_asso-
       ciate(3C),  pthread_create(3C),	pthread_kill(3C), pthread_sigmask(3C),
       setjmp(3C), siginfo.h(3HEAD), signal(3C), sigqueue(3RT),	sigsetops(3C),
       thr_create(3C),	thr_kill(3C),  thr_sigsetmask(3C),  ucontext.h(3HEAD),
       wait(3C), attributes(5),	standards(5)

       The dispositions	of the SIGKILL and SIGSTOP signals cannot  be  altered
       from their default values. The system generates an error	if this	is at-

       The SIGKILL, SIGSTOP, and SIGCANCEL signals cannot be blocked. The sys-
       tem silently enforces this restriction.

       The  SIGCANCEL  signal cannot be	directed to an individual thread using
       pthread_kill(3C), but it	can  be	 sent  to  a  process  using  kill(2),
       sigsend(2), or sigqueue(3RT).

       Whenever	 a  process  receives  a SIGSTOP, SIGTSTP, SIGTTIN, or SIGTTOU
       signal, regardless of its disposition, any pending SIGCONT  signal  are

       Whenever	 a process receives a SIGCONT signal, regardless of its	dispo-
       sition, any pending SIGSTOP, SIGTSTP, SIGTTIN, and SIGTTOU  signals  is
       discarded. In addition, if the process was stopped, it is continued.

       SIGPOLL	is  issued  when  a file descriptor corresponding to a STREAMS
       file has	a "selectable" event pending. See intro(2).   A	 process  must
       specifically  request that this signal be sent using the	I_SETSIG ioctl
       call. Otherwise,	the process will never receive SIGPOLL.

       If the disposition of the SIGCHLD signal	has been set  with  signal  or
       sigset, or with sigaction and the SA_NOCLDSTOP flag has been specified,
       it will only be sent to the calling process  when  its  children	 exit;
       otherwise, it will also be sent when the	calling	process's children are
       stopped or continued due	to job control.

       The name	SIGCLD is also defined in this header and identifies the  same
       signal  as  SIGCHLD. SIGCLD is provided for backward compatibility, new
       applications should use	SIGCHLD.

       The disposition of signals that are inherited as	SIG_IGN	should not  be

       Signals which are generated synchronously should	not be masked. If such
       a signal	is blocked and delivered, the receiving	process	is killed.

				  20 Oct 2003		       signal.h(3HEAD)


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

home | help