SIGACTION(2)

BEZEICHNUNG
sigaction, rt_sigaction - Signalaktionen untersuchen und ändern

ÜBERSICHT
#include <signal.h>

int sigaction(int signum, const struct sigaction *act,
              struct sigaction *oldact);

Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):

sigaction(): _POSIX_C_SOURCE siginfo_t: _POSIX_C_SOURCE >= 199309L

BESCHREIBUNG
Der Systemaufruf sigaction wird zur Veränderung der von einem Prozess beim Empfang eines Signals durchgeführten Aktion benutzt. (Siehe signal(7) für einen Überblick über Signale.)

signum legt das Signal fest und kann jedes gültige Signal außer SIGKILL und SIGSTOP sein.

Falls act nicht NULL ist, wird die neue Aktion für Signal signum aus act installiert. Falls oldact nicht Null ist, wird die vorherige Aktion in oldact gespeichert.

Die Struktur sigaction wird durch etwas wie das folgende definiert:

struct sigaction {
    void     (*sa_handler)(int);
    void     (*sa_sigaction)(int, siginfo_t *, void *);
    sigset_t   sa_mask;
    int        sa_flags;
    void     (*sa_restorer)(void);
};

On some architectures a union is involved: do not assign to both sa_handler and sa_sigaction.

Das Feld sa_restorer ist nicht zur Verwendung durch Anwendungen gedacht. (POSIX spezifiziert ein Feld sa_restorer nicht.) Weitere Details über den Zweck dieses Feldes finden Sie in sigreturn(2).

sa_handler legt die signum zugeordnete Funktion fest; sie könnte SIG_DFL als Vorgabeaktion sein, SIG_IGN, um dieses Signal zu ignorieren oder ein Zeiger auf eine Signalhandhabungsfunktion. Diese Funktion erhält die Signalnummer als einziges Argument.

If SA_SIGINFO is specified in sa_flags, then sa_sigaction (instead of sa_handler) specifies the signal-handling function for signum. This function receives the signal number as its first argument, a pointer to a siginfo_t as its second argument and a pointer to a ucontext_t (cast to void *) as its third argument. (Commonly, the handler function doesn't make any use of the third argument. See getcontext(3) for further information about ucontext_t.)

sa_mask legt eine Signalmaske fest, die angibt, welche Signale während der Ausführung der Signalhandhabungsfunktion blockiert (d.h. zu der Signalmaske des Threads, in der der Signalhandler aufgerufen wird, hinzugefügt) werden sollen. Zusätzlich wird das Signal, das den Handler ausgelöst hat, blockiert, falls nicht der Schalter SA_NODEFER verwandt wurde.

sa_flags legt eine Gruppe von Schaltern fest, die das Verhalten des Signals verändern. Es wird durch bitweise ODER-Verknüpfung von Null oder mehreren der folgenden Werte erstellt:

    SA_NOCLDSTOP
        Falls signum SIGCHLD ist werden keine Benachrichtigungen empfangen, wenn ein Kindprozess gestoppt (d.h. wenn es SIGSTOP, SIGTSTP, SIGTTIN oder SIGTTOU empfängt) oder wiederaufgenommen wird (d.h. es SIGCONT empfängt) (siehe wait(2)). Dieser Schalter ist nur bei der Einrichtung eines Handlers für SIGCHLD von Bedeutung.

    SA_NOCLDWAIT (seit Linux 2.6)
        If signum is SIGCHLD, do not transform children into zombies when they terminate. See also waitpid(2). This flag is meaningful only when establishing a handler for SIGCHLD, or when setting that signal's disposition to SIG_DFL. Falls der Schalter SA_NOCLDWAIT beim Einrichten eines Handlers für SIGCHLD gesetzt ist, lässt es POSIX.1 unspezifiziert, ob ein Signal SIGCHLD generiert wird, wenn sich ein Kindprozess beendet. Unter Linux wird in diesem Fall ein Signal SIGCHLD generiert, bei einigen anderen Implementierungen passiert das nicht.

    SA_NODEFER
        Es wird nicht verhindert, dass das Signal innerhalb seines eigenen Signal-Handlers empfangen wird. Dieser Schalter ist nur bei der Einrichtung eines Handlers von Bedeutung. SA_NOMASK ist ein veraltetes, nicht standardisiertes Synonym für diesen Schalter.

    SA_ONSTACK
        Call the signal handler on an alternate signal stack provided by sigaltstack(2). If an alternate stack is not available, the default stack will be used. This flag is meaningful only when establishing a signal handler.

    SA_RESETHAND
        Stellt die Signalaktion beim Eintritt in den Signal-Handler auf den Vorgabewert zurück. Dieser Schalter ist nur bei der Einrichtung eines Handlers von Bedeutung. SA_ONESHOT ist ein veraltetes, nicht standardisiertes Synonym für diesen Schalter.

    SA_RESTART
        Stellt ein zur BSD-Signalsemantik kompatibles Verhalten her, indem bestimmte Systemaufrufe über Signale hinweg neu gestartet werden können. Dieser Schalter ist nur bei der Einrichtung eines Handlers von Bedeutung. Siehe signal(7) für eine Diskussion bezüglich des Neustarts von Systemaufrufen.

    SA_RESTORER
        Not intended for application use. This flag is used by C libraries to indicate that the sa_restorer field contains the address of a "signal trampoline". See sigreturn(2) for more details.

    SA_SIGINFO (seit Linux 2.2)
        Der Signal-Handler erwartet drei Argumente, nicht eines. In diesem Fall sollte sa_sigaction auf sa_handler gesetzt werden. Dieser Schalter ist nur bei der Einrichtung eines Handlers von Bedeutung.

  The siginfo_t argument to a SA_SIGINFO handler
When the SA_SIGINFO flag is specified in act.sa_flags, the signal handler address is passed via the act.sa_sigaction field. This handler takes three arguments, as follows:
void
handler(int sig, siginfo_t *info, void *ucontext)
{
    ...
}
The siginfo_t data type is a structure with the following fields:

siginfo_t {
    int      si_signo;     /* Signal number */
    int      si_errno;     /* An errno value */
    int      si_code;      /* Signal code */
    int      si_trapno;    /* Trap number that caused
                              hardware-generated signal
                              (unused on most architectures) */
    pid_t    si_pid;       /* Sending process ID */
    uid_t    si_uid;       /* Real user ID of sending process */
    int      si_status;    /* Exit value or signal */
    clock_t  si_utime;     /* User time consumed */
    clock_t  si_stime;     /* System time consumed */
    sigval_t si_value;     /* Signal value */
    int      si_int;       /* POSIX.1b signal */
    void    *si_ptr;       /* POSIX.1b signal */
    int      si_overrun;   /* Timer overrun count;
                              POSIX.1b timers */
    int      si_timerid;   /* Timer ID; POSIX.1b timers */
    void    *si_addr;      /* Memory location which caused fault */
    long     si_band;      /* Band event (was int in
                              glibc 2.3.2 and earlier) */
    int      si_fd;        /* File descriptor */
    short    si_addr_lsb;  /* Least significant bit of address
                              (since Linux 2.6.32) */
    void    *si_lower;     /* Lower bound when address violation
                              occurred (since Linux 3.19) */
    void    *si_upper;     /* Upper bound when address violation
                              occurred (since Linux 3.19) */
    int      si_pkey;      /* Protection key on PTE that caused
                              fault (since Linux 4.6) */
    void    *si_call_addr; /* Address of system call instruction
                              (since Linux 3.5) */
    int      si_syscall;   /* Number of attempted system call
                              (since Linux 3.5) */
    unsigned int si_arch;  /* Architecture of attempted system call
                              (since Linux 3.5) */
}
si_signo, si_errno and si_code are defined for all signals. (si_errno is generally unused on Linux.) The rest of the struct may be a union, so that one should read only the fields that are meaningful for the given signal:

*   Signale, die mit kill(2) und sigqueue(3) gesandt werden, füllen si_pid und si_uid aus. Zusätzlich füllen Signale, die mit sigqueue(3) gesandt werden, si_int und si_ptr mit dem vom Sender angegebenen Werte aus. Siehe sigqueue(3) für weitere Details.

*   Signals sent by POSIX.1b timers (since Linux 2.6) fill in si_overrun and si_timerid. The si_timerid field is an internal ID used by the kernel to identify the timer; it is not the same as the timer ID returned by timer_create(2). The si_overrun field is the timer overrun count; this is the same information as is obtained by a call to timer_getoverrun(2). These fields are nonstandard Linux extensions.

*   Signals sent for message queue notification (see the description of SIGEV_SIGNAL in mq_notify(3)) fill in si_int/si_ptr, with the sigev_value supplied to mq_notify(3); si_pid, with the process ID of the message sender; and si_uid, with the real user ID of the message sender.

*   SIGCHLD füllt si_pid, si_uid, si_status, si_utime und si_stime mit Informationen über das Kind aus. Das Feld si_pid ist die Prozess-ID des Kindes; si_uid ist die echte Benutzer-ID. Das Feld si_status enthält den Exit-Status des Kindes (falls si_code CLD_EXITED ist) oder die Signalnummer, die den Prozess zur Zustandsänderung veranlasst hat. si_utime und si_stime enthalten die vom Kindprozess verwandte Benutzer- und System-CPU-Zeit, diese Felder enthalten nicht die Zeit von Kindern, auf die gewartet wurde (anders als getrusage(2) und times(2)). In Kerneln bis 2.6 und seit 2.6.27 berichten diese Felder die CPU-Zeit in Einheiten von sysconf(_SC_CLK_TCK). In 2.6er Kerneln vor 2.6.27 wurden durch einen Fehler diese Felder in Einheiten der (konfigurierbaren) System-Jiffys berichtet (siehe time(7)).

*   SIGILL, SIGFPE, SIGSEGV, SIGBUS, and SIGTRAP fill in si_addr with the address of the fault. On some architectures, these signals also fill in the si_trapno field. Some suberrors of SIGBUS, in particular BUS_MCEERR_AO and BUS_MCEERR_AR, also fill in si_addr_lsb. This field indicates the least significant bit of the reported address and therefore the extent of the corruption. For example, if a full page was corrupted, si_addr_lsb contains log2(sysconf(_SC_PAGESIZE)). When SIGTRAP is delivered in response to a ptrace(2) event (PTRACE_EVENT_foo), si_addr is not populated, but si_pid and si_uid are populated with the respective process ID and user ID responsible for delivering the trap. In the case of seccomp(2), the tracee will be shown as delivering the event. BUS_MCEERR_* and si_addr_lsb are Linux-specific extensions. Der Unterfehler SEGV_BNDERR von SIGSEGV belegt si_lower und si_upper. Der Unterfehler SEGV_PKUERR von SIGSEGV belegt si_pkey.

*   SIGIO/SIGPOLL (die zwei Namen sind unter Linux synonym) füllen si_band und si_fd aus. Das Ereignis si_band ist eine Bitmaske, die die gleichen Werte enthält, die auch durch poll(2) in das Feld revents eingetragen werden. Das Feld si_fd zeigt den Dateideskriptor an, für den ein E/A-Ereignis aufgetreten ist. Für weitere Details lesen Sie die Beschreibung von F_SETSIG in fcntl(2).

*   SIGSYS, erstellt (seit Linux 3.5) wenn ein Seccomp-Filter SECCOMP_RET_TRAP zurückliefert, füllt si_call_addr, si_syscall, si_arch, si_errno und andere Felder wie in seccomp(2) beschrieben aus.

si_code ist ein Wert (keine Bitmaske), der angibt, warum dieses Signal gesendet wurde. Für ein ptrace(2)-Ereignis wird si_code SIGTRAP enthalten und das Ptrace-Ereignis im hohen Byte enthalten.
    (SIGTRAP | PTRACE_EVENT_foo << 8).
Für ein reguläres Signal zeigt die folgende Liste die Werte, die in si_code für jedes Signal gelegt werden können, zusammen mit den Gründen für die Erstellung des Signals.

    SI_USER
        kill(2)

    SI_KERNEL
        Vom Kernel geschickt

    SI_QUEUE
        sigqueue(3)

    SI_TIMER
        POSIX timer expired.

    SI_MESGQ (seit Linux 2.6.6)
        POSIX message queue state changed; see mq_notify(3).

    SI_ASYNCIO
        AIO abgeschlossen

    SI_SIGIO
        Queued SIGIO (only in kernels up to Linux 2.2; from Linux 2.4 onward SIGIO/SIGPOLL fills in si_code as described below).

    SI_TKILL (seit Linux 2.4.19)
        tkill(2) oder tgkill(2)

Die folgenden Werte können in si_code für ein Signal SIGILL gesetzt werden:

    ILL_ILLOPC
        Ungültiger Opcode

    ILL_ILLOPN
        Ungültiger Operand

    ILL_ILLADR
        Ungültiger Adressierungsmodus

    ILL_ILLTRP
        Illegal trap.

    ILL_PRVOPC
        Privilegierter Opcode

    ILL_PRVREG
        Privilegiertes Register

    ILL_COPROC
        Koprozessorfehler

    ILL_BADSTK
        Internal stack error.

Die folgenden Werte können in si_code für ein Signal SIGFPE gesetzt werden:

    FPE_INTDIV
        Ganzzahldivision durch Null

    FPE_INTOVF
        Ganzzahlüberlauf

    FPE_FLTDIV
        Fließkommadivision durch Null

    FPE_FLTOVF
        Fließkommazahlüberlauf

    FPE_FLTUND
        Fließkommazahlunterlauf

    FPE_FLTRES
        Ungenaues Fließkommaergebnis

    FPE_FLTINV
        Ungültige Fließkommazahlaktion

    FPE_FLTSUB
        Subscript out of range.

Die folgenden Werte können in si_code für ein Signal SIGSEGV gesetzt werden:

    SEGV_MAPERR
        Address not mapped to object.

    SEGV_ACCERR
        Invalid permissions for mapped object.

    SEGV_BNDERR (seit Linux 3.19)
        Failed address bound checks.

    SEGV_PKUERR (seit Linux 4.6)
        Access was denied by memory protection keys. See pkeys(7). The protection key which applied to this access is available via si_pkey.

Die folgenden Werte können in si_code für ein Signal SIGBUS gesetzt werden:

    BUS_ADRALN
        Invalid address alignment.

    BUS_ADRERR
        Nichtexistierende physische Adresse.

    BUS_OBJERR
        Objektspezifischer Hardwarefehler.

    BUS_MCEERR_AR (seit Linux 2.6.32)
        Hardware memory error consumed on a machine check; action required.

    BUS_MCEERR_AO (seit Linux 2.6.32)
        Hardware memory error detected in process but not consumed; action optional.

Die folgenden Werte können in si_code für ein Signal SIGTRAP gesetzt werden:

    TRAP_BRKPT
        Process breakpoint.

    TRAP_TRACE
        Process trace trap.

    TRAP_BRANCH (seit Linux 2.4)
        Process taken branch trap.

    TRAP_HWBKPT (seit Linux 2.4)
        Hardware breakpoint/watchpoint.

Die folgenden Werte können in si_code für ein Signal SIGCHLD gesetzt werden:

    CLD_EXITED
        Kind hat sich beendet.

    CLD_KILLED
        Kind wurde getötet

    CLD_DUMPED
        Kind wurde anormal beendet.

    CLD_TRAPPED
        Traced child has trapped.

    CLD_STOPPED
        Kind wurde gestoppt.

    CLD_CONTINUED (seit Linux 2.6.9)
        Gestopptes Kind hat fortgefahren.

Die folgenden Werte können in si_code für ein Signal SIGIOSIGPOLL gesetzt werden:

    POLL_IN
        Dateneingabe verfügbar

    POLL_OUT
        Ausgabepuffer verfügbar

    POLL_MSG
        Eingabenachricht verfügbar

    POLL_ERR
        E/A-Fehler (engl. I/O).

    POLL_PRI
        Eingabe hoher Priorität verfügbar

    POLL_HUP
        Gerät abgetrennt

Die folgenden Werte können in si_code für ein Signal SIGSYS gesetzt werden:

    SYS_SECCOMP (seit Linux 3.5)
        Ausgelöst durch eine seccomp(2)-Filterregel.

RÜCKGABEWERT
sigaction() gibt bei Erfolg Null zurück. Bei einem Fehler wird -1 zurückgegeben und errno entsprechend gesetzt.

FEHLER

EFAULT
    act oder oldact zeigt aus dem vom Prozess adressierbaren Adressraum heraus.

EINVAL
    Ein ungültiges Signal wurde angegeben. Dieser Fehler wird auch ausgelöst, wenn versucht wird, die Aktion für SIGKILL oder SIGSTOP zu ändern, da diese nicht abgefangen oder ignoriert werden können.

KONFORM ZU
POSIX.1-2001, POSIX.1-2008, SVr4.

ANMERKUNGEN
A child created via fork(2) inherits a copy of its parent's signal dispositions. During an execve(2), the dispositions of handled signals are reset to the default; the dispositions of ignored signals are left unchanged. Laut POSIX ist das Verhalten eines Prozesses undefiniert, nachdem es ein Signal SIGFPE, SIGILL oder SIGSEGV ignoriert hat, das nicht von kill(2) oder raise(3) erstellt wurde. Ganzzahldivision durch Null hat ein undefiniertes Ergebnis. Auf einigen Architekturen wird dies ein Signal SIGFPE hervorrufen. (Auch kann die Division der negativsten Ganzzahl durch -1 SIGFPE hervorrufen.) Wird dieses Signal ignoriert, kann eine Endlosschleife auftreten.

POSIX.1-1990 verbot das Setzen der Aktion für SIGCHLD bis SIG_IGN. POSIX.1-2001 und neuer erlauben diese Möglichkeit, so dass das Ignorieren von SIGCHLD zur Vermeidung von Zombies verwandt werden kann (siehe wait(2)). Allerdings unterscheiden sich die historischen BSD- und System-V-Verhalten für das Ingorieren von SIGCHLD, so dass die einzige komplett portable Methode, um sicherzustellen, dass beendete Kinder nicht Zombies werden, das Fangen des Signals SIGCHLD und das Durchführen eines wait(2) oder ähnlichem ist.

POSIX.1-1990 spezifizierte nur SA_NOCLDSTOP. POSIX.1-2001 fügte SA_NOCLDSTOP, SA_NOCLDWAIT, SA_NODEFER, SA_ONSTACK, SA_RESETHAND, SA_RESTART und SA_SIGINFO hinzu. Benutzung letzterer Werte in sa_flags könnte in Anwendungen, die für ältere UNIX-Implementierungen gedacht sind, weniger portabel sein.

Der Schalter SA_RESETHAND ist zu dem SVr4-Schalter mit dem gleichen Namen kompatibel.

Der Schalter SA_NODEFER ist mit dem SVr4-Schalter des gleichen Namens unter Kerneln 1.3.9 und neuer kompatibel. Unter älteren Kerneln erlaubte die Linux-Implementierung nicht das Empfangen irgendeines Signals, nicht nur desjenigen, das installiert wurde (was effektiv die Einstellungen sa_mask außer Kraft setzt).

Wird sigaction mit Null als zweitem Argument aufgerufen, kann der augenblickliche Signalhandler abgefragt werden. Die Funktion kann auch dazu benutzt werden, die Gültigkeit eines Signales für die aktuelle Maschine zu überprüfen, indem sie mit Null als zweitem und drittem Argument aufgerufen wird.

Es ist nicht möglich, SIGKILL oder SIGSTOP zu blockieren (indem Sie in sa_mask festgelegt werden). Derartige Versuche werden ohne Rückmeldung ignoriert.

Siehe sigsetops(3) für detaillierte Informationen über die Manipulation von Signalgruppen.

See signal-safety(7) for a list of the async-signal-safe functions that can be safely called inside from inside a signal handler.

  Unterschiede C-Bibliothek/Kernel
The glibc wrapper function for sigaction() gives an error (EINVAL) on attempts to change the disposition of the two real-time signals used internally by the NPTL threading implementation. See nptl(7) for details. Der ursprüngliche Linux-Systemaufruf hieß sigaction(). Mit dem Hinzufügen von Echtzeitsignalen in Linux 2.2 passte der mit einer festen Größe versehene 32-Bit-Typ sigset_t nicht mehr für den Zweck. Daher wurde ein neuer Systemaufruf rt_sigaction() mit einem vergrößerten Typ sigset_t hinzugefügt. Der neue Systemaufruf akzeptiert ein viertes Argument size_t sigsetsize, das die Größe in Bytes der Signalgruppe in act.sa_mask und oldact.sa_mask festlegt. Dieses Argument muss derzeit den Wert sizeof(sigset_t) enthalten oder der Fehler EINVAL tritt auf. Die Glibc-Wrapper-Funktion sigaction() versteckt diese Details und ruft rt_sigaction() transparent auf, wenn der Kernel ihn bereitstellt.

  Undokumentiert
Vor der Einführung von SA_SIGINFO war es auch möglich, einige zusätzliche Informationen durch die Verwendung eines sa_handler mit einem zweiten Argument des Typs struct sigcontext zu erhalten. Siehe die relevanten Kernelquellen für Details. Diese Verwendung ist jetzt veraltet.

FEHLER
In Kerneln bis einschließlich 2.6.13 verhinderte die Festlegung von SA_NODEFER in sa_flags nicht nur die Ausblendung des ausgelieferten Signals während der Ausführung des Handlers sondern auch der in sa_mask festgelegten Signale. Dieser Fehler wurde in Kernel 2.6.14 behoben.

BEISPIEL
Siehe mprotect(2)

SIEHE AUCH
kill(1), kill(2), pause(2), restart_syscall(2), seccomp(2), sigaltstack(2), signal(2), signalfd(2), sigpending(2), sigprocmask(2), sigreturn(2), sigsuspend(2), wait(2), killpg(3), raise(3), siginterrupt(3), sigqueue(3), sigsetops(3), sigvec(3), core(5), signal(7)

KOLOPHON
This page is part of release 4.11 of the Linux man-pages project. A description of the project, information about reporting bugs, and the latest version of this page, can be found at https://www.kernel.org/doc/man-pages/.

ÜBERSETZUNG
Die deutsche Übersetzung dieser Handbuchseite wurde von René Tschirley <gremlin@cs.tu-berlin.de>, Martin Eberhard Schauer <Martin.E.Schauer@gmx.de> und Helge Kreutzmann <debian@helgefjell.de> erstellt. Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezüglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen. Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an <debian-l10n-german@lists.debian.org>.