Movatterモバイル変換

sigaction(3p) — Linux manual page

PROLOG \|NAME \|SYNOPSIS \|DESCRIPTION \|RETURN VALUE \|ERRORS \|EXAMPLES \|APPLICATION USAGE \|RATIONALE \|FUTURE DIRECTIONS \|SEE ALSO \|COPYRIGHT

SIGACTION(3P)           POSIX Programmer's ManualSIGACTION(3P)

PROLOG top

       This manual page is part of the POSIX Programmer's Manual.  The       Linux implementation of this interface may differ (consult the       corresponding Linux manual page for details of Linux behavior), or       the interface may not be implemented on Linux.

NAME top

       sigaction — examine and change a signal action

SYNOPSIS top

       #include <signal.h>       int sigaction(intsig, const struct sigaction *restrictact,           struct sigaction *restrictoact);

DESCRIPTION top

       Thesigaction() function allows the calling process to examine       and/or specify the action to be associated with a specific signal.       The argumentsig specifies the signal; acceptable values are       defined in<signal.h>.       The structuresigaction, used to describe an action to be taken,       is defined in the<signal.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 behavior of    │  │                 │               │signal.                                │  │void(*) (int,│sa_sigaction  │Pointer to a signal-catching function. │  │siginfo_t *,│               │                                       │  │void *)│               │                                       │  └─────────────────┴───────────────┴───────────────────────────────────────┘       The  storage  occupied bysa_handler andsa_sigaction may overlap,       and a conforming application shall not use both simultaneously.       If the argumentact  is  not  a  null  pointer,  it  points  to  a       structure   specifying  the  action  to  be  associated  with  the       specified signal. If the argumentoact is not a null pointer,  the       action  previously  associated  with  the  signal is stored in the       location pointed to by the argumentoact.  If the argumentact  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 thesa_flags       field of thesigactionstructure, thesa_handler field  identifies       the  action  to  be  associated with the specified signal.  If the       SA_SIGINFO flag is set in thesa_flags  field,  thesa_sigaction       field specifies a signal-catching function.       Thesa_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       insa_flags:       SA_NOCLDSTOP  Do not generate SIGCHLD when children stop or                     stopped children continue.                     Ifsig is SIGCHLD and the SA_NOCLDSTOP flag is not                     set insa_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.  Ifsig                     is SIGCHLD and the SA_NOCLDSTOP flag is set insa_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 withsigaltstack(), the signal 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 handler.                     In addition, if this flag is set,sigaction() may                     behave 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 witherrno set to[EINTR].  If set, and a function                     specified as interruptible is interrupted by this                     signal, the function shall restart and shall not                     fail with[EINTR]unless otherwise specified. If an                     interruptible function which uses a timeout is                     restarted, the duration of the timeout following the                     restart is set to an unspecified value that does not                     exceed the original timeout value. If the flag is                     not set, interruptible functions interrupted by this                     signal shall fail witherrno set to[EINTR].       SA_SIGINFO    If cleared and the signal is caught, the signal-                     catching function shall be entered as:                         void func(intsigno);                     wheresigno is the only argument to the signal-                     catching function. In this case, the application                     shall use thesa_handler member to describe the                     signal-catching function and the application shall                     not modify thesa_sigaction member.                     If SA_SIGINFO is set and the signal is caught, the                     signal-catching function shall be entered as:                         void func(intsigno, 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 typesiginfo_texplaining the                     reason why the signal was generated; the third                     argument can be cast to a pointer to an object of                     typeucontext_tto refer to the receiving thread's                     context that was interrupted when the signal was                     delivered. In this case, the application shall use                     thesa_sigaction member to describe the signal-                     catching function and the application shall not                     modify thesa_handler member.                     Thesi_signo member contains the system-generated                     signal number.                     Thesi_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.                     Thesi_code member contains a code identifying the                     cause of the signal, as described inSection 2.4.3,Signal Actions.       SA_NOCLDWAIT  Ifsig does not equal SIGCHLD, the behavior is                     unspecified. Otherwise, the behavior of the                     SA_NOCLDWAIT flag is as specified inConsequences ofProcess Termination.       SA_NODEFER    If set andsig is caught,sig shall not be added to                     the thread's signal mask on entry to the signal                     handler unless it is included insa_mask.                     Otherwise,sig shall always be added to the thread's                     signal mask on entry to the signal handler.       When a signal is caught by a signal-catching function installed bysigaction(), a new signal mask is calculated and installed for the       duration of the signal-catching function (or until a call to       eithersigprocmask() orsigsuspend() is made). This mask is formed       by taking the union of the current signal mask and the value of       thesa_mask for the signal being delivered, and unless SA_NODEFER       or SA_RESETHAND is set, then including the signal being delivered.       If and when the user's signal handler returns normally, the       original signal 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 tosigaction()), until the SA_RESETHAND flag causes resetting       of the handler, or until one of theexec functions is called.       If the previous action forsig had been established bysignal(),       the values of the fields returned in the structure pointed to byoact are unspecified, and in particularoact->sa_handler is not       necessarily the same value passed tosignal().  However, if a       pointer to the same structure or a copy thereof is passed to a       subsequent call tosigaction() via theact argument, handling of       the signal shall be as if the original call tosignal() were       repeated.       Ifsigaction() 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 witherrno set to[EINVAL].       If SA_SIGINFO is not set insa_flags, then the disposition of       subsequent occurrences ofsig when it is already pending is       implementation-defined; the signal-catching function shall be       invoked with a single argument.  If SA_SIGINFO is set insa_flags,       then subsequent occurrences ofsig generated bysigqueue() or as a       result of any signal-generating function that supports the       specification of an application-defined value (whensig is already       pending) shall be queued in FIFO order until delivered or       accepted; the signal-catching function shall be invoked with three       arguments. The application specified value is passed to the       signal-catching function as thesi_value member of thesiginfo_t       structure.       The result of the use ofsigaction() and asigwait() function       concurrently within a process on the same signal is unspecified.

RETURN VALUE top

       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 top

       Thesigaction() function shall fail if:EINVALThesig 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.       Thesigaction() function may fail if:EINVALAn attempt was made to set the action to SIG_DFL for a              signal that cannot be caught or ignored (or both).       In addition, on systems that do not support the XSI option, thesigaction() function may fail if the SA_SIGINFO flag is set in thesa_flags field of thesigactionstructure for a signal not in the       range SIGRTMIN to SIGRTMAX.The following sections are informative.

EXAMPLES top

Establishing a Signal Handler       The following example demonstrates the use ofsigaction() to       establish a handler for the SIGINT signal.           #include <signal.h>           static void handler(int signum)           {               /* Take appropriate actions for signal delivery */           }           int main()           {               struct sigaction sa;               sa.sa_handler = handler;               sigemptyset(&sa.sa_mask);               sa.sa_flags = SA_RESTART; /* Restart functions if                                            interrupted by handler */               if (sigaction(SIGINT, &sa, NULL) == -1)                   /* Handle error */;               /* Further code */           }

APPLICATION USAGE top

       Thesigaction() function supersedes thesignal() function, and       should be used in preference. In particular,sigaction() andsignal() should not be used in the same process to control the       same signal.  The behavior of async-signal-safe functions, as       defined in their respective DESCRIPTION sections, is as specified       by this volume of POSIX.1‐2017, regardless of invocation from a       signal-catching function. This is the only intended meaning of the       statement that async-signal-safe functions may be used in signal-       catching functions without restrictions. Applications must still       consider all effects of such functions on such things as data       structures, files, and process state. In particular, application       developers need to consider the restrictions on interactions when       interruptingsleep() and interactions among multiple handles for a       file description. The fact that any specific function is listed as       async-signal-safe 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-async-       signal-safe function calls, applications should protect calls to       these functions either by blocking the appropriate signals or       through the use of some programmatic semaphore (seesemget(3p),sem_init(3p),sem_open(3p), and so on). Note in particular that       even the ``safe'' functions may modifyerrno; the signal-catching       function, if not executing as an independent thread, should save       and restore its value in order to avoid the possibility that       delivery of a signal in between an error return from a function       that setserrno and the subsequent examination oferrno could       result in the signal-catching function changing the value oferrno.  Naturally, the same principles apply to the async-signal-       safety of application routines and asynchronous data access. Note       thatlongjmp() andsiglongjmp() are not in the list of async-       signal-safe functions. This is because the code executing afterlongjmp() andsiglongjmp() can call any unsafe functions with the       same danger as calling those unsafe functions directly from the       signal handler. Applications that uselongjmp() andsiglongjmp()       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 eithermalloc() orfree() functions or the standard I/O library, both of which       traditionally use data structures in a non-async-signal-safe       manner. Since any combination of different functions using a       common data structure can cause async-signal-safety problems, this       volume of POSIX.1‐2017 does not define the behavior when any       unsafe function is called in a signal handler that interrupts an       unsafe function.       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 thread resumes       execution at the point it was interrupted unless the signal       handler makes other arrangements. Iflongjmp() or_longjmp() is       used to leave the signal handler, then the signal mask must be       explicitly restored.       This volume of POSIX.1‐2017 defines the third argument of a signal       handling function when SA_SIGINFO is set as avoid *instead of aucontext_t *, but without requiring type checking. New       applications should explicitly cast the third argument of the       signal handling function toucontext_t *.       The BSD optional four argument signal handling function is not       supported by this volume of POSIX.1‐2017. The BSD declaration       would be:           void handler(intsig, intcode, struct sigcontext *scp,               char *addr);       wheresig is the signal number,code is additional information on       certain signals,scp is a pointer to thesigcontextstructure, andaddr 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.       Since thesigaction() function is allowed but not required to set       SA_NODEFER when the application sets the SA_RESETHAND flag,       applications which depend on the SA_RESETHAND functionality for       the newly installed signal handler must always explicitly set       SA_NODEFER when they set SA_RESETHAND in order to be portable.       See also the rationale for Realtime Signal Generation and Delivery       in the Rationale (Informative) volume of POSIX.1‐2017,SectionB.2.4.2,Signal Generation and Delivery.

RATIONALE top

       Although this volume of POSIX.1‐2017 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 tosigaction() reflect this in       the information returned in theoact argument. In other words, if       SIGKILL is included in thesa_mask field ofact, it is unspecified       whether or not a subsequent call tosigaction() returns with       SIGKILL included in thesa_mask field ofoact.       The SA_NOCLDSTOP flag, when supplied in theact->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 thewaitpid()       function with the WNOHANG flag set, acting on each child for which       status is returned, untilwaitpid() 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 theptrace() 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 volume of POSIX.1‐2017.       This volume of POSIX.1‐2017 requires that calls tosigaction()       that supply a NULLact argument succeed, even in the case of       signals that cannot be caught or ignored (that is, SIGKILL or       SIGSTOP).  The System Vsignal() and BSDsigvec() functions return[EINVAL]in these cases and, in this respect, their behavior       varies fromsigaction().       This volume of POSIX.1‐2017 requires thatsigaction() properly       save and restore a signal action set up by the ISO C standardsignal() function. However, there is no guarantee that the reverse       is true, nor could there be given the greater amount of       information conveyed by thesigactionstructure. 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 withsigaction().       It was intended that thesignal() function should be implementable       as a library routine usingsigaction().       The POSIX Realtime Extension extends thesigaction() 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 top

       None.

COPYRIGHT top

       Portions of this text are reprinted and reproduced in electronic       form from IEEE Std 1003.1-2017, Standard for Information       Technology -- Portable Operating System Interface (POSIX), The       Open Group Base Specifications Issue 7, 2018 Edition, Copyright       (C) 2018 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 original Standard can be obtained online athttp://www.opengroup.org/unix/online.html .       Any typographical or formatting errors that appear in this page       are most likely to have been introduced during the conversion of       the source files to man page format. To report such errors, seehttps://www.kernel.org/doc/man-pages/reporting_bugs.html .IEEE/The Open Group                2017SIGACTION(3P)

Pages that refer to this page:signal.h(0p), alarm(3p), exec(3p), fcntl(3p), getrusage(3p), ioctl(3p), kill(3p), longjmp(3p), msgrcv(3p), msgsnd(3p), pthread_sigmask(3p), raise(3p), semop(3p), sigaddset(3p), sigaltstack(3p), sigdelset(3p), sigemptyset(3p), sigfillset(3p), sighold(3p), siginterrupt(3p), sigismember(3p), signal(3p), sigsuspend(3p), sigtimedwait(3p), sigwait(3p), sleep(3p)