unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 signal(2)							   signal(2)




 NAME
      signal, sigset, sighold, sigrelse, sigignore, sigpause - signal
      management

 SYNOPSIS
      #include <&lt&lt&lt;signal.h>&gt&gt&gt;

      void (*signal(int sig, void (*func)(int)))(int);

      int sighold(int sig);

      int sigignore(int sig);

      int sigpause(int sig);

      int sigrelse(int sig);

      void (*sigset(int sig, void (*disp)(int)))(int);

 DESCRIPTION
      The signal() function chooses one of three ways in which receipt of
      the signal number sig is to be subsequently handled. If the value of
      func is SIG_DFL, default handling for that signal will occur.  If the
      value of func is SIG_IGN, the signal will be ignored. Otherwise, func
      must point to a function to be called when that signal occurs. Such a
      function is called a signal handler.

      When a signal occurs, if func points to a function, first the
      equivalent of a:

	   signal(sig, SIG_DFL);

      is executed or an implementation-dependent blocking of the signal is
      performed. (If the value of sig is SIGILL, whether the reset to
      SIG_DFL occurs is implementation-dependent.) Next the equivalent of:

	   (*func)(sig);

      is executed. The func function may terminate by executing a return
      statement or by calling abort(), exit(), or longjmp().  If func()
      executes a return statement and the value of sig was SIGFPE or any
      other implementation-dependent value corresponding to a computational
      exception, the behaviour is undefined.  Otherwise, the program will
      resume execution at the point it was interrupted.

      If the signal occurs other than as the result of calling abort(),
      kill() or raise(), the behaviour is undefined if the signal handler
      calls any function in the standard library other than one of the
      functions listed on the sigaction(2) page or refers to any object with
      static storage duration other than by assigning a value to a static
      storage duration variable of type volatile sig_atomic_t.	Furthermore,



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 signal(2)							   signal(2)




      if such a call fails, the value of errno is indeterminate.

      At program startup, the equivalent of:

	   signal(sig, SIG_IGN);

      is executed for some signals, and the equivalent of:

	   signal(sig, SIG_DFL);

      is executed for all other signals (see exec).

      The sigset(), sighold(), sigignore(), sigpause() and segrelse()
      functions provide simplified signal management.

      The sigset() function is used to modify signal dispositions.  The sig
      argument specifies the signal, which may be any signal except SIGKILL
      and SIGSTOP.  The disp argument specifies the signal's disposition,
      which may be SIG_DFL, SIG_IGN or the address of a signal handler. If
      sigset() is used, and disp is the address of a signal handler, the
      system will add sig to the calling process' signal mask before
      executing the signal handler; when the signal handler returns, the
      system will restore the calling process' signal mask to its state
      prior the delivery of the signal. In addition, if sigset() is used,
      and disp is equal to SIG_HOLD, sig will be added to the calling
      process' signal mask and sig's disposition will remain unchanged. If
      sigset() is used, and disp is not equal to SIG_HOLD, sig will be
      removed from the calling process' signal mask.

      The sighold() function adds sig to the calling process' signal mask.

      The sigrelse() function removes sig from the calling process' signal
      mask.

      The sigignore() function sets the disposition of sig to SIG_IGN.

      The sigpause() function removes sig from the calling process' signal
      mask and suspends the calling process until a signal is received.

      If the action for the SIGCHLD signal is set to SIG_IGN, child
      processes of the calling processes will not be transformed into zombie
      processes when they terminate. If the calling process subsequently
      waits for its children, and the process has no unwaited for children
      that were transformed into zombie processes, it will block until all
      of its children terminate, and wait(), wait3(), waitid() and waitpid()
      will fail and set errno to ECHILD.

 RETURN VALUE
      If the request can be honoured, signal() returns the value of func()
      for the most recent call to signal() for the specified signal sig.
      Otherwise, SIG_ERR is returned and a positive value is stored in



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 signal(2)							   signal(2)




      errno.

      Upon successful completion, sigset() returns SIG_HOLD if the signal
      had been blocked and the signal's previous disposition if it had not
      been blocked. Otherwise, SIG_ERR is returned and errno is set to
      indicate the error.

      For all other functions, upon successful completion, 0 is returned.
      Otherwise, -1 is returned and errno is set to indicate the error.

 ERRORS
      The signal() 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 signal() function may fail if:

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

      The sigset(), sighold(), sigrelse(), sigignore(), and sigpause()
      functions will fail if:

	   [EINVAL]	  The sig argument is an illegal signal number.

      The sigset(), and sigignore() functions will fail if:

	   [EINVAL]	  An attempt is made to catch a signal that cannot
			  be caught, or to ignore a signal that cannot be
			  ignored.

 APPLICATION USAGE
      The sigaction() function provides a more comprehensive and reliable
      mechanism for controlling signals; new applications should use
      sigaction() rather than signal().

      The sighold() function, in conjunction with sigrelse() or sigpause(),
      may be used to establish critical regions of code that require the
      delivery of a signal to be temporarily deferred.

      The sigsuspend() function should be used in preference to sigpause()
      for broader portability.

    Threads Considerations
      The signal disposition (such as catch/ignore/default) established by
      signal() is shared by all threads in the process.	 Blocked signal
      masks are maintained by each thread.



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 signal(2)							   signal(2)




      If signal() is used to set the signal disposition for sig to SIG_IGN
      or to SIG_DFL for a signal whose default action 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, refer to
      signal(5).

 SEE ALSO
      exec(2), pause(2), sigaction(2), waitid(2), <signal.h>.

 CHANGE HISTORY
      First released in Issue 1.

      Derived from Issue 1 of the SVID.

 Issue 4
      The following changes are incorporated for alignment with the ISO C
      standard:

	   -	     The function is no longer marked as an extension.

	   -	     The argument int is added to the definition of func()
		     in the SYNOPSIS section.

	   -	     In Issue 3, this interface cross-referred to
		     sigaction().  This issue provides a complete
		     description of the function as defined in ISO C
		     standard.

      Another change is incorporated as follows:

	   -	     The APPLICATION USAGE section is added.

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

	   -	     The sighold(), sigignore(), sigpause(), sigrelse(), and
		     sigset() functions are added to the SYNOPSIS.

	   -	     The DESCRIPTION is updated to describe semantics of the
		     above interfaces.

	   -	     Additional text is added to the RETURN VALUE section to
		     describe possible returns from the sigset() function
		     specifically, and all of the above functions in
		     general.

	   -	     The ERRORS section is restructured to describe possible
		     error returns from each of the above functions



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 signal(2)							   signal(2)




		     individually.

	   -	     The APPLICATION USAGE section is updated to describe
		     certain programming considerations associated with the
		     X/OPEN UNIX functions.

















































				    - 5 -	  Formatted:  August 2, 2006






 signal(2)							   signal(2)




				 HP-UX EXTENSIONS



 SYNOPSIS
      void (*signal(int sig, void (*action)(int)))(int);

      void (*sigset(int sig, void (*func)(int)))(int);

 DESCRIPTION
      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.	An alternate mechanism for
      handling these signals is defined here.  The facilities described here
      should not be used in conjunction with the other facilities described
      under signal(2), sigvector(2), sigblock(2), sigsetmask(2),
      sigpause(3C), and sigspace(2).

      Acceptable values for sig are defined in <&lt&lt&lt;signal.h>&gt&gt&gt;.

	   SIG_DFL     Execute the default action, which varies depending on
		       the signal.  The default action for most signals is
		       to terminate the process (see signal(5)).

		       A pending signal is discarded (whether or not it is
		       blocked) if action is set to SIG_DFL but the default
		       action of the pending signal is to ignore the signal
		       (as in the case of SIGCLD).

	   SIG_IGN     Ignore the signal.

		       When signal() is called with action set to SIG_IGN
		       and an instance of the signal sig is pending, the
		       pending signal is discarded, whether or not it is
		       blocked.

		       SIGKILL and SIGSTOP signals cannot be ignored.

	   address     Catch the signal.

		       Upon receipt of signal sig, reset the value of action
		       for the caught signal to SIG_DFL (except signals
		       marked with "not reset when caught"; see signal(5)),
		       call the signal-catching function to which address
		       points, and resume executing the receiving process at
		       the point where it was interrupted.

		       The signal-catching function is called with the
		       following three parameters:





 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 signal(2)							   signal(2)




			    sig	    The signal number.

			    code    A word of information usually provided
				    by the hardware.

			    scp	    A pointer to the machine-dependent
				    structure sigcontext defined in
				    <signal.h>.

		       The pointer scp is valid only during the context of
		       the signal-catching function.  The structure pointer
		       scp is always defined.

		       The code word is always zero for all signals except
		       SIGILL and SIGFPE.  For SIGILL, code has the
		       following values:

			    8	    illegal instruction trap;
			    9	    break instruction trap;
			    10	    privileged operation trap;
			    11	    privileged register trap.

		       For SIGFPE, code has the following values:

			    12	    overflow trap;
			    13	    conditional trap;
			    14	    assist exception trap;
			    22	    assist emulation trap.

		       As defined by the IEEE POSIX Standard, HP-UX does not
		       raise an exception on floating-point divide by zero.
		       The result of floating-point divide by zero is
		       infinity which can be checked by isinf(3M).

		       The signals SIGKILL and SIGSTOP cannot be caught.

      sigset() allows the calling process to choose one of four ways to
      handle the receipt of a specific signal.	sig specifies the signal and
      func specifies the choice.

	   sig	can be any one of the signals described under signal(5)
		except SIGKILL or SIGSTOP.

	   func is assigned one of four values: SIG_DFL, SIG_IGN, SIG_HOLD,
		or a function address. The actions prescribed by SIG_DFL and
		SIG_IGN are described under signal(5).	The action
		prescribed by SIG_HOLD and function address are described
		below:

		     SIG_HOLD		      Hold signal. The signal sig is
					      held upon receipt. Any pending



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 signal(2)							   signal(2)




					      signal of this signal type
					      remains held. Only one signal
					      of each type is held. Note:
					      the signals SIGKILL, SIGCONT,
					      and SIGSTOP cannot be held.

		     function address	      Catch signal.  func must be a
					      pointer to a function, the
					      signal- catching handler, that
					      is called when signal sig
					      occurs.  sigset() specifies
					      that the process calls this
					      function upon receipt of
					      signal sig.  Any pending
					      signal of this type is
					      released. This handler address
					      is retained across calls to
					      the other signal management
					      functions listed here. Upon
					      receipt of signal sig, the
					      receiving process executes the
					      signal-catching function
					      pointed to by func as
					      described under signal(5) with
					      the following differences:

					      Before calling the
					      signal-catching handler, the
					      system signal action of sig is
					      set to SIG_HOLD.	During a
					      normal return from the
					      signal-catching handler, the
					      system signal action is
					      restored to func and any held
					      signal of this type is
					      released. If a non-local goto
					      (longjmp(3C)) is taken,
					      sigrelse() must be called to
					      restore the system signal
					      action to func and release any
					      held signal of this type.

      sighold() holds the signal sig.  sigrelse() restores the system signal
      action of sig to that specified previously by sigset().  sighold() and
      sigrelse() are used to establish critical regions of code.  sighold()
      is analogous to raising the priority level and deferring or holding a
      signal until the priority is lowered by sigrelse().

      sigignore() sets the action for signal sig to SIG_IGN (see signal(5)).





 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 signal(2)							   signal(2)




      sigpause() suspends the calling process until it receives an unblocked
      signal.  If the signal sig is held, it is released before the process
      pauses.  sigpause() is useful for testing variables that are changed
      when a signal occurs.  For example, sighold() should be used to block
      the signal first, then test the variables.  If they have not changed,
      call sigpause() to wait for the signal.

      These functions can be linked into a program by giving the -lV3 option
      to the ld command (see ld(1)).

 ERRORS
      sigset() fails and the system signal action for sig is not changed if
      any of the following occur:

	   [EFAULT]		    The func argument points to memory that
				    is not a valid part of the process
				    address space. Reliable detection of
				    this error is implementation-dependent.

      sigset(), sighold(), sigrelse(), sigignore(), and sigpause() fail and
      the system signal action for sig is not changed if any of the
      following occur:

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

      sigpause returns when the following occurs:

	   [EINTR]		    A signal was caught.

 EXAMPLES
      The following call to signal() sets up a signal-catching function for
      the SIGINT signal:

	   void myhandler();

	   (void) signal(SIGINT, myhandler);

 WARNINGS
      signal() should not be used in conjunction with the facilities
      described under bsdproc(3C), sigaction(2), sigset(3C), or
      sigvector(2).

      signal() does not detect an invalid value for action, and if it does
      not equal SIG_DFL or SIG_IGN, or point to a valid function address,
      subsequent receipt of the signal sig causes undefined results.

 AUTHOR
      signal() was developed by HP, AT&T, and the University of California,



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 signal(2)							   signal(2)




      Berkeley.

 SEE ALSO
      kill(1), init(1M), exit(2), kill(2), lseek(2), pause(2), sigaction(2),
      sigvector(2), wait(2), abort(3C), setjmp(3C), signal(5).

 STANDARDS CONFORMANCE
      signal(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C














































 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000