Scroll to navigation

SIGACTION(2) Podręcznik programisty Linuksa SIGACTION(2)

NAZWA

sigaction, rt_sigaction - bada i zmienia akcję sygnału

SKŁADNIA

#include <signal.h>
int sigaction(int signum, const struct sigaction *act,
              struct sigaction *oldact);

Wymagane ustawienia makr biblioteki glibc (patrz feature_test_macros(7)):

sigaction(): _POSIX_C_SOURCE

siginfo_t: _POSIX_C_SOURCE >= 199309L

OPIS

Wywołanie systemowe sigaction() jest używane do zmieniania akcji, którą odbiera proces po odebraniu określonego sygnału. (Wprowadzenie do sygnałów można znaleźć w podręczniku signals(7)).

signum określa sygnał i może być dowolnym prawidłowym sygnałem poza SIGKILL i SIGSTOP.

Jeśli act nie jest NULL-em, to nowa akcja dla sygnału signum jest brana z act. Jeśli oldact też jest różny od NULL, to poprzednia akcja jest w nim zachowywana.

Struktura sigaction jest zdefiniowana jako:


struct sigaction {

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

Na niektórych architekturach część tej struktury może być unią: nie należy ustawiać jednocześnie pól sa_handler oraz sa_sigaction.

The sa_restorer field is not intended for application use. (POSIX does not specify a sa_restorer field.) Some further details of the purpose of this field can be found in sigreturn(2).

sa_handler specifies the action to be associated with signum and is be one of the following:

  • SIG_DFL for the default action.
  • SIG_IGN to ignore this signal.
  • A pointer to a signal handling function. This function receives the signal number as its only 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 three arguments, as described below.

sa_mask określa maskę sygnałów, które powinny być blokowane (tj. dodane do maski sygnałów wątku, z którego sygnał został wywołany) podczas wywoływania funkcji obsługi sygnałów. Dodatkowo, sygnał, który wywołał tę funkcję obsługi będzie zablokowany, chyba że użyto flagi SA_NODEFER.

sa_flags podaje zbiór flag, które modyfikują zachowanie procesu obsługi sygnałów. Jest to zbiór wartości połączonych bitowym OR:

Jeśli signum jest równe SIGCHLD, to nie są odbierane powiadomienia o zatrzymaniu procesu-dziecka (np. gdy dziecko otrzyma jeden z SIGSTOP, SIGTSTP, SIGTTIN lub SIGTTOU) ani o jego wznowieniu (np. po otrzymaniu SIGCONT) (patrz wait(2)). Flaga ta ma znaczenie tylko w przypadku ustawiania funkcji obsługi sygnału SIGCHLD.
Jeśli signum jest równy SIGCHLD, to dzieci po swoim zakończeniu nie zostaną przekształcone w zombie. Patrz także waitpid(2). Znacznik ma znaczenie tylko ustanawiania funkcji obsługującej sygnał SIGCHLD lub podczas ustawiania tego sygnału na SIG_DLF.
Jeśli znacznik SA_NOCLDWAIT jest ustawiony podczas ustanawiania funkcji obsługującej sygnał SIGCHLD, to POSIX.1 nie określa, czy sygnał SIGCHLD po zakończeniu procesu potomnego. Pod Linuksem sygnał SIGCHLD jest w takim przypadku generowany; niektóre inne systemy go nie generują.
Do not add the signal to the thread's signal mask while the handler is executing, unless the signal is specified in act.sa_mask. Consequently, a further instance of the signal may be delivered to the thread while it is executing the handler. This flag is meaningful only when establishing a signal handler.
SA_NOMASK is an obsolete, nonstandard synonym for this flag.
Wywołuje funkcję obsługi sygnału, używając alternatywnego stosu ustawionego przez sigaltstack(2). Jeżeli ten alternatywny stos nie jest dostępny, zostanie użyty stos domyślny. Flaga ta ma znaczenie tylko w przypadku ustanawiania funkcji obsługi sygnału.
Restore the signal action to the default upon entry to the signal handler. This flag is meaningful only when establishing a signal handler.
SA_ONESHOT is an obsolete, nonstandard synonym for this flag.
Dostarcza zachowania kompatybilnego z semantyką sygnałową BSD, czyniąc pewne wywołania systemowe odtwarzalnymi przez sygnały. Flaga ta ma znaczenie podczas ustanawiania procedury obsługi sygnału. Informacje na temat odtwarzania wywołań systemowych można znaleźć w podręczniku signal(7).
Nie jest przeznaczone do bezpośredniego stosowania. Flaga ta jest używana przez biblioteki C do wskazania, że pole sa_restorer zawiera adres "trampoliny sygnału" Więcej szczegółów w podręczniku sigreturn(2).
Funkcja obsługi sygnałów pobiera trzy argumenty, a nie jeden. W typ przypadku zamiast ustawiać sa_handler należy ustawić sa_sigaction. Flaga ta ma znaczenie tylko w przypadku ustanawiania funkcji obsługi sygnału.

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)
{

... }

These three arguments are as follows

The number of the signal that caused invocation of the handler.
A pointer to a siginfo_t, which is a structure containing further information about the signal, as described below.
This is a pointer to a ucontext_t structure, cast to void *. The structure pointed to by this field contains signal context information that was saved on the user-space stack by the kernel; for details, see sigreturn(2). Further information about the ucontext_t structure can be found in getcontext(3) and signal(7). Commonly, the handler function doesn't make any use of the third argument.

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 */
union sigval 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 i si_code są zdefiniowane dla wszystkich sygnałów. (Generalnie si_errno nie jest używane pod Linuksem). Pozostałe pola struktury mogą być unią; powinno się odczytywać tylko pola istotne dla danego sygnału.

  • Sygnały wysłane przez kill(2) i sigqueue(3) mają wypełnione pola si_pid oraz si_uid. Dodatkowo sygnały wysłane przez sigqueue(3) mają w polach si_int i si_ptr ustawione wartości podane przez nadawcę sygnału; szczegóły opisano w sigqueue(3).
  • Sygnały wysłane przez timery POSIX.1b (od Linuksa 2.6) mają uzupełnione pola si_overrun i si_timerid. Pole si_timerid zawiera wewnętrzny identyfikator używany przez jądro do identyfikacji timera; nie jest to ten sam identyfikator, który zwraca timer_create(2). Pole si_overrun zawiera informację o tym, ile razy timer się przepełnił — jest to ta sama informacja, którą zwraca timer_getoverrun(2). Pola te są niestandardowymi rozszerzeniami Linuksa.
  • Sygnały wysłane w celu notyfikacji kolejki komunikatów (patrz opis SIGEV_SIGNAL in mq_notify(3)) mają pola si_int/si_ptr wypełnione wartościami sigev_value przekazanymi do mq_notify(3); ponadto si_pid zawiera identyfikator procesu wysyłającego sygnał, a si_uid rzeczywisty identyfikator użytkownika - nadawcy sygnału.
  • SIGCHLD ustawia pola si_pid, si_uid, si_status, si_utime i si_stime, dostarczając informacji o procesie potomnym. Pole si_pid jest identyfikatorem potomka, si_uid jest identyfikatorem rzeczywistego użytkownika procesu potomnego. Pole si_status zawiera kod zakończenia potomka (jeśli si_code jest równe CLD_EXITED) lub numer sygnału, który spowodował zmianę stanu. Pola si_utime i si_stime zawierają czasy spędzone przez potomka w przestrzeniach użytkownika i systemowej; w przeciwieństwie do getrusage(2) i times(2), pola te nie zawierają czasów oczekiwania na potomków. W jądrach wcześniejszych niż 2.6, a także w 2.6.27 i nowszych, pola zawierają czas CPU w jednostkach sysconf(_SC_CLK_TCK). W jądrach 2.6 wcześniejszych niż 2.6.27 z powodu błędu używane były (konfigurowalne) jednostki jiffy (patrz time(7)).
  • SIGILL, SIGFPE, SIGSEGV, SIGBUS oraz SIGTRAP wypełniają pole si_addr, ustawiając w nim adres błędu. Na niektórych architekturach sygnały wypełniają także pole si_trapno.
Niektóre błędy pochodne SIGBUS, w szczególności BUS_MCEERR_AO i BUS_MCEERR_AR ustawiają także si_addr_lsb. Pole to oznacza najmniej znaczący bit adresu, zatem i rozmiary uszkodzeń. Na przykład jeśli cała strona została uszkodzona, si_addr_lsb zawierać będzie log2(sysconf(_SC_PAGESIZE)). Gdy jako odpowiedź na zdarzenie ptrace(2) (PTRACE_EVENT_foo) zostanie dostarczony SIGTRAP, pole si_addr nie jest wypełnione, natomiast pola si_pid i si_uid są wypełnione identyfikatorami odpowiednio procesu i użytkownika odpowiedzialnego za dostarczenie pułapki. W przypadku seccomp(2) jako dostarczenie zdarzenia pokazany zostanie zrzut. BUS_MCERR_* i si_addr_lsb są rozszerzeniami specyficznymi dla Linuksa.
SEGV_BNDERR będący podbłędem SIGSEGV wypełnia pola si_lower i si_upper.
SEGV_PKUERR będący podbłędem SIGSEGV wypełnia pole si_pkey.
  • SIGIO/SIGPOLL (te dwie nazwy są synonimami pod Linuksem) wypełnia pola si_band i si_fd. Zdarzenie si_band jest maską bitową zawierającą te same wartości, które poll(2) umieszcza w polu revents. Pole si_fd oznacza deskryptor pliku, na którym wystąpiło dane zdarzenie wejścia/wyjścia; więcej szczegółów w opisie F_SETSIG w podręczniku fcntl(2).
  • SIGSYS, generowany (od Linuksa 3.5) gdy filtr seccomp zwróci SECCOMP_RET_TRAP, wypełnia pola si_call_addr, si_syscall, si_arch, si_errno i inne, zgodnie z opisem z seccomp(2).

The si_code field

The si_code field inside the siginfo_t argument that is passed to a SA_SIGINFO signal handler is a value (not a bit mask) indicating why this signal was sent. For a ptrace(2) event, si_code will contain SIGTRAP and have the ptrace event in the high byte:


(SIGTRAP | PTRACE_EVENT_foo << 8).

For a non-ptrace(2) event, the values that can appear in si_code are described in the remainder of this section. Since glibc 2.20, the definitions of most of these symbols are obtained from <signal.h> by defining feature test macros (before including any header file) as follows:

  • _XOPEN_SOURCE with the value 500 or greater;
  • _XOPEN_SOURCE and _XOPEN_SOURCE_EXTENDED; or
  • _POSIX_C_SOURCE with the value 200809L or greater.

For the TRAP_* constants, the symbol definitions are provided only in the first two cases. Before glibc 2.20, no feature test macros were required to obtain these symbols.

For a regular signal, the following list shows the values which can be placed in si_code for any signal, along with the reason that the signal was generated.

kill(2).
Wysyłany przez jądro.
sigqueue(3).
Wygaśnięcie timera POSIX.
Zmiana stanu kolejki komunikatów POSIX; patrz mq_notify(3)
Ukończenie asynchronicznej operacji wejścia/wyjścia.
Kolejkowany SIGIO (tylko w jądrach do wersji 2.2 Linuksa; od Linuksa 2.4 SIGIO/SIGPOLL wypełniają si_code, tak jak to opisano poniżej).
tkill(2) lub tgkill(2)

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGILL:

Niedozwolony kod operacji.
Niedozwolony operand.
Niedozwolony tryb adresowania.
Niedozwolona pułapka.
Uprzywilejowany kod operacji.
Uprzywilejowany rejestr.
Błąd koprocesora.
Wewnętrzny błąd stosu.

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGFPE:

Dzielenie wartości całkowitej przez zero.
Przepełnienie liczby całkowitej.
Dzielenie wartości zmiennoprzecinkowej przez zero.
Przekroczenie zakresu operacji zmiennoprzecinkowej.
Przekroczenie (w dół) zakresu operacji zmiennoprzecinkowej.
Niedokładny wynik operacji zmiennoprzecinkowej.
Niepoprawna operacja zmiennoprzecinkowa.
Dolny indeks poza zakresem.

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGSEGV:

Adres niemapowany do obiektu.
Niepoprawne uprawnienia mapowanego obiektu.
Niepowodzenie sprawdzenia przypisania adresu.
Access was denied by memory protection keys. See pkeys(7). The protection key which applied to this access is available via si_pkey.

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGBUS:

Niepoprawne wyrównanie adresu.
Nieistniejący adres fizyczny.
Błąd sprzętowy specyficzny dla obiektu.
Sprzętowy błąd pamięci podczas sprawdzania komputera; wymagane podjęcie akcji.
Wykryto sprzętowy błąd pamięci w procesie; opcjonalne podjęcie akcji.

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGTRAP:

Punkt wstrzymania procesu.
Śledzony proces złapany.
Śledzone rozgałęzienie procesu złapane.
Pułapka sprzętowa.

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGCHLD:

Proces potomny się zakończył.
Proces potomny został zabity.
Potomek zakończył się w nieprawidłowy sposób.
Śledzony potomek został złapany.
Proces potomny został zatrzymany.
Zatrzymany proces potomny został wznowiony.

Następujące wartości mogą zostać umieszczone w si_code sygnału SIGIO/SIGPOLL:

Dostępne dane na wejściu.
Dostępne bufory wyjścia.
Dostępna wiadomość na wejściu.
Błąd wejścia/wyjścia.
Dostępne wejście o wysokim priorytecie.
Urządzenie odłączone.

Następująca wartość może zostać umieszczona w si_code sygnału SIGSYS:

Wyzwolone przez regułę filtra seccomp(2).

WARTOŚĆ ZWRACANA

sigaction() w przypadku powodzenia zwraca 0. W razie wystąpienia błędu zwracane jest -1 i ustawiana jest zmienna errno wskazując na błąd.

BŁĘDY

act lub oldact wskazują na pamięć poza przestrzenią adresową procesu.
Podano nieprawidłowy sygnał. Będzie to też generowane w przypadku próby zmienienia akcji dla sygnałów SIGKILL lub SIGSTOP, które nie mogą być przechwycone lub zignorowane.

ZGODNE Z

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

UWAGI

Dziecko utworzone przez fork(2) dziedziczy kopię ustawień sygnałów od swojego rodzica. Podczas wywołania execve(2) przywracane są wartości domyślne ustawień, z wyjątkiem ustawienia ignorowania sygnału, które nie jest zmieniane.

Zgodnie z POSIX, zachowanie procesu po zignorowaniu sygnału SIGFPE, SIGILL lub SIGSEGV, niewygenerowanego przez kill(2) lub raise(3), jest niezdefiniowane. Dzielenie liczby całkowitej przez zero ma wynik niezdefiniowany. Na niektórych architekturach generuje sygnał SIGFPE (Także dzielenie najmniejszej ujemnej liczby całkowitej przez -1 może wygenerować SIGFPE). Ignorowanie go może prowadzić do nieskończonej pętli.

POSIX.1-1990 zabraniał ustawiania akcji dla SIGCHLD na SIG_IGN. POSIX.1-2001 i późniejsze pozwalają na to, tak że można użyć ignorowania SIGCHLD, żeby zapobiec tworzeniu procesów-duchów (patrz wait(2)). Niemniej jednak, historyczne zachowanie systemów BSD i System V w zakresie ignorowania SIGCHLD jest inne, tak więc jedyną całkowicie przenośną metodą zapewnienia, że potomek po zakończeniu nie zostanie procesem-duchem jest przechwytywanie sygnału SIGCHLD i wywołanie funkcji wait(2) lub podobnej.

POSIX.1-1990 określał tylko SA_NOCLDSTOP. W POSIX.1-2001 dodano SA_NOCLDSTOP, SA_NOCLDWAIT, SA_NODEFER, SA_ONSTACK, SA_RESETHAND, SA_RESTART oraz SA_SIGINFO. Używanie tych nowych wartości sa_flags może być mniej przenośne w aplikacjach przewidzianych do użycia w starszych implementacjach Uniksa.

Flaga SA_RESETHAND jest kompatybilna z flagą w SVr4 o tej samej nazwie.

The SA_NODEFER flag is compatible with the SVr4 flag of the same name under kernels 1.3.9 and later. On older kernels the Linux implementation allowed the receipt of any signal, not just the one we are installing (effectively overriding any sa_mask settings).

sigaction() może być wywoływany z drugim argumentem o wartości NULL, powodując w ten sposób zapytanie o bieżący handler sygnału. Może go też użyć do sprawdzenia, czy dany sygnał jest prawidłowy na obecnej maszynie. W tym celu należy zarówno drugi, jak i trzeci argument ustawić na NULL.

Nie można zablokować sygnałów SIGKILL lub SIGSTOP (przez podanie ich w sa_mask). Próby takie zostaną zignorowane.

Zobacz sigsetops(3) dla szczegółów o operacjach na zbiorach sygnałów.

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

Różnice biblioteki C/jądra

Funkcja opakowująca glibc dla sigaction() daje błąd (EINVAL) przy próbie zmiany dyspozycji dwóch sygnałów czasu rzeczywistego używanych wewnętrznie przez implementację wątkową NPTL. Więcej szczegółów w podręczniku nptl(7).

On architectures where the signal trampoline resides in the C library, the glibc wrapper function for sigaction() places the address of the trampoline code in the act.sa_restorer field and sets the SA_RESTORER flag in the act.sa_flags field. See sigreturn(2).

Oryginalne linuksowe wywołanie systemowe nazywało się sigaction(). Jednak po pojawieniu się sygnałów czasu rzeczywistego w Linuksie 2.2, 32-bitowy typ sigset_t o stałym rozmiarze obsługiwany przez to wywołanie przestał dobrze służyć swemu zadaniu. Z tego powodu, w celu obsługi powiększonego typu sigset_t dodano nowe wywołanie systemowe rt_sigaction(). Nowe wywołanie przyjmuje czwarty argument size_t sigsetsize, który określa rozmiar w bajtach zestawu sygnałów w act.sa_mask i oldact.sa_mask. Argument ten obecnie musi mieć wartość sizeof(sigset_t) (albo nastąpi błąd EINVAL). Opakowanie glibc sigaction() ukrywa te detale przed nami, po cichu wywołując rt_sigaction() jeśli udostępnia je jądro.

Nieudokumentowane

Before the introduction of SA_SIGINFO, it was also possible to get some additional information about the signal. This was done by providing an sa_handler signal handler with a second argument of type struct sigcontext, which is the same structure as the one that is passed in the uc_mcontext field of the ucontext structure that is passed (via a pointer) in the third argument of the sa_sigaction handler. See the relevant Linux kernel sources for details. This use is obsolete now.

BŁĘDY

When delivering a signal with a SA_SIGINFO handler, the kernel does not always provide meaningful values for all of the fields of the siginfo_t that are relevant for that signal.

W jądrze 2.6.13 i wcześniejszych podanie SA_NODEFER w sa_flags zapobiegało maskowaniu nie tylko dostarczonego sygnału podczas wykonywania procedury obsługi sygnału, ale także sygnałów określonych w sa_mask. Ten błąd został poprawiony w 2.6.14.

PRZYKŁADY

Patrz mprotect(2).

ZOBACZ TAKŻE

kill(1), kill(2), pause(2), pidfd_send_signal(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)

O STRONIE

Angielska wersja tej strony pochodzi z wydania 5.10 projektu Linux man-pages. Opis projektu, informacje dotyczące zgłaszania błędów oraz najnowszą wersję oryginału można znaleźć pod adresem https://www.kernel.org/doc/man-pages/.

TŁUMACZENIE

Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Przemek Borys <pborys@dione.ids.pl>, Robert Luberda <robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>

Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać zapoznając się z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.

Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres manpages-pl-list@lists.sourceforge.net.

21 grudnia 2020 r. Linux