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

FreeBSD Manual Pages


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

       sigvec -	software signal	facilities

       #include	<signal.h>

       int sigvec(sig, vec, ovec)
       int sig;
       struct sigvec *vec, *ovec;

       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 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 blocked
       or ignored.  A process may also specify that a default action is	to  be
       taken  by  the  system when a signal occurs.  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.

       All  signals  have the same priority.  Signal routines execute with the
       signal that caused their	invocation 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	0).  It	may be changed
       with a sigblock(2) or sigsetmask(2) call, or when a signal is delivered
       to the process.

       A  process may also specify a set of flags for a	signal that affect the
       delivery	of that	signal.

       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.   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  invoked.  The call to the handler is	arranged so that if the	signal
       handling	routine	returns	normally the process will resume execution  in
       the  context  from before the signal's delivery.	 If the	process	wishes
       to resume 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  sigblock()
       or  sigsetmask()	call is	made).	This mask is formed by taking the cur-
       rent signal mask, adding	the signal to be delivered, and	ORing  in  the
       signal mask associated with the handler to be invoked.

       The  action  to be taken	when the signal	is delivered is	specified by a
       sigvec structure, defined in <signal.h> as:

	      struct sigvec {
		     void (*sv_handler)();	   /* signal handler */
		     int sv_mask;		   /* signal mask to apply */
		     int sv_flags;		   /* see signal options */

       The following bits may be set in	sv_flags:

	      #define SV_ONSTACK       0x0001	 /* take signal	on signal stack	*/
	      #define SV_INTERRUPT     0x0002	 /* do not restart system on signal return */
	      #define SV_RESETHAND     0x0004	 /* reset signal handler to SIG_DFL on signal */

       If the SV_ONSTACK bit is	set in the flags for that signal,  the	system
       will  deliver  the  signal to the process on the	signal stack specified
       with sigstack(2), rather	than delivering	 the  signal  on  the  current

       If vec is not a NULL pointer, sigvec() assigns the handler specified by
       sv_handler, the mask specified by sv_mask, and the flags	 specified  by
       sv_flags	 to  the specified signal.  If vec is a	NULL pointer, sigvec()
       does not	change the handler, mask, or flags for the specified signal.

       The mask	specified in vec is not	allowed	to block SIGKILL  or  SIGSTOP.
       The system enforces this	restriction silently.

       If  ovec	 is not	a NULL pointer,	the handler, mask, and flags in	effect
       for the signal before the call to sigvec() are returned to the user.  A
       call  to	 sigvec()  with	vec a NULL pointer and ovec not	a NULL pointer
       can be used to determine	the handling information currently  in	effect
       for a signal without changing that information.

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

	      SIGHUP	1    hangup
	      SIGINT	2    interrupt
	      SIGQUIT	3*   quit
	      SIGILL	4*   illegal instruction
	      SIGTRAP	5*   trace trap
	      SIGABRT	6*   abort (generated by abort(3) routine)
	      SIGEMT	7*   emulator trap
	      SIGFPE	8*   arithmetic	exception
	      SIGKILL	9    kill (cannot be caught, blocked, or ignored)
	      SIGBUS	10*  bus error
	      SIGSEGV	11*  segmentation violation
	      SIGSYS	12*  bad argument to system call
	      SIGPIPE	13   write on a	pipe or	other socket with no one to read it
	      SIGALRM	14   alarm clock
	      SIGTERM	15   software termination signal
	      SIGURG	16@  urgent condition present on socket
	      SIGSTOP	17+  stop (cannot be caught, blocked, or ignored)
	      SIGTSTP	18+  stop signal generated from	keyboard
	      SIGCONT	19@  continue after stop
	      SIGCHLD	20@  child status has changed
	      SIGTTIN	21+  background	read attempted from control terminal
	      SIGTTOU	22+  background	write attempted	to control terminal
	      SIGIO	23@  I/O is possible on	a descriptor (see fcntl(2V))
	      SIGXCPU	24   cpu time limit exceeded (see getrlimit(2))
	      SIGXFSZ	25   file size limit exceeded (see getrlimit(2))
	      SIGVTALRM	26   virtual time alarm	(see getitimer(2))
	      SIGPROF	27   profiling timer alarm (see	getitimer(2))
	      SIGWINCH	28@  window changed (see termio(4) and win(4S))
	      SIGLOST	29*  resource lost (see	lockd(8C))
	      SIGUSR1	30   user-defined signal 1
	      SIGUSR2	31   user-defined signal 2

       The starred signals in the list above cause a core image	if not	caught
       or ignored.

       Once  a signal handler is installed, it remains installed until another
       sigvec()	call is	made, or an execve(2V) is performed, unless the	SV_RE-
       SETHAND	bit  is	 set  in the flags for that signal.  In	that case, the
       value of	the handler for	the caught signal is set to SIG_DFL before en-
       tering  the  signal-catching  function,	unless the signal is SIGILL or
       SIGTRAP.	 Also, if this bit is set, the bit for that signal in the sig-
       nal  mask  will not be set; unless the signal mask associated with that
       signal blocks that signal, further occurrences of that signal will  not
       be blocked.  The	SV_RESETHAND flag is not available in 4.2BSD, hence it
       should not be used if backward compatibility is needed.

       The default action for a	signal may be reinstated by setting  the  sig-
       nal's  handler  to SIG_DFL; this	default	is termination except for sig-
       nals marked with	@ or +.	 Signals marked	with @ are  discarded  if  the
       action is SIG_DFL; signals marked with +	cause the process to stop.  If
       the process is terminated, a ``core image'' will	be made	in the current
       working	directory  of  the  receiving process if the signal is one for
       which an	asterisk appears in the	above list and	the  following	condi-
       tions are met:

	      o	 The  effective	 user  ID (EUID) and the real user ID (UID) of
		 the receiving process are equal.

	      o	 The effective group ID	(EGID) and the real group ID (GID)  of
		 the receiving process are equal.

	      o	 An  ordinary file named core exists and is writable or	can be
		 created.  If the file must be created,	it will	have the  fol-
		 lowing	properties:

		 o  a  mode  of	 0666  modified	by the file creation mask (see

		 o  a file owner ID that is the	same as	the effective user  ID
		    of the receiving process.

		 o  a  file  group ID that is the same as the file group ID of
		    the	current	directory

       If the handler for that signal is SIG_IGN, the signal  is  subsequently
       ignored,	and pending instances of the signal are	discarded.

       Note: the signals SIGKILL and SIGSTOP cannot be ignored.

       If  a  caught  signal  occurs  during certain system calls, the call is
       restarted by default.  The call can be forced to	terminate  prematurely
       with an EINTR error return by setting the SV_INTERRUPT bit in the flags
       for that	signal.	 SV_INTERRUPT is not available	in  4.2BSD,  hence  it
       should  not  be used if backward	compatibility is needed.  The affected
       system calls are	read(2V) or write(2V) on a slow	device (such as	a ter-
       minal or	pipe or	other socket, but not a	file) and during a wait(2V).

       After  a	fork(2V), or vfork(2) the child	inherits all signals, the sig-
       nal mask, the signal stack, and the restart/interrupt and reset-signal-
       handler flags.

       The  execve(2V),	 call  resets all caught signals to default action and
       resets all signals to be	caught on the user stack.  Ignored signals re-
       main  ignored; the signal mask remains the same;	signals	that interrupt
       system calls continue to	do so.

       The following defines the codes for signals which produce them.	All of
       these symbols are defined in signal.h:

       Sun codes:
	 Illegal instructionSIGILLILL_INSTR_FAULT
	 Integer division by zeroSIGFPEFPE_INTDIV_TRAP
	 IEEE floating pt inexactSIGFPEFPE_FLTINEX_TRAP
	 IEEE floating pt division by zeroSIGFPEFPE_FLTDIV_TRAP
	 IEEE floating pt underflowSIGFPEFPE_FLTUND_TRAP
	 IEEE floating pt operand errorSIGFPEFPE_FLTOPERR_TRAP
	 IEEE floating pt overflowSIGFPEFPE_FLTOVF_FAULT
	 Hardware bus errorSIGBUSBUS_HWERR
	 Address alignment errorSIGBUSBUS_ALIGN
	 No mapping faultSIGSEGVSEGV_NOMAP
	 Protection faultSIGSEGVSEGV_PROT
	 Object	error numberSIGSEGVSEGV_ERRNO(code)
       SPARC codes:
	 Privileged instruction	violationSIGILLILL_PRIVINSTR_FAULT
	 Trap #n (1 <= n <= 127)SIGILLILL_TRAP_FAULT(n)
	 Tag overflowSIGEMTEMT_TAG
       MC680X0 codes:
	 Privilege violationSIGILLILL_PRIVVIO_FAULT
	 Coprocessor protocol errorSIGILLILL_INSTR_FAULT
	 Trap #n (1 <= n <= 14)SIGILLILL_TRAPn _FAULT
	 A-line	op codeSIGEMTEMT_EMU1010
	 F-line	op codeSIGEMTEMT_EMU1111
	 IEEE floating pt compare unorderedSIGFPEFPE_FLTBSUN_TRAP
	 IEEE floating pt signaling NaNSIGFPEFPE_FLTNAN_TRAP

       The addr	signal handler parameter is defined as follows:

	 SIGILLAnyaddress of faulted instruction
	 SIGEMTAnyaddress of faulted instruction
	 SIGFPEAnyaddress of faulted instruction
	 SIGBUSBUS_HWERRaddress	that caused fault
	 SIGSEGVAnyaddress that	caused fault
	 SIGBUSBUS_ALIGNaddress	of faulted instruction
	 SIGBUSBUS_ALIGNaddress	that caused fault

       The  accuracy  of  addr is machine dependent.  For example, certain ma-
       chines may supply an address that is on the same	page  as  the  address
       that  caused  the  fault.  If an	appropriate addr cannot	be computed it
       will be set to SIG_NOADDR.

       sigvec()	returns:

       0      on success.

       -1     on failure and sets errno	to indicate the	error.

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

       EFAULT	      Either  vec  or ovec is not a NULL pointer and points to
		      memory that is not a valid part of the  process  address

       EINVAL	      Sig is not a valid signal	number.

		      An  attempt  was	made to	ignore or supply a handler for

       execve(2V), fcntl(2V), fork(2V),	getitimer(2), getrlimit(2),  ioctl(2),
       kill(2V),   ptrace(2),  read(2V),  sigblock(2),	sigpause(2V),  sigset-
       mask(2),	 sigstack(2),  umask(2V),   vfork(2),	wait(2V),   write(2V),
       setjmp(3V), signal(3V), streamio(4), termio(4), win(4S),	lockd(8C)

       SIGPOLL is a synonym for	SIGIO.	A SIGIO	will be	issued when a file de-
       scriptor	corresponding to a STREAMS (see	 intro(2))  file  has  a  "se-
       lectable"  event	 pending.   Unless  that  descriptor has been put into
       asynchronous mode (see fcntl (2V), a process must specifically  request
       that  this  signal  be  sent  using  the	 I_SETSIG  ioctl(2)  call (see
       streamio(4)).  Otherwise, the process will never	receive	SIGPOLL.

       The handler routine can be declared:

	      void handler(sig,	code, scp, addr)
	      int sig, code;
	      struct sigcontext	*scp;
	      char *addr;

       Here sig	is the signal number; code is a	parameter of  certain  signals
       that  provides  additional  detail;  scp	is a pointer to	the sigcontext
       structure (defined in signal.h),	used to	restore	the context  from  be-
       fore the	signal;	and addr is additional address information.

       Programs	that must be portable to UNIX systems other than 4.2BSD	should
       use the signal(3V), interface instead.

				21 January 1990			     SIGVEC(2)


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

home | help