👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for sigaction (linux section 3posix)

SIGACTION(P)			    POSIX Programmer's Manual			     SIGACTION(P)

NAME
       sigaction - examine and change a signal action

SYNOPSIS
       #include <signal.h>

       int sigaction(int sig, const struct sigaction *restrict act,
	      struct sigaction *restrict oact);

DESCRIPTION
       The  sigaction()  function allows the calling process to examine and/or specify the action
       to be associated with a specific signal. The argument sig specifies the signal; acceptable
       values are defined in <signal.h>.

       The  structure  sigaction, used to describe an action to be taken, is defined in the <sig-
       nal.h> header to include at least the following members:

		    Member Type       Member Name    Description
		    void(*) (int)     sa_handler     Pointer to a signal-catching
						     function or one of the macros
						     SIG_IGN or SIG_DFL.
		    sigset_t	      sa_mask	     Additional set of signals to
						     be blocked during execution of
						     signal-catching function.
		    int 	      sa_flags	     Special flags to affect behav-
						     ior of signal.
		    void(*) (int,
		      siginfo_t *,    sa_sigaction   Pointer to a signal-catching
		    void *)			     function.

       The storage occupied by sa_handler and sa_sigaction may overlap, and a conforming applica-
       tion shall not use both simultaneously.

       If the argument act is not a null pointer, it points to a structure specifying the  action
       to  be  associated  with the specified signal. If the argument oact is not a null pointer,
       the action previously associated with the signal is stored in the location pointed  to  by
       the  argument  oact.  If the argument act is a null pointer, signal handling is unchanged;
       thus, the call can be used to enquire about the current handling of a  given  signal.  The
       SIGKILL	and  SIGSTOP  signals shall not be added to the signal mask using this mechanism;
       this restriction shall be enforced by the system without causing an error to be indicated.

       If the SA_SIGINFO flag (see below) is cleared in  the  sa_flags	field  of  the	sigaction
       structure,  the sa_handler field identifies the action to be associated with the specified
       signal.	  If the SA_SIGINFO flag is set in the sa_flags  field,  and  the  implementation
       supports  the Realtime Signals Extension option or the XSI Extension option, the sa_sigac-
       tion field specifies a signal-catching function.  If the SA_SIGINFO bit is cleared and the
       sa_handler  field  specifies  a signal-catching function, or if the SA_SIGINFO bit is set,
       the sa_mask field identifies a set of signals that shall be added to the  signal  mask  of
       the  thread before the signal-catching function is invoked. If the sa_handler field speci-
       fies a signal-catching function, the sa_mask field identifies a set of signals that  shall
       be added to the process' signal mask before the signal-catching function is invoked.

       The sa_flags field can be used to modify the behavior of the specified signal.

       The following flags, defined in the <signal.h> header, can be set in sa_flags:

       SA_NOCLDSTOP
	      Do not generate SIGCHLD when children stop    or stopped children continue.

       If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in sa_flags, and the implementation
       supports the SIGCHLD signal, then a SIGCHLD signal shall  be  generated	for  the  calling
       process	whenever any of its child processes stop    and a SIGCHLD signal may be generated
       for the calling process whenever any of its stopped child processes  are  continued.    If
       sig is SIGCHLD and the SA_NOCLDSTOP flag is set in sa_flags, then the implementation shall
       not generate a SIGCHLD signal in this way.

       SA_ONSTACK
	      If set and an alternate signal stack has been declared with sigaltstack(), the sig-
	      nal  shall be delivered to the calling process on that stack. Otherwise, the signal
	      shall be delivered on the current stack.

       SA_RESETHAND
	      If set, the disposition of the signal shall be reset to SIG_DFL and the  SA_SIGINFO
	      flag shall be cleared on entry to the signal handler.

       Note:
	      SIGILL  and  SIGTRAP  cannot  be	automatically  reset  when  delivered; the system
	      silently enforces this restriction.

       Otherwise, the disposition of the signal shall not be modified on entry to the signal han-
       dler.

       In  addition, if this flag is set, sigaction() behaves as if the SA_NODEFER flag were also
       set.

       SA_RESTART
	      This flag affects the behavior of interruptible functions; that is, those specified
	      to  fail	with errno set to [EINTR]. If set, and a function specified as interrupt-
	      ible is interrupted by this signal, the function shall restart and shall	not  fail
	      with  [EINTR]  unless  otherwise	specified.  If the flag is not set, interruptible
	      functions interrupted by this signal shall fail with errno set to [EINTR].

       SA_SIGINFO
	      If cleared and the signal is caught, the signal-catching function shall be  entered
	      as:

	      void func(int signo);

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

       If  SA_SIGINFO  is  set	and  the  signal is caught, the signal-catching function shall be
       entered as:

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

       where two additional arguments are passed to the  signal-catching  function.   The  second
       argument  shall	point 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' context that was interrupted when the signal was deliv-
       ered. In this case, the application shall use the sa_sigaction member to describe the sig-
       nal-catching function and the application shall not modify the sa_handler member.

       The si_signo member contains the system-generated signal number.

       The  si_errno  member  may contain implementation-defined additional error information; if
       non-zero, it contains an error number identifying 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, respectively, indicate the process ID and the real user  ID
       of  the	sender.  The <signal.h> header description contains information about the signal-
       specific contents of the elements of the siginfo_t type.

       SA_NOCLDWAIT
	      If set, and sig equals SIGCHLD, child processes of the calling processes shall  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 shall block until all of its chil-
	      dren terminate, and wait(), waitid(), and waitpid() shall fail  and  set	errno  to
	      [ECHILD].  Otherwise,  terminating child processes shall be transformed into zombie
	      processes, unless SIGCHLD is set to SIG_IGN.

       SA_NODEFER
	      If set and sig is caught, sig shall not be added to the  process'  signal  mask  on
	      entry  to the signal handler unless it is included in sa_mask. Otherwise, sig shall
	      always be added to the process' signal mask on entry to the signal handler.

       When a signal is caught by a signal-catching function installed by sigaction(), a new sig-
       nal  mask is calculated and installed for the duration of the signal-catching function (or
       until a call to either sigprocmask() or sigsuspend() is made). This mask is formed by tak-
       ing the union of the current signal mask and the value of the sa_mask for the signal being
       delivered    unless SA_NODEFER or SA_RESETHAND is set,	and  then  including  the  signal
       being delivered. If and when the user's signal handler returns normally, the original sig-
       nal mask is restored.

       Once an action is installed for a specific signal, it shall remain installed until another
       action is explicitly requested (by another call to sigaction()),    until the SA_RESETHAND
       flag causes resetting of the handler,   or until one of the exec functions is called.

       If the previous action for sig had been established by signal(), the values of the  fields
       returned  in  the  structure  pointed to by oact are unspecified, and in particular oact->
       sa_handler is not necessarily the same value passed to signal().  However, if a pointer to
       the same structure or a copy thereof is passed to a subsequent call to sigaction() via the
       act argument, handling of the signal shall be as if the original  call  to  signal()  were
       repeated.

       If sigaction() fails, no new signal handler is installed.

       It  is unspecified whether an attempt to set the action for a signal that cannot be caught
       or ignored to SIG_DFL is ignored or causes an error to be returned with errno set to [EIN-
       VAL].

       If  SA_SIGINFO  is  not set in sa_flags, then the disposition of subsequent occurrences of
       sig when it is already pending is  implementation-defined;  the	signal-catching  function
       shall  be  invoked  with a single argument.    If the implementation supports the Realtime
       Signals Extension option, and if SA_SIGINFO is set in  sa_flags,  then  subsequent  occur-
       rences  of  sig	generated  by sigqueue() or as a result of any signal-generating function
       that supports the specification of an application-defined value (when sig is already pend-
       ing)  shall be queued in FIFO order until delivered or accepted; the signal-catching func-
       tion shall be invoked with three arguments. The application specified value is  passed  to
       the signal-catching function as the si_value member of the siginfo_t structure.

       The  result  of	the  use  of  sigaction()  and a sigwait() function concurrently within a
       process on the same signal is unspecified.

RETURN VALUE
       Upon successful completion, sigaction() shall return 0; otherwise, -1 shall  be	returned,
       errno  shall  be  set  to indicate the error, and no new signal-catching function shall be
       installed.

ERRORS
       The sigaction() function shall fail if:

       EINVAL The sig argument is not a valid signal number or an attempt is made to catch a sig-
	      nal that cannot be caught or ignore a signal that cannot be ignored.

       ENOTSUP
	      The  SA_SIGINFO  bit  flag is set in the sa_flags field of the sigaction structure,
	      and the implementation does not  support	either	the  Realtime  Signals	Extension
	      option, or the XSI Extension option.

       The sigaction() 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 following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       The sigaction() function supersedes the signal() function, and should be used  in  prefer-
       ence.  In  particular,  sigaction() and signal() should not be used in the same process to
       control the same signal. The behavior of reentrant functions, as defined in  the  DESCRIP-
       TION,  is  as  specified  by this volume of IEEE Std 1003.1-2001, regardless of invocation
       from a signal-catching function. This is the only intended meaning of the  statement  that
       reentrant functions may be used in signal-catching functions without restrictions.  Appli-
       cations must still consider all effects of such functions on such things  as  data  struc-
       tures,  files,  and process state. In particular, application writers need to consider the
       restrictions on interactions when interrupting sleep()  and  interactions  among  multiple
       handles for a file description. The fact that any specific function is listed as reentrant
       does not necessarily mean that invocation of that function from a signal-catching function
       is recommended.

       In  order to prevent errors arising from interrupting non-reentrant function calls, appli-
       cations should protect calls to these functions either by blocking the appropriate signals
       or  through the use of some programmatic semaphore (see semget() , sem_init() , sem_open()
       , and so on). Note in particular that even the "safe" functions may modify errno; the sig-
       nal-catching  function,	if  not  executing as an independent thread, may want to save and
       restore its value. Naturally, the same principles apply to the reentrancy  of  application
       routines and asynchronous data access. Note that longjmp() and siglongjmp() are not in the
       list of reentrant functions.  This is because the code executing after longjmp() and  sig-
       longjmp() can call any unsafe functions with the same danger as calling those unsafe func-
       tions directly from the signal handler. Applications that use longjmp()	and  siglongjmp()
       from  within  signal handlers require rigorous protection in order to be portable. Many of
       the other functions that are excluded from the list are	traditionally  implemented  using
       either  malloc() or free() functions or the standard I/O library, both of which tradition-
       ally use data structures in a non-reentrant manner. Since  any  combination  of	different
       functions  using  a  common  data  structure can cause reentrancy problems, this volume of
       IEEE Std 1003.1-2001 does not define the behavior when any unsafe function is called in	a
       signal handler that interrupts an unsafe function.

       If  the signal occurs other than as the result of calling abort(), kill(), or raise(), the
       behavior is undefined if the signal handler calls any function  in  the	standard  library
       other  than  one  of  the functions listed in the table above or refers to any object with
       static storage duration other than by assigning a value to a static storage duration vari-
       able  of type volatile sig_atomic_t. Furthermore, if such a call fails, the value of errno
       is unspecified.

       Usually, the signal is executed on the stack that was in  effect  before  the  signal  was
       delivered.  An  alternate  stack may be specified to receive a subset of the signals being
       caught.

       When the signal handler returns, the receiving process resumes execution at the	point  it
       was  interrupted  unless  the  signal  handler  makes  other arrangements. If longjmp() or
       _longjmp() is used to leave the signal handler, then the signal mask  must  be  explicitly
       restored by the process.

       This  volume of IEEE Std 1003.1-2001 defines the third argument of a signal handling func-
       tion when SA_SIGINFO is set as a void * instead of a ucontext_t *, but  without	requiring
       type  checking.	New  applications should explicitly cast the third argument of the signal
       handling function to ucontext_t *.

       The BSD optional four argument signal handling function is not supported by this volume of
       IEEE Std 1003.1-2001. The BSD declaration would be:

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

       where  sig is the signal number, code is additional information on certain signals, scp is
       a pointer to the sigcontext structure, and addr is additional address  information.   Much
       the  same information is available in the objects pointed to by the second argument of the
       signal handler specified when SA_SIGINFO is set.

RATIONALE
       Although this volume of IEEE Std 1003.1-2001 requires that signals that cannot be  ignored
       shall not be added to the signal mask when a signal-catching function is entered, there is
       no explicit requirement that subsequent calls to sigaction() reflect this in the  informa-
       tion  returned in the oact argument. In other words, if SIGKILL is included in the sa_mask
       field of act, it is unspecified whether or not a subsequent call  to  sigaction()  returns
       with SIGKILL included in the sa_mask field of oact.

       The  SA_NOCLDSTOP  flag, when supplied in the act-> sa_flags parameter, allows overloading
       SIGCHLD with the System V semantics that each SIGCLD signal indicates a single  terminated
       child.  Most  conforming  applications  that catch SIGCHLD are expected to install signal-
       catching functions that repeatedly call the waitpid() function with the WNOHANG flag  set,
       acting  on  each  child	for  which  status  is returned, until waitpid() returns zero. If
       stopped children are not of interest, the use of the SA_NOCLDSTOP  flag	can  prevent  the
       overhead from invoking the signal-catching routine when they stop.

       Some  historical implementations also define other mechanisms for stopping processes, such
       as the ptrace() function. These implementations usually do not generate a  SIGCHLD  signal
       when  processes stop due to this mechanism; however, that is beyond the scope of this vol-
       ume of IEEE Std 1003.1-2001.

       This volume of IEEE Std 1003.1-2001 requires that calls to sigaction() that supply a  NULL
       act  argument  succeed, even in the case of signals that cannot be caught or ignored (that
       is, SIGKILL or SIGSTOP). The System V signal() and BSD sigvec() functions return  [EINVAL]
       in these cases and, in this respect, their behavior varies from sigaction().

       This  volume of IEEE Std 1003.1-2001 requires that sigaction() properly save and restore a
       signal action set up by the ISO C standard signal() function. However, there is no guaran-
       tee  that  the reverse is true, nor could there be given the greater amount of information
       conveyed by the sigaction structure. Because of this, applications should avoid using both
       functions  for the same signal in the same process. Since this cannot always be avoided in
       case of general-purpose library routines, they should always be	implemented  with  sigac-
       tion().

       It  was	intended  that the signal() function should be implementable as a library routine
       using sigaction().

       The POSIX Realtime  Extension  extends  the  sigaction()  function  as  specified  by  the
       POSIX.1-1990  standard  to  allow  the application to request on a per-signal basis via an
       additional signal action flag that the extra parameters, including the application-defined
       signal value, if any, be passed to the signal-catching function.

FUTURE DIRECTIONS
       None.

SEE ALSO
       Signal  Concepts  ,  bsd_signal() , kill() , _longjmp() , longjmp() , raise() , semget() ,
       sem_init() , sem_open() , sigaddset() , sigaltstack() , sigdelset() , sigemptyset() , sig-
       fillset()  , sigismember() , signal() , sigprocmask() , sigsuspend() , wait() , waitid() ,
       waitpid() , the Base Definitions volume of IEEE Std 1003.1-2001, <signal.h>, <ucontext.h>

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				     SIGACTION(P)


All times are GMT -4. The time now is 01:54 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password