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

FreeBSD Manual Pages

  
 
  

home | help
sigaction(2)		      System Calls Manual		  sigaction(2)

NAME
       sigaction - examine and change signal action

SYNOPSIS
DESCRIPTION
       The  function  allows the calling process to examine and/or specify the
       action to be associated with a specific signal. The argument sig	speci-
       fies the	signal;	acceptable values are defined in

       The  structure  sigaction, used to describe an  action to  be taken, is
       defined in the header to	include	at least the following members:

       Member Type			 Member	Name	Description

       void(*)(int)			 sa_handler	SIG_DFL, SIG_IGN  or
							pointer	 to  a func-
							tion.

       sigset_t				 sa_mask	Additional  set	  of
							signals	    to	  be
							blocked	during	exe-
							cution	 of  signal-
							catching function.

       int				 sa_flags	Special	flags to af-
							fect   behavior	  of
							signal.

       void(*)(int, siginfo_t*,void *)	 sa_sigaction	signal-catching
							function.

       If  the	argument  act  is not a	null pointer, it points	to a structure
       specifying the action to	be associated with the specified  signal.   If
       the  argument oact is not a null	pointer, the action previously associ-
       ated with the signal is stored in the location pointed to by the	 argu-
       ment  oact.   If	the argument act is a null pointer, signal handling is
       unchanged; thus,	the call can be	used to	enquire	about the current han-
       dling of	a given	 signal. The sa_handler	field of the structure identi-
       fies the	action to be associated	with  the  specified  signal.  If  the
       sa_handler  field  specifies  a	signal-catching	 function, the sa_mask
       field identifies	a set of signals that will be added  to	 the  process'
       signal  mask  before  the  signal-catching function is invoked. The and
       signals will not	be added to the	signal mask using this mechanism; this
       restriction  will be enforced by	the system without causing an error to
       be indicated.

       The sa_flags field can be used to modify	the behavior of	the  specified
       signal.	 The  following	 flags,	 defined  in  the header can be	set in
       sa_flags:

	      Do not generate	     when children stop.

	      If set and an alternate signal stack has been declared with
				     or	the signal will	be  delivered  to  the
				     calling  process  on  that	stack.	Other-
				     wise, the signal will be delivered	on the
				     current stack.

	      If set, the disposition of the signal will be reset to
				     and  the flag will	be cleared on entry to
				     the signal	handler	(Note: and  cannot  be
				     automatically  reset  when	delivered; the
				     system silently  enforces	this  restric-
				     tion).  Otherwise,	the disposition	of the
				     signal will not be	modified on  entry  to
				     the signal	handler.  In addition, if this
				     flag is set, behaves as if	the flag  were
				     also set.

	      This flag	affects	the behaviour of interruptible functions; that
				     is,  those	 specified to fail with	set to
				     If	set, and a function specified  as  in-
				     terruptible  is  interrupted by this sig-
				     nal, the function will restart  and  will
				     not fail with unless otherwise specified.
				     If	the flag  is  not  set,	 interruptible
				     functions interrupted by this signal will
				     fail with set to

	      If cleared and the signal	is caught, the signal-catching
				     function will be entered as:

				     where is the only argument	to the	signal
				     catching  function.   In  this  case  the
				     sa_handler	member must  be	 used  to  de-
				     scribe  the  signal catching function and
				     the  application  must  not  modify   the
				     sa_sigaction member.

				     If	 is  set and the signal	is caught, the
				     signal-catching function will be  entered
				     as:

				     where two additional arguments are	passed
				     to	the signal catching function.  If  the
				     second argument is	not a null pointer, it
				     will point	to an object of	type siginfo_t
				     explaining	 the reason why	the signal was
				     generated;	the third argument can be cast
				     to	 a  pointer to an object of type ucon-
				     text_t to refer to	the context of the re-
				     ceiving process or	thread that was	inter-
				     rupted when the signal was	delivered.  In
				     this case the sa_sigaction	member must be
				     used  to  describe	 the  signal  catching
				     function  and  the	 application  must not
				     modify the	sa_handler member.

				     The si_signo member of info contains  the
				     system-generated signal number.

				     The si_errno member may contain implemen-
				     tation-dependent additional error	infor-
				     mation; if	non-zero, it contains an error
				     number  identifying  the  condition  that
				     caused the	signal to be generated.

				     The  si_code member contains a code iden-
				     tifying the cause of the signal.  If  the
				     value of si_code is less than or equal to
				     0,	then the signal	 was  generated	 by  a
				     process  and  si_pid  and	si_uid respec-
				     tively indicate the process  ID  and  the
				     real user ID of the sender. The values of
				     si_pid and	si_uid are otherwise  meaning-
				     less.

				     If	 is set	in sa_flags, subsequent	occur-
				     rences of sig generated by	or as a	result
				     of	 any  signal-generating	 function that
				     supports the specification	of an applica-
				     tion-defined  value - when	sig is already
				     pending - will be queued  in  FIFO	 order
				     until   delivered,	 and  the  application
				     specified value will  be  passed  to  the
				     signal-catching  function as the si_value
				     member of info (See Realtime Signals  Ex-
				     tension).	 If  is	 not  set in sa_flags,
				     then the disposition of subsequent	occur-
				     rences  of	sig when it is already pending
				     is	implementation-defined.

	      If set, and	     sig equals	child processes	of the calling
				     process will not be transformed into zom-
				     bie processes when	they terminate.	If the
				     calling  process  subsequently  waits for
				     its children, and the process has no  un-
				     waited for	children that were transformed
				     into zombie processes, it will block  un-
				     til  all  of  its children	terminate, and
				     and will fail and set errno to Otherwise,
				     terminating   child   processes  will  be
				     transformed into zombie processes,	unless
				     is	set to

	      If set and	     sig  is  caught, sig will not be added to
				     the process' signal mask on entry to  the
				     signal  handler  unless it	is included in
				     sa_mask.  Otherwise, sig will  always  be
				     added  to the process' signal mask	on en-
				     try to the	signal handler.

       If sig is and the flag is not set in sa_flags, and  the	implementation
       supports	 the  signal,  then a signal will be generated for the calling
       process whenever	any of its child processes stop. If  sig  is  and  the
       flag  is	 set  in sa_flags, then	the implementation will	not generate a
       signal in this way.

       When a signal is	caught by a signal-catching function  installed	 by  a
       new  signal  mask  is  calculated and installed for the duration	of the
       signal-catching function	(or until a call to either or is  made).  This
       mask  is	 formed	by taking the union of the current signal mask and the
       value of	the sa_mask for	the signal being delivered unless or  is  set,
       and  then including the signal being delivered.	If and when the	user's
       signal handler returns normally,	the original signal mask is restored.

       Once an action is installed for a specific signal, it remains installed
       until  another action is	explicitly requested (by another call to until
       the flag	causes resetting of the	handler, or  until  one	 of  the  exec
       functions is called.

       If  the	previous  action for sig had been established by the values of
       the fields returned in the structure pointed to by  oact	 are  unspeci-
       fied,  and  in  particular oact-_sa_handler is not necessarily the same
       value passed to However,	if a pointer to	the same structure or  a  copy
       thereof	is  passed  to a subsequent call to via	the act	argument, han-
       dling of	the signal will	be as if the original call to were repeated.

       If fails, no new	signal handler is installed.

       It is unspecified whether an attempt to set the	action	for  a	signal
       that cannot be caught or	ignored	to is ignored or causes	an error to be
       returned	with set to

       A signal	is said	to be for (or sent to) a process when the  event  that
       causes  the signal first	occurs.	Examples of such events	include	detec-
       tion of hardware	faults,	timer expiration  and  terminal	 activity,  as
       well  as	 the  invocation  of and In some circumstances,	the same event
       generates signals for multiple processes.

       Each process has	an action to be	taken in response to each  signal  de-
       fined by	the system (see	Signal Actions). A signal is said to be	deliv-
       ered to a process when the appropriate action for the process and  sig-
       nal is taken.

       During  the  time  between the generation of a signal and its delivery,
       the signal is said to be	Ordinarily, this interval cannot  be  detected
       by  an  application.   However,	a  signal  can	be  from delivery to a
       process.	If the action associated with a	 blocked  signal  is  anything
       other  than  to	ignore the signal, and if that signal is generated for
       the process, the	signal will remain pending  until  either  it  is  un-
       blocked	or  the	action associated with it is set to ignore the signal.
       If the action associated	with a blocked signal is to ignore the	signal
       and  if	that  signal  is  generated for	the process, it	is unspecified
       whether the signal is discarded immediately upon	generation or  remains
       pending.

       Each  process  has  a  signal mask that defines the set of signals cur-
       rently blocked from delivery to it.  The	signal mask for	a  process  is
       initialized  from that of its parent. The and functions control the ma-
       nipulation of the signal	mask.

       The determination of which action is taken in response to a  signal  is
       made  at	 the  time  the	 signal	is delivered, allowing for any changes
       since the time of generation.  This determination is independent	of the
       means  by  which	 the signal was	originally generated.  If a subsequent
       occurrence of a pending signal is generated, it	is  implementation-de-
       pendent	as to whether the signal is delivered more than	once.  The or-
       der in which multiple, simultaneously pending signals are delivered  to
       a process is unspecified.

       When  any stop signal ( is generated for	a process, any pending signals
       for that	process	will be	discarded.  Conversely,	when is	generated  for
       a process, all pending stop signals for that process will be discarded.
       When is generated for a process that is stopped,	the  process  will  be
       continued,  even	if the signal is blocked or ignored. If	is blocked and
       not ignored, it will remain pending until it is either unblocked	 or  a
       stop signal is generated	for the	process.

       Some signal-generating functions, such as high-resolution timer expira-
       tion, asynchronous I/O completion, interprocess	message	 arrival,  and
       the  function,  support	the  specification  of	an application-defined
       value, either explicitly	as a parameter to the function or in a	struc-
       ture parameter (see

   Realtime Signals Extension
       When  a	signal	is generated by	or any signal-generating function that
       supports	the specification of an	application-defined value, and if  the
       flag  is	 set for that signal, the signal will be queued	to the process
       along with the application-specified  signal  value.   Multiple	occur-
       rences of signals so generated are queued in FIFO order.	 When multiple
       unblocked signals, all in the range to are pending, the	implementation
       delivers	 the  pending  unblocked  signal with the lowest signal	number
       within that range.  The selection order between realtime	 and  nonreal-
       time  signals,  or between multiple pending nonrealtime signals,	is un-
       specified.  Signals generated by	or other events	that cause signals  to
       occur,  such as detection of hardware faults, timer expiration, or ter-
       minal activity, and for	which  the  implementation  does  not  support
       queueing,  will	have  no effect	on signals already queued for the same
       signal number.

       If, when	a pending signal is delivered, there are additional signals to
       be queued to that signal	number,	the signal will	remain pending.	Other-
       wise, the pending indication will be reset.

       An implementation will document any condition  not  specified  by  this
       document	under which the	implementation generates signals.

   Signal Actions
       There  are  three types of action that can be associated	with a signal:
       or a pointer to a function. Initially, all signals will be  set	to  or
       prior  to  entry	 of  the routine (see the functions). The actions pre-
       scribed by these	values are as follows:

       - signal-specific default action

	      o	 The default actions for the signals defined in	this  document
		 are specified under

	      o	 If  the  default action is to stop the	process, the execution
		 of that process is  temporarily  suspended.  When  a  process
		 stops,	a signal will be generated for its parent process, un-
		 less the parent process has set the flag.  While a process is
		 stopped,  any additional signals that are sent	to the process
		 will not be delivered until the process is continued,	except
		 which	always	terminates  the	 receiving process.  A process
		 that is a member of an	orphaned process group will not	be al-
		 lowed	to stop	in response to the or signals.	In cases where
		 delivery of one of these signals would	stop such  a  process,
		 the signal will be discarded.

	      o	 Setting  a signal action to for a signal that is pending, and
		 whose default action is to ignore the	signal	(for  example,
		 will cause the	pending	signal to be discarded,	whether	or not
		 it is blocked.	 Any queued values pending will	be  discarded,
		 and  the system resources used	to queue them will be released
		 and made available to queue other signals.

       - ignore	signal

	      o	 Delivery of the signal	will have no effect  on	 the  process.
		 The behaviour of a process is undefined after it ignores a or
		 signal	that was not generated by

	      o	 The system will not allow the action for the signals or to be
		 set to

	      o	 Setting  a signal action to for a signal that is pending will
		 cause the pending signal to be	discarded, whether or  not  it
		 is blocked.  Any queued values	pending	will be	discarded, and
		 the system resources used to queue them will be released  and
		 made available	to queue other signals.

	      o	 If  a process sets the	action for the signal to the behaviour
		 is unspecified, except	as specified below.

		 If the	action for the signal is set to	child processes	of the
		 calling  processes  will  not be transformed into zombie pro-
		 cesses	when they terminate. If	 the  calling  process	subse-
		 quently  waits	 for  its children, and	the process has	no un-
		 waited	for children that were transformed  into  zombie  pro-
		 cesses,  it  will  block until	all of its children terminate,
		 and and will fail and set to

       Pointer to a function - catch signal

	      o	 On delivery of	the signal, the	receiving process is  to  exe-
		 cute  the  signal-catching function at	the specified address.
		 After returning from the signal-catching  function,  the  re-
		 ceiving  process  will	resume execution at the	point at which
		 it was	interrupted.

	      o	 If is cleared,	the signal-catching function will  be  entered
		 as:

		 where	is the specified signal-catching function and signo is
		 the signal number of the signal being delivered.

	      o	 If is set, the	signal-catching	function will be entered as:

		 where is the specified	signal-catching	function, is the  sig-
		 nal  number  of the signal being delivered, siginfo points to
		 an object of type siginfo_t associated	with the signal	 being
		 delivered, and	points to a ucontext_t.

	      o	 The behaviour of a process is undefined after it returns nor-
		 mally from a signal- catching function	for a or  signal  that
		 was not generated by or

	      o	 The system will not allow a process to	catch the signals and

	      o	 If  a	process	establishes a signal-catching function for the
		 signal	while it has a terminated child	process	for  which  it
		 has  not waited, it is	unspecified whether a signal is	gener-
		 ated to indicate that child process.

	      o	 When signal-catching  functions  are  invoked	asynchronously
		 with  process	execution,  the	behaviour of some of the func-
		 tions defined by this document	is  unspecified	 if  they  are
		 called	from a signal-catching function.

		 Refer	to the "Async Signal Safe" section of thread_safety(5)
		 which defines a set of	functions that are either reentrant or
		 not interruptible by signals.	Therefore applications may in-
		 voke them, without restriction,  from	signal-catching	 func-
		 tions.

		 All  functions	 not  mentioned	 under the "Async Signal Safe"
		 section of thread_safety(5) are considered to be unsafe  with
		 respect to signals. In	the presence of	signals, all functions
		 defined by this document will behave as defined  when	called
		 from  or  interrupted	by  a signal-catching function,	with a
		 single	exception: when	a signal interrupts an unsafe function
		 and  the  signal-catching  function calls an unsafe function,
		 the behaviour is undefined.

   Signal Effects on Other Functions
       Signals affect the behaviour of certain functions  (defined  under  the
       "Async  Signal  Safe"  section  of  thread_safety(5)) if	delivered to a
       process while it	is executing such a function. If  the  action  of  the
       signal  is to terminate the process, the	process	will be	terminated and
       the function will not return. If	the action of the signal  is  to  stop
       the  process, the process will stop until continued or terminated. Gen-
       eration of a signal for the process causes the process to be continued,
       and  the	 original  function will continue at the point the process was
       stopped.	If the action of the signal is	to  invoke  a  signal-catching
       function,  the  signal-catching	function will be invoked; in this case
       the original function is	said to	be by the signal. If the signal-catch-
       ing  function  executes a return	statement, the behaviour of the	inter-
       rupted function will be as described individually  for  that  function.
       Signals that are	ignored	will not affect	the behaviour of any function;
       signals that are	blocked	will not affect	the behaviour of any  function
       until they are unblocked	and then delivered.

RETURN VALUE
       Upon successful completion, returns 0. Otherwise	-1 is returned,	is set
       to indicate the error and no new	signal-catching	function will  be  in-
       stalled.

ERRORS
       The function will fail if:

	      [EINVAL]		       The  sig	argument is not	a valid	signal
				       number or an attempt is made to catch a
				       signal  that cannot be caught or	ignore
				       a signal	that cannot be ignored.

       The function may	fail if:

	      [EINVAL]		       An attempt was made to set  the	action
				       to  for	a signal that cannot be	caught
				       or ignored (or both).

APPLICATION USAGE
       The function supersedes the interface, and should be  used  in  prefer-
       ence.   In  particular,	and  should not	be used	in the same process to
       control the same	signal.	 The behaviour of reentrant functions, as  de-
       fined  in the description, is as	specified by this document, regardless
       of invocation from a signal-catching function. This  is	the  only  in-
       tended meaning of the statement that reentrant functions	may be used in
       signal-catching	functions  without  restrictions.   Applications  must
       still  consider	all  effects  of such functions	on such	things as data
       structures, files and process state. In particular, application writers
       need to consider	the restrictions on interactions when interrupting and
       interactions among multiple handles for a  file	descriptor.  The  fact
       that  any specific function is listed as	reentrant does not necessarily
       mean that invocation of that function from a  signal-catching  function
       is recommended.

       In  order  to  prevent  errors  arising from interrupting non-reentrant
       function	calls, applications should protect calls  to  these  functions
       either  by  blocking the	appropriate signals or through the use of some
       programmatic semaphore. This document does not address the more general
       problem of synchronizing	access to shared data structures. Note in par-
       ticular that even the "safe" functions may modify the  global  variable
       the  signal-catching  function  may want	to save	and restore its	value.
       Naturally, the same principles apply to the reentrancy  of  application
       routines	 and  asynchronous  data  access. Note that and	are not	in the
       list of reentrant functions. This is because the	code  executing	 after
       and can call any	unsafe functions with the same danger as calling those
       unsafe functions	directly from the signal  handler.  Applications  that
       use  and	from within signal handlers require rigorous protection	in or-
       der to be portable. Many	of the other functions that are	excluded  from
       the list	are traditionally implemented using either or functions	or the
       standard	I/O library, both of which traditionally use  data  structures
       in  a non-reentrant manner.  Because any	combination of different func-
       tions using a common data structure can cause reentrancy	problems, this
       document	 does  not  define  the	 behaviour when	any unsafe function is
       called in a signal handler that interrupts an unsafe function.

       If the signal occurs other than as the result of	calling	or the	behav-
       iour is undefined if the	signal handler calls any function in the stan-
       dard library other than one of the functions listed in the table	 above
       or  refers to any object	with static storage duration other than	by as-
       signing a value to a static storage duration variable of	type  volatile
       sig_atomic_t.  Furthermore, if such a call fails, the value of is inde-
       terminate.

       Usually,	the signal is executed on the stack that was in	effect	before
       the  signal  was	 delivered. An alternate stack may be specified	to re-
       ceive a subset of the signals being caught.

       When the	signal handler returns,	the receiving process will resume exe-
       cution  at the point it was interrupted unless the signal handler makes
       other arrangements. If or is used to leave the signal handler, then the
       signal mask must	be explicitly restored by the process.

       POSIX.4-1993  defines  the third	argument of a signal handling function
       when is set as a	void * instead of a ucontext_t *, but without  requir-
       ing  type  checking.  New applications should explicitly	cast the third
       argument	of the signal handling function	to uncontext_t *.

       The BSD optional	four argument signal handling  function	 is  not  sup-
       ported by this specification.  The BSD declaration would	be

       where  sig is the signal	number,	code is	additional information on cer-
       tain signals, scp is a pointer to the structure,	and addr is additional
       address information.  Much the same information is available in the ob-
       jects pointed to	by the second argument of the signal handler specified
       when is set.

   Threads Considerations
       The  signal disposition,	catch/ignore/default, established by is	shared
       by all threads in the process.

       If the signal disposition for sig is set	to or is set to	 and  the  de-
       fault  action  for  sig	is  to ignore the signal, any instances	of sig
       pending on the process or any of	the threads will  be  discarded.   The
       signals	are  discarded	regardless of whether the signal is blocked by
       any of the threads.

       For more	information regarding signals and threads, see signal(5).

FUTURE DIRECTIONS
       The function is marked as an extension in the list  of  safe  functions
       because it is not included in the corresponding list in the ISO POSIX-1
       standard, but it	is expected to be added	in a future revision  of  that
       standard.

SEE ALSO
       kill(2),	  setjmp(3C),	sigaltstack(2),	  signal(2),   sigprocmask(2),
       sigqueue(2), sigsetops(3C), sigsuspend(2),  thread_safety(5),  wait(2),
       waitid(2), <signal.h>, <ucontext.h>.

CHANGE HISTORY
       First released in Issue 3.

       Entry included for alignment with the POSIX.1-1988 standard.

Issue 4
       The  following  changes	are  incorporated  for	alignment with the ISO
       POSIX-1 standard:

	      o	 The type of argument act is changed from to

	      o	 A statement is	added to the  DESCRIPTION  section  indicating
		 that  the  consequence	of attempting to set for a signal that
		 cannot	be caught or ignored is	unspecified.  The  error,  de-
		 scribing one possible reaction	to this	condition, is added to
		 the ERRORS section.

       Other changes are incorporated as follows:

	      o	 The and functions are added to	the list of functions that are
		 either	 reentrant  or	not  interruptible by signals; is also
		 added to this list and	marked as  an  extension;  is  removed
		 from  the list, as this function is withdrawn from the	inter-
		 face definition.  It is no longer specified whether and  also
		 fall into this	category of functions.

	      o	 The  APPLICATION USAGE	section	is added. Most of this text is
		 moved from the	DESCRIPTION SECTION in Issue 3.

	      o	 The FUTURE DIRECTIONS section is added.

Issue 4, Version 2
       The following changes are incorporated for X/OPEN UNIX conformance:

	      o	 The DESCRIPTION describes the member of the sigaction	struc-
		 ture that is the signal-catching function.

	      o	 The  DESCRIPTION describes the	and settings of	sa_flags.  The
		 text describes	the implications of the	use of for the	number
		 of arguments passed to	the signal-catching function. The text
		 also describes	the effects of the and flags on	 the  delivery
		 of a signal and on the	permanence of an installed action.

	      o	 The  DESCRIPTION  specifies  the effect if the	action for the
		 signal	is set to

	      o	 In the	DESCRIPTION, additional	text describes the  effect  if
		 the  action  is  a pointer to a function. A new bullet	covers
		 the case where	is set.	 is given as an	additional signal  for
		 which	the  behaviour	of  a process is undefined following a
		 normal	return from the	signal-catching	function.

	      o	 The APPLICATION USAGE section is updated to describe  use  of
		 an  alternate signal stack; resumption	of the process receiv-
		 ing the signal; coding	for compatibility  with	 POSIX.4-1993;
		 and implementation of signal-handling functions in BSD.

sigaction(2)		      System Calls Manual		  sigaction(2)

				  HP-UX	EXTENSIONS

DESCRIPTION
       More  details  on the semantics of specific signals can be found	in the
       signal(5) manual	entry.

	      Upon receipt of the signal
			     sig, the default action (specified	on  signal(5))
			     is	performed.

ERRORS
	      [EFAULT]	     act  or  oact  points to an invalid address.  The
			     reliable detection	of this	error  is  implementa-
			     tion dependent.

AUTHOR
       was derived from	the IEEE POSIX 1003.1-1988 Standard.

SEE ALSO
       ptrace(2), sigpending(2), sigspace(2), sigsetops(3C).

STANDARDS CONFORMANCE
								  sigaction(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | APPLICATION USAGE | FUTURE DIRECTIONS | SEE ALSO | CHANGE HISTORY | Issue 4 | Issue 4, Version 2 | DESCRIPTION | ERRORS | AUTHOR | SEE ALSO | STANDARDS CONFORMANCE

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

home | help