Signal control functions

Typedefs
typedef void(*	sigsafe_user_handler_t )(int, siginfo_t *, ucontext_t *, intptr_t)
	User-specified handler type.
Functions
int	sigsafe_install_handler (int signum, sigsafe_user_handler_t handler)
	Installs a safe signal handler.
int	sigsafe_install_tsd (intptr_t userdata, void(*destructor)(intptr_t))
	Installs thread-specific data.
intptr_t	sigsafe_clear_received (void)
	Clears the signal received flag for this thread.

---

Typedef Documentation

typedef void(* sigsafe_user_handler_t)(int, siginfo_t*, ucontext_t*, intptr_t)

User-specified handler type. Arguments: int signo: The signal number received. siginfo_t *si: The signal information as passed to a sigaction-style signal handler. ucontext_t *ctx: The machine context of the program when the signal was received. After the user-defined handler exits, the platform-specific handler will kick in. It will decide if it is currently executing in a "jump region" of a sigsafe system call and adjust the instruction pointer if so. While ctx is not marked const, you should be very cautious modifying it. Your code will be non-portable, and you may interfere with sigsafe's operation. In fact, normally you will not need to even read this parameter. intptr_t user_data. The data you passed to sigsafe_install_tsd() in this thread. Warning: This handler is executed asynchronously. You must take care to only call async signal-safe functions. In fact, the entire point of sigsafe is to allow you to do very little here and handle the rest in the main program. It's recommended that you only note details about the signal here, not take any action. Portability: Unfortunately, NetBSD does not support sigaction, as of the latest released version (1.6.2). Thus, it has a different signature: int signo int code - similar to si->si_code with the standard handler struct sigcontext *ctx - similar to the standard handler's ctx. intptr_t user_data Currently, you will need to use #ifdef SIGSAFE_NO_SIGINFO if you wish to support NetBSD. Future releases: I may change the API to have "simple" and "extended" versions of user handlers, so that simple ones do not need to worry about these platform differences. See also: sigsafe_install_handler Definition at line 102 of file sigsafe.h. Referenced by sigsafe_install_handler().

---

Function Documentation

intptr_t sigsafe_clear_received (  void   )

Clears the signal received flag for this thread. After calling this function, sigsafe system calls will not receive -EINTR due to signals received before this call. Precondition: sigsafe_install_tsd has been called in this thread. Returns: The user-specified data given when the TSD was installed for this thread. Note: Additional signals could arrive between a sigsafe sytem call returning -EINTR and the heart of this function; it will clear them all. If this is a concern for your application, use the userdata to track signals and check it after calling this function. Signals can also be received while you are reading the userdata. This can cause the usual problems like word tearing and stale data. If this is a concern, one approach would be to block signals with pthread_sigmask(2) while handling previous ones. (Though remember that some signal delivery mechanisms --- like child process events and interval timers --- simply do not deliver signals if all eligible threads have them masked.) Definition at line 169 of file sigsafe.c.

int sigsafe_install_handler (  int  signum, sigsafe_user_handler_t  handler )

Installs a safe signal handler. This installs a safe signal handler. It is global to the process. Note that nothing will happen on signal delivery if the thread in which it arrives has not called sigsafe_install_tsd. Parameters: signum  The signal number handler  An optional signal handler which will be run asynchronously. It will be passed the normal sigaction(2)-style signal information and the intptr_t supplied to sigsafe_install_tsd. The usual async signal-safety rules apply; it is strongly suggested that this handler do nothing more than copy whatever data from the siginfo_t* structure to the user-supplied location. This is allowed since sigsafe itself only notes that a signal has arrived, not even the signal number. May be NULL, in which case sigsafe simply notes that a signal was received. Returns: 0 on success; -EINVAL where sigaction(2) would return -1 and set errno to EINVAL. Note: Call this function at most once for each signal number. Definition at line 107 of file sigsafe.c. References sigsafe_user_handler_t.

int sigsafe_install_tsd (  intptr_t  userdata, void(*  destructor)(intptr_t) )

Installs thread-specific data. Before this is called for a given thread, "safe" signals delivered to that thread will be silently ignored. If you are concerned about signals delivered at thread startup, ensure threads start with blocked signals. Note: This function still must be called for single-threaded compiles. Precondition: This function has not previously been called in this thread. Parameters: userdata  Thread-specific user data which will be delivered to your handler routine with every signal. destructor  An optional destructor for userdata, to be run at thread exit. It is unspecified whether this runs for the final thread to exit - TSD destructors are used to clean up memory, and that happens on process exit automatically. Some pthread implementations vary. In single-threaded compiles, this will be ignored. Definition at line 139 of file sigsafe.c.

---