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

FreeBSD Manual Pages


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

       sigvector - software signal facilities

       The system defines a set	of signals that	can be delivered to a process.
       The set of signals is defined in	signal(5), along with the meaning  and
       side  effects  of each signal.  This manual entry, along	with those for
       sigblock(2), sigsetmask(2), sigpause(3C), and sigspace(2),  defines  an
       alternate  mechanism for	handling these signals that ensures the	deliv-
       ery of signals and the integrity	of signal  handling  procedures.   The
       facilities  described  here  should  not	be used	in the same program as

       With the	interface, signal delivery resembles the occurrence of a hard-
       ware interrupt: the signal is blocked from further occurrence, the cur-
       rent process context is saved, and a new	one is built.  A  process  can
       specify a handler function to be	invoked	when a signal is delivered, or
       specify that a signal should be blocked or ignored.  A process can also
       specify that a default action should be taken by	the system when	a sig-
       nal occurs.  It is possible to ensure a minimum amount of  stack	 space
       for processing signals using (see sigspace(2)).

       All  signals  have the same priority.  Signal routines execute with the
       signal that causes their	invocation to be blocked, although other  sig-
       nals  can  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 It	can be
       changed with a or call, or when a signal	is delivered to	the process.

       A signal	mask is	represented as a with one bit representing each	signal
       being  blocked.	 The  following	 macro defined in is used to convert a
       signal number to	its corresponding bit in the mask:

       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, it is delivered to the process.	When a	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  in-
       voked.	The call to the	handler	is arranged so that if the signal han-
       dling routine returns normally, the process resumes  execution  in  the
       same context as before the signal's delivery.  If the process wishes to
       resume in a different context, 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 or call  is
       made).	This mask is formed by taking the current signal mask, comput-
       ing the bit-wise	inclusive OR with the value of (see  below)  from  the
       most  recent  call  to  for the signal to be delivered, and, unless the
       flag is set (see	below),	setting	the bit	corresponding  to  the	signal
       being  delivered.  When the user's signal handler returns normally, the
       original	mask is	restored.

       assigns a handler for the signal	specified by sig.  vec	and  ovec  are
       pointers	to sigvec structures that include the following	elements:

	      vec  is non-zero,	it specifies a handler routine (sv_handler), a
	      mask (sv_mask) that the system should use	 when  delivering  the
	      specified	 signal, and a set of flags (sv_flags) that modify the
	      delivery of the signal.  If ovec is non-zero, the	previous  han-
	      dling  information  for  the signal is returned to the user.  If
	      vec is zero, signal handling is unchanged.  Thus,	the  call  can
	      be used to enquire about the current handling of a given signal.
	      If vec and ovec point to the same	structure, the value of	vec is
	      read prior to being overwritten.

       The  sv_flags  field can	be used	to modify the receipt of signals.  The
       following flag bits are defined:

	      Use the		       allocated space.
	      Use the Berkeley signal semantics.
	      Use the semantics	of     signal(2).

       If is set, the system uses or permits the use of	the space reserved for
       signal processing in the	system call.

       If  is  set, the	signal is given	the Berkeley semantics.	 The following
       signal is affected by this flag:

	      In addition to being sent	when a child process dies,
			     the signal	is also	sent when any  child's	status
			     changes from running to stopped.  This would nor-
			     mally be used by a	program	such as	 (see  csh(1))
			     when  maintaining	process	 groups	under Berkeley
			     job control.

       If is set, the signal handler is	installed with the same	semantics as a
       handler installed with signal(2).  This affects signal mask set-up dur-
       ing the signal handler (see above) and whether the handler is reset af-
       ter a signal is caught (see below).

       If is not set, once a signal handler is installed, it remains installed
       until another call  is  made  or	 an  system  call  is  performed  (see
       exec(2)).  If is	set and	the signal is not one of those marked "not re-
       set when	caught"	under signal(5), the default action is reinstated when
       the  signal  is caught, prior to	entering the signal-catching function.
       The "not	reset when caught" distinction	is  not	 significant  when  is
       called and is not set.

       The default action for a	signal can be reinstated by setting sv_handler
       to this default usually results in  termination	of  the	 process.   If
       sv_handler  is  the signal is usually subsequently ignored, and pending
       instances of the	signal are discarded.  The exact meaning  of  and  for
       each signal is discussed	in signal(5).

       Certain	system	calls can be interrupted by a signal; all other	system
       calls complete before the signal	is  serviced.	The  scp  pointer  de-
       scribed	in  signal(5)  is never	null if	is supported.  scp points to a
       machine-dependent sigcontext structure.	All  implementations  of  this
       structure include the fields:


       The value for the sc_syscall field indicates that the signal is not in-
       terrupting a system call; any other value indicates which  system  call
       it is interrupting.

       If  a  signal that is being caught occurs during	a system call that can
       be interrupted, the signal handler is immediately invoked.  If the sig-
       nal handler exits normally, the value of	the sc_syscall_action field is
       inspected; if the value is the system call is aborted  and  the	inter-
       rupted  program continues past the call.	 The result of the interrupted
       call is -1 and is set to	EINTR.	If the value of	the  sc_syscall_action
       field is	the call is restarted.	A call is restarted if,	in the case of
       a or system call	(see read(2) or	write(2)), it had transferred no data.
       If  some	data had been transferred, the operation is considered to have
       completed with a	partial	transfer, and the sc_syscall  value  is	 Other
       values are undefined and	reserved for future use.

       Exiting	the handler abnormally (such as	with --	see setjmp(3C))	aborts
       the call, leaving the user responsible for the context of further  exe-
       cution.	 The value of scp-_sc_syscall_action is	ignored	when the value
       of scp-_sc_syscall is scp-_sc_syscall_action is always  initialized  to
       before invocation of a signal handler.  When an system call that	can be
       interrupted is interrupted by multiple signals, if any  signal  handler
       returns	a  value  of  in scp-_sc_syscall_action, all subsequent	signal
       handlers	are passed a value of in scp-_sc_syscall.

       Note that calls to or on	fast devices (such as disks) cannot be	inter-
       rupted,	but  I/O  to  a	 slow device (such as a	printer) can be	inter-
       rupted.	Other system calls, such as those used	for  networking,  also
       can  be interrupted on some implementations.  In	these cases additional
       values can be specified for scp-_sc_syscall.  Programs that look	at the
       values  of scp-_sc_syscall always should	compare	them to	these symbolic
       constants; the numerical	values represented by  these  constants	 might
       vary  among  implementations.  System calls that	can be interrupted and
       their corresponding values for scp-_sc_syscall are listed below:
		      Call		    | sc_syscall value
		      read (slow devices)   | SYS_READ
		      readv (slow devices)  | SYS_READV
		      write (slow devices)  | SYS_WRITE
		      writev (slow devices) | SYS_WRITEV
		      open (slow devices)   | SYS_OPEN
		      ioctl (slow requests) | SYS_IOCTL
		      close (slow requests) | SYS_CLOSE
		      wait		    | SYS_WAIT
		      select		    | SYS_SELECT
		      pause		    | SYS_PAUSE
		      sigpause		    | SYS_SIGPAUSE
		      semop		    | SYS_SEMOP
		      msgsnd		    | SYS_MSGSND
		      msgrcv		    | SYS_MSGRCV

       These system calls are not defined if the preprocessor macro is defined
       when  is	 included.   This is because the specifies a different meaning
       for the symbol (see limits(5)).

       After a or system call, the child  inherits  all	 signals,  the	signal
       mask, and the reserved signal stack space.

       exec(2)	resets	all caught signals to the default action; ignored sig-
       nals remain ignored, the	signal mask remains  unchanged,	 and  the  re-
       served signal stack space is released.

       The  mask  specified in vec is not allowed to block signals that	cannot
       be ignored, as defined in signal(5).  This is enforced silently by  the

       If  is called to	catch in a process that	currently has terminated (zom-
       bie) children, a	signal is delivered to	the  calling  process  immedi-
       ately, or as soon as is unblocked if it is currently blocked.  Thus, in
       a process that spawns multiple children and catches it is sometimes ad-
       visable	to  reinstall  the  handler  for after each invocation in case
       there are multiple zombies present.  This is true even though the  han-
       dling  of the signal is not reset by the	system,	as with	signal(2), be-
       cause deaths of multiple	processes while	is blocked in the handler  re-
       sult  in	delivery of only a single signal.  Note	that the function must
       reinstall itself	after it has called or Otherwise the presence  of  the
       child  that  caused the original	signal always causes another signal to
       be delivered.

       Upon successful completion, returns 0; otherwise,  it  returns  -1  and
       sets to indicate	the reason.

       fails  and  no  new signal handler is installed if any of the following
       conditions are encountered:

	      [EFAULT]		  Either vec or	ovec points to memory that  is
				  not  a  valid	 part  of  the process address
				  space.  Reliable detection of	this error  is
				  implementation dependent.

	      [EINVAL]		  sig is not a valid signal number.

	      [EINVAL]		  An  attempt  was  made to ignore or supply a
				  handler for a	signal that cannot  be	caught
				  or ignored; see signal(5).

       Restarting a select(2) call can sometimes cause unexpected results.  If
       the call	has a timeout specified, the timeout  is  restarted  with  the
       call,  ignoring	any  portion that had elapsed prior to interruption by
       the signal.  Normally this simply extends the  timeout  and  is	not  a
       problem.	  However,  if	a  handler repeatedly catches signals, and the
       timeout specified to is longer than the	time  between  those  signals,
       restarting the call effectively renders the timeout infinite.

       should  not  be used in conjunction with	the facilities described under

   Obsolescent Interfaces
       is to be	obsoleted at a future date.

   Threads Considerations
       The signal disposition (such as catch/ignore/default) established by is
       shared  by  all	threads	in the process.	 Each thread maintains its own
       blocked signal  mask.   For  more  information  regarding  signals  and
       threads,	refer to signal(5).

       was developed by	HP and the University of California, Berkeley.

       kill(1),	 kill(2),  ptrace(2),  sigblock(2),  signal(2),	 sigpause(3C),
       sigsetmask(2), sigspace(2), setjmp(3C), signal(5), termio(7).

				TO BE OBSOLETED			  sigvector(2)


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

home | help