unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



sigaction(2)							 sigaction(2)



NAME

  sigaction - Specifies	the action to take upon	delivery of a signal

SYNOPSIS

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

  int sigaction(
	  int signal,
	  const	struct sigaction *action,
	  struct sigaction *o_action);

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  sigaction():	XPG4, XPG4-UNIX

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  signal
      Defines the signal.

  action
      Points to	a sigaction structure that describes the action	to be taken
      upon receipt of the signal specified by the signal parameter.

  o_action
      Points to	a sigaction structure.	When the sigaction() function returns
      from a call, the action previously attached to the specified signal is
      stored in	this structure.

DESCRIPTION

  When a process requests the sigaction() function, the	process	can both
  examine or specify what action is to be performed when the specified signal
  is delivered.	 The parameters	determine the behavior of the sigaction()
  function as follows:

    +  Specifying the signal parameter identifies the signal that is to	be
       affected.

    +  Specifying the action parameter,	if not null, points to a sigaction
       structure that defines what action is to	be performed when the signal
       is received.  If	the action parameter is	null, signal handling remains
       unchanged; thus the call	can be used to inquire about the current han-
       dling of	the signal.

    +  Specifying the o_action parameter, if not null, points to a sigaction
       structure that contains the action previously attached to the speci-
       fied signal.

  The X/Open Base Standard defines the following members for the sigaction
  structure:

  void	    (*sa_handler)(int);

  sigset_t  sa_mask;

  int	    sa_flags;

  [XSH4.2]  The	following additional member is defined in the sigaction
  structure for	use by realtime	and X/Open UNIX	programs:

  void(*) (int,	siginfo_t *, void *)
	    sa_sigaction;

  The members are defined as follows:

  sa_sigaction
      [XSH4.2]	A pointer to a signal-handling function.

  sa_handler
      This field can contain a value of	SIG_DFL	or SIG_IGN, or it can point
      to a function.  A	SIG_DFL	value specifies	the default action is to be
      taken when the signal is delivered.  A value of SIG_IGN specifies	that
      the signal has no	effect on the receiving	process. A pointer to a	func-
      tion requests that the signal be caught; that is,	the signal should
      cause the	function to be called. These actions are more fully described
      in the <&lt;signal.h>&gt;	file.

  sa_mask
      This field can request that individual signals, in addition to those in
      the current signal mask, be blocked from being delivered while the sig-
      nal handler function specified by	the sa_handler or sa_sigaction field
      is executing.

  sa_flags
      This field can set the following flags to	enable further control over
      the actions taken	when a signal is delivered:

      SA_ONSTACK
	  [XSH4.2]  Setting this bit causes the	system to run the signal-
	  catching function on the signal stack	specified by the
	  sigaltstack()	and sigstack() functions.  If this bit is not set,
	  the function runs on the stack of the	process	to which the signal
	  is delivered.

      SA_RESETHAND
	  [XSH4.2]  Setting this bit causes the	signal to be reset to
	  SIG_DFL.  Note that SIGILL, SIGTRAP, and SIGPWR cannot be automati-
	  cally	reset.

      SA_NODEFER
	  [XSH4.2]  Setting this bit causes the	signal not to be blocked
	  automatically	by the kernel as it is being caught.

      SA_RESTART
	  [XSH4.2]  Setting this bit enables a function	that has been inter-
	  rupted by the	execution of this signal's handler to be restarted
	  transparently	by the system.	The affected functions include
	  wait(), and the read() and write() functions on a slow device	(such
	  as a terminal, but not a regular file). If this bit is not set and
	  one of the previously	mentioned functions is interrupted by a
	  signal which is caught, the function returns the value -1 and	sets
	  errno	to [EINTR].

      SA_SIGINFO
	  [XSH4.2]  If this bit	is clear, the signal-catching function is
	  entered as:



	  void func(int	signo);

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

	  If this bit is set and the signal is caught, the signal-catching
	  function is entered as:



	  void func(int	signo, siginfo_t *info,	void *context);

	  where	two additional arguments are passed to the signal-catching
	  function.  If	the second argument is not a null pointer, it points
	  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 ucontext_t to refer to	the receiving process' con-
	  text that was	interrupted 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 contains the system-generated signal number.

	  If non-zero, the si_errno member contains an error number identify-
	  ing the condition that caused	the signal to be generated.

	  The si_code member contains a	code identifying 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 indi-
	  cate the process ID and the real user	ID of the sender.  The values
	  of si_pid and	si_uid are otherwise meaningless.

	  [Tru64 UNIX]	In the backward-compatible version of sigaction(),
	  the second and third arguments available to the signal are defined
	  as follows:

	    +  If SA_SIGINFO is	clear, the second argument is an integer
	       value providing additional error	information for	exception
	       signals (see <&lt;machine/signal.h>&gt;).

	    +  The third argument points to a sigcontext structure containing
	       context information in a	different format.

      SA_NOCLDSTOP
	  If this bit is set and the signal parameter is equal to SIGCHLD, a
	  SIGCHLD signal is not	sent to	the calling process when child
	  processes terminate.

      SA_NOCLDWAIT
	  [XSH4.2]  If this bit	is set and the signal parameter	is equal to
	  SIGCHLD, zombie processes are	not created by the system when a
	  child	process	of the calling process exits.  If the wait function
	  is subsequently issued by the	calling	process, it blocks until all
	  of its child processes terminate.  It	then returns a value of	-1
	  and errno is set to ECHILD to	indicate the error.  Note:  when this
	  flag is set, exiting child processes do not send SIGCHLD signals to
	  the parent.

      SA_CLDNOTIFY
	  [Tru64 UNIX]	If this	bit is set in combination with SA_SIGINFO,
	  two SIGCHLD signals are queued to the	parent for each	abnormal ter-
	  mination of a	child process that includes a core dump: an early
	  notification signal and a  final notification	signal.

	  The early notification signal	delivers a siginfo structure with the
	  si_signo field set to	SIGCHLD, the si_code field set to
	  CLD_SIGEXITING, and the si_pid field set to the process ID of	the
	  child	process	that is	about to write a core file and then terminate
	  abnormally.  This signal tells the parent process that it can	start
	  a failover operation or take other appropriate action.

	  The final notification signal	delivers a siginfo structure with the
	  si_signo field set to	SIGCHLD, the si_code field set to CLD_DUMPED,
	  and the si_pid field set to the process ID of	the child that has
	  terminated abnormally.  This signal tells the	parent process that
	  the child process is now a zombie and	can be cleaned up with a call
	  to wait(2).

	  When SA_CLDNOTIFY is used without SA_SIGINFO,	the early notifica-
	  tion signal is not sent to the parent.

  Once an action is installed for a specific signal, it	remains	installed
  until	one of the following events occurs:

    +  A sigaction() call that explicitly requests a different action.

    +  [XSH4.2]	 A signal that causes the SA_RESETHAND flag to reset the sig-
       nal handler.

    +  A call to one of	the exec* functions.

  The signal parameter can be any one of the signal values defined in the
  signal.h header file,	except SIGKILL and SIGSTOP.

  In a multithreaded environment, the sigaction() function should only be
  used for the synchronous signals. Use	the sigwait() function for asynchro-
  nous signals.

NOTES

  [Tru64 UNIX]	When compiled in the X/Open UNIX environment, calls to the
  sigaction() function are internally renamed by prepending _E to the func-
  tion name.  When you are debugging a module that includes the	sigaction()
  function and for which _XOPEN_SOURCE_EXTENDED	has been defined, use _Esi-
  gaction to refer to the sigaction() call.  See standards(5) for information
  on when the _XOPEN_SOURCE_EXTENDED macro is defined.

EXAMPLE

  The following	program	illustrates the	use of the SA_CLDNOTIFY	flag:

	       #include	<stdio.h>
	       #include	<sys/types.h>
	       #include	<sys/signal.h>
	       #include	<sys/siginfo.h>

	       volatile	pid_t kid1, kid2;

	       /*
		* Handler for SIGHCLD signal. Note: printf() calls
		* are technically unsupported from signal handlers
		* and are shown	for illustrative purposes only.
		*/
	       void
	       sigchld_handler(int sig,	siginfo_t *sip,	void *extra)
	       {
		       pid_t kid;
		       kid = sip->si_pid;
		       if (sip->si_code	== CLD_SIGEXITING) {
			       printf("SIGEXITING: Got signal %d, si_code %d"
				      "	for kid	%d\n",
				      sip->si_signo, sip->si_code, kid);
		       } else if (sip->si_code == CLD_DUMPED) {
			       printf("EXITED: Got signal %d, si_code %d"
				      "	for kid	%d\n",
				       sip->si_signo, sip->si_code, kid);
			       kid = wait(0);
			       printf("Parent got PID %d exiting\n", kid);
			       if (kid == kid1)
				       kid1 = 0;
			       else if (kid == kid2)
				       kid2 = 0;
		       }
	       }

	       main()
	       {
		       struct sigaction	sa;
		       int ret;

		       /*
			* Set up SIGHCLD handler for early exit
			* notification.
			*/
		       sa.sa_sigaction = sigchild_handler;
		       sigemptyset(&sa.sa_mask);
		       sa.sa_flags = SA_CLDNOTIFY|SA_SIGINFO;

		       ret = sigaction(SIGCHLD,	&sa, 0);
		       if (ret)	{
			       perror("sigaction");
			       exit(1);
		       }


		       /*
			* Create 2 children to die with	SIGABRT
			* and create core files.
			*/
		       kid1 = fork();
		       if (kid1)
			       printf("Parent forked %d\n", kid1);
		       else {
			       /*
				* First	child...
				*/
			       sleep(1);
			       printf("Kid %d will now die with	core file...\n",
				       getpid());
			       abort();
			       /*NOTREACHED*/
		       }
		       kid2 = fork();
		       if (kid2)
			       printf("Parent forked %d\n", kid2);
		       else {
			       /*
				* Second child...
				*/
			       sleep(1);
			       printf("Kid %d will now die with	core file...\n",
				       getpid());
			       abort();
			       /*NOTREACHED*/
		       }

		       /*
			* Parent: keep busy until children exit.
			*/
			while (kid1 || kid2)
			      ;
		       /*
			* Children have	exit: verify by	printing zeros.
			*/
		       printf("Parent: done -- kid1 %d,	kid2 %d\n", kid1, kid2);
			      ;
		       /*
			* Children have	exit: verify by	printing zeros.
			*/
		       printf("Parent: done -- kid1 %d,	kid2 %d\n", kid1, kid2);
	       }


RETURN VALUES

  Upon successful completion of	the sigaction()	function, a value of zero (0)
  is returned. If the sigaction() function fails, a value of -1	is returned
  and errno is set to indicate the error.

ERRORS

  If the sigaction() function fails, no	new signal handler is installed	and
  errno	may be set to one of the following values:

  [EFAULT]  [Tru64 UNIX]  The action or	o_action parameter points to a loca-
	    tion outside of the	allocated address space	of the process.

  [EINVAL]  The	signal parameter is not	a valid	signal number.

	    An attempt was made	to ignore or supply a handler for the SIGKILL
	    and	SIGSTOP	signals.

RELATED	INFORMATION

  Functions: acct(2), exit(2), kill(2),	ptrace(2), sigblock(2),	sigproc-
  mask(2), sigstack(2),	sigsuspend(2), sigvec(2), umask(2), wait(2),
  pause(3), setjmp(3), sigpause(3)

  Commands: kill(1)

  Files: signal(4)

  Standards: standards(5)