sigaction man page on DigitalUNIX

Printed from http://www.polarhome.com/service/man/?qf=sigaction&af=0&tf=2&of=DigitalUNIX

sigaction(2)							  sigaction(2)

NAME
       sigaction - Specify the action to take upon delivery of a signal

SYNOPSIS
       #include <signal.h>

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

STANDARDS
       Interfaces  documented on this reference page conform to industry stan‐
       dards as follows:

       sigaction(): XSH4.0, XSH4.2, XSH5.0

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

PARAMETERS
       Defines the signal.  Points to a sigaction structure that describes the
       action to be taken upon receipt of the signal specified by  the	signal
       parameter.   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	 iden‐
       tifies the signal that is to be affected.  Specifying the action param‐
       eter, 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 handling of the signal.  Specify‐
       ing the o_action parameter, if not null, points to a  sigaction	struc‐
       ture that contains the action previously attached to the specified sig‐
       nal.

       The XSH specification 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 POSIX realtime and UNIX programs that conform to
       XSH:

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

       These sigaction members are described as follows:  [XSH4.2]  A  pointer
       to  a  signal-handling  function.   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 deliv‐
       ered. A value of SIG_IGN specifies that the signal has no effect on the
       receiving  process. A pointer to a function requests that the signal be
       caught; that is, the signal should cause the  function  to  be  called.
       These  actions  are more fully described in <signal.h>.	This field can
       request that individual signals, in addition to those  in  the  current
       signal  mask,  be blocked from being delivered while the signal handler
       function specified by the sa_handler or sa_sigaction field  is  execut‐
       ing.   This field can set the following flags to enable further control
       over the actions taken when a signal  is	 delivered:  [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.  [XSH4.2]  Setting  this  bit	causes
       the  signal to be reset to SIG_DFL. Note that SIGILL, SIGTRAP, and SIG‐
       PWR cannot be automatically reset.  [XSH4.2]  Setting this  bit	causes
       the signal not to be blocked automatically by the kernel as it is being
       caught.	[XSH4.2]  Setting this bit enables a function  that  has  been
       interrupted  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 termi‐
       nal, 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].
       [XSH4.2]	 If this bit is clear, the signal-catching function adheres to
       the following format:

	      void func ( int signo );

	      In this format, signo is the only argument to the	 signal-catch‐
	      ing  function. This argument contains the signal number. In this
	      case, the sa_handler member of the sigaction structure  must  be
	      used  to describe the signal-catching function, and the applica‐
	      tion must not modify the sa_sigaction member.

	      If the SA_SIGINFO bit is set and the signal is caught, the  sig‐
	      nal-catching function adheres to the following format:

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

	      In  this format, two additional arguments are passed to the sig‐
	      nal-catching function: If	 the  info  argument  is  not  a  null
	      pointer,	it  points  to	a  structure  of  type	siginfo_t that
	      explains the reason why the signal was generated.	 The  si_signo
	      member  of  this	structure contains the system-generated signal
	      number. If non-zero, the si_errno member contains an error  num‐
	      ber  identifying the condition that caused the signal to be gen‐
	      erated.  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  the
	      si_pid  and  si_uid members indicate the process ID and the real
	      user ID of the sender.  The values of si_pid and si_uid are oth‐
	      erwise  meaningless.   The  context  argument  can  be cast to a
	      pointer to an object of type ucontext_t to refer to the  receiv‐
	      ing  process'  context  that was interrupted when the signal was
	      delivered.  In this case, the sa_sigaction member of the	sigac‐
	      tion  structure  must  be	 used  to describe the signal catching
	      function, and the application must  not  modify  the  sa_handler
	      member.

	      [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 <machine/signal.h>).  The third argument
	      points to a sigcontext structure containing context  information
	      in a different format.  If this bit is set and the signal param‐
	      eter is equal to SIGCHLD, a SIGCHLD signal is not	 sent  to  the
	      calling  process	when  child processes terminate.  [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	 a  wait(),  waitid(),
	      waitpid(), or wait3() call is subsequently issued by the calling
	      process, it blocks until all of its child	 processes  terminate.
	      The call 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.
	      [Tru64 UNIX]  If this bit is set in combination with SA_SIGINFO,
	      two  SIGCHLD  signals are queued to the parent for each abnormal
	      termination 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 par‐
	      ent  process  that  the child process is now a zombie and can be
	      cleaned up with a call to wait().

	      When SA_CLDNOTIFY is used without SA_SIGINFO, the early  notifi‐
	      cation signal is not sent to the parent.

       Once an action is installed for a specific signal, it remains installed
       until one of the following occurs: Another sigaction() call  explicitly
       requests	 a  different action.  [XSH4.2]	 A signal causes the SA_RESET‐
       HAND flag to reset the signal handler.  A call is made 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 asyn‐
       chronous signals.

NOTES
       Only otherwise noted, sections in this reference page that  are	marked
       by  [XSH4.2]    also  apply  to	compilation environments conforming to
       higher revisions of the XSH specification.

       [Tru64 UNIX]  When compiled in XSH4.2 and higher	 compilation  environ‐
       ments,  calls  to  the  sigaction()  function are internally renamed by
       prepending _E to the function name.  When you are  debugging  a	module
       that    includes	   the	  sigaction()	 function    and   for	 which
       _XOPEN_SOURCE_EXTENDED or a more current	 XSH  compilation  environment
       has  been  defined,  use	 _Esigaction to refer to the sigaction() call.
       See standards(5) for information about  compilation  macro  definitions
       for industry standards.

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: [Tru64  UNIX]  The
       action  or o_action parameter points to a location outside of the allo‐
       cated address space of the process.  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.

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);
	       }

SEE ALSO
       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)

								  sigaction(2)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net