# Module Std.Signal

    module Signal: Signal

    type t

    include Comparable.S

    include Hashable.S

    include Stringable.S

    val equal : t -> t -> bool

    val of_system_int : int -> t

`of_system_int` and `to_system_int` return and take respectively a signal number corresponding to those in the system's /usr/include/bits/signum.h (or equivalent). It is not guaranteed that these numbers are portable across any given pair of systems -- although some are defined as standard by POSIX.

    val to_system_int : t -> int

    val of_caml_int : int -> t

`of_caml_int` constructs a Signal.t given an O'Caml internal signal number. This is only for the use of the Core_unix module.

    val to_caml_int : t -> int

    val to_string : t -> string

`to_string t` returns a human-readable name: "sigabrt", "sigalrm", ...

    type sys_behavior = [ `Continue | `Dump_core | `Ignore | `Stop | `Terminate ]

The default behaviour of the system if these signals trickle to the top level of a program. See include/linux/kernel.h in the Linux kernel source tree (not the file /usr/include/linux/kernel.h).

    val default_sys_behavior : t -> sys_behavior

`default_sys_behavior t` Query the default system behavior for a signal.

    val handle_default : t -> unit

`handle_default t` is `set t `Default`.

    val ignore : t -> unit

`ignore t` is `set t `Ignore`.

    type pid_spec = [ `Group of Core_kernel.Std.Pid.t | `My_group | `Pid of Core_kernel.Std.Pid.t ]

    val send : t -> pid_spec -> [ `No_such_process | `Ok ]

`send signal pid_spec` sends `signal` to the processes specified by `pid_spec`.

`send_i` is like `send`, except that it silently returns if the specified processes don't exist.

`send_exn` is like `send`, except that it raises if the specified processes don't exist.

All of `send`, `send_i`, and `send_exn` raise if you don't have permission to send the signal to the specified processes or if `signal` is unknown.

    val send_i : t -> pid_spec -> unit

    val send_exn : t -> pid_spec -> unit

    val can_send_to : Core_kernel.Std.Pid.t -> bool

`can_send_to pid` returns true if `pid` is running and the current process has permission to send it signals.

    type sigprocmask_command = [ `Block | `Set | `Unblock ]

    val sigprocmask : sigprocmask_command -> t list -> t list

`sigprocmask cmd sigs` changes the set of blocked signals. If `cmd` is ``Set`, blocked signals are set to those in the list `sigs`. If `cmd` is ``Block`, the signals in `sigs` are added to the set of blocked signals. If `cmd` is ``Unblock`, the signals in `sigs` are removed from the set of blocked signals. `sigprocmask` returns the set of previously blocked signals.

    val sigpending : unit -> t list

`sigpending ()` returns the set of blocked signals that are currently pending.

    val sigsuspend : t list -> unit

`sigsuspend sigs` atomically sets the blocked signals to `sigs` and waits for a non-ignored, non-blocked signal to be delivered. On return, the blocked signals are reset to their initial value.
Specific signals, along with their default behavior and meaning.

    val abrt : t

`Dump_core` Abnormal termination

    val alrm : t

`Terminate` Timeout

    val chld : t

`Ignore` Child process terminated

    val cont : t

`Continue` Continue

    val fpe : t

`Dump_core` Arithmetic exception

    val hup : t

`Terminate` Hangup on controlling terminal

    val ill : t

`Dump_core` Invalid hardware instruction

    val int : t

`Terminate` Interactive interrupt (ctrl-C)

    val kill : t

`Terminate` Termination (cannot be ignored)

    val pipe : t

`Terminate` Broken pipe

    val prof : t

`Terminate` Profiling interrupt

    val quit : t

`Dump_core` Interactive termination

    val segv : t

`Dump_core` Invalid memory reference

    val stop : t

`Stop` Stop

    val term : t

`Terminate` Termination

    val tstp : t

`Stop` Interactive stop

    val ttin : t

`Stop` Terminal read from background process

    val ttou : t

`Stop` Terminal write from background process

    val usr1 : t

`Terminate` Application-defined signal 1

    val usr2 : t

`Terminate` Application-defined signal 2

    val vtalrm : t

`Terminate` Timeout in virtual time

    val zero : t

`Ignore` No-op; can be used to test whether the target process exists and the current process has permission to signal it

    module Expert: sig .. end

The `Expert` module contains functions that novice users should avoid, due to their complexity.

    val t_of_sexp : Sexplib.Sexp.t -> t

    val sexp_of_t : t -> Sexplib.Sexp.t

    val bin_t : t Core_kernel.Std.Bin_prot.Type_class.t

    val bin_read_t : t Core_kernel.Std.Bin_prot.Read.reader

    val __bin_read_t__ : (int -> t) Core_kernel.Std.Bin_prot.Read.reader

    val bin_reader_t : t Core_kernel.Std.Bin_prot.Type_class.reader

    val bin_size_t : t Core_kernel.Std.Bin_prot.Size.sizer

    val bin_write_t : t Core_kernel.Std.Bin_prot.Write.writer

    val bin_writer_t : t Core_kernel.Std.Bin_prot.Type_class.writer

`of_system_int` and `to_system_int` return and take respectively a signal number corresponding to those in the system's /usr/include/bits/signum.h (or equivalent). It is not guaranteed that these numbers are portable across any given pair of systems -- although some are defined as standard by POSIX.
`of_caml_int` constructs a Signal.t given an O'Caml internal signal number. This is only for the use of the Core_unix module.
`to_string t` returns a human-readable name: "sigabrt", "sigalrm", ...

    val sys_behavior_of_sexp : Sexplib.Sexp.t -> sys_behavior

The default behaviour of the system if these signals trickle to the top level of a program. See include/linux/kernel.h in the Linux kernel source tree (not the file /usr/include/linux/kernel.h).

    val __sys_behavior_of_sexp__ : Sexplib.Sexp.t -> sys_behavior

    val sexp_of_sys_behavior : sys_behavior -> Sexplib.Sexp.t

`default_sys_behavior t` Query the default system behavior for a signal.
`handle_default t` is `set t `Default`.
`ignore t` is `set t `Ignore`.
`send signal pid_spec` sends `signal` to the processes specified by `pid_spec`.

`send_i` is like `send`, except that it silently returns if the specified processes don't exist.

`send_exn` is like `send`, except that it raises if the specified processes don't exist.

All of `send`, `send_i`, and `send_exn` raise if you don't have permission to send the signal to the specified processes or if `signal` is unknown.
`can_send_to pid` returns true if `pid` is running and the current process has permission to send it signals.
`sigprocmask cmd sigs` changes the set of blocked signals. If `cmd` is ``Set`, blocked signals are set to those in the list `sigs`. If `cmd` is ``Block`, the signals in `sigs` are added to the set of blocked signals. If `cmd` is ``Unblock`, the signals in `sigs` are removed from the set of blocked signals. `sigprocmask` returns the set of previously blocked signals.
`sigpending ()` returns the set of blocked signals that are currently pending.
`sigsuspend sigs` atomically sets the blocked signals to `sigs` and waits for a non-ignored, non-blocked signal to be delivered. On return, the blocked signals are reset to their initial value.
Specific signals, along with their default behavior and meaning.
`Dump_core` Abnormal termination
`Terminate` Timeout
`Ignore` Child process terminated
`Continue` Continue
`Dump_core` Arithmetic exception
`Terminate` Hangup on controlling terminal
`Dump_core` Invalid hardware instruction
`Terminate` Interactive interrupt (ctrl-C)
`Terminate` Termination (cannot be ignored)
`Terminate` Broken pipe
`Terminate` Profiling interrupt
`Dump_core` Interactive termination
`Dump_core` Invalid memory reference
`Stop` Stop
`Terminate` Termination
`Stop` Interactive stop
`Stop` Terminal read from background process
`Stop` Terminal write from background process
`Terminate` Application-defined signal 1
`Terminate` Application-defined signal 2
`Terminate` Timeout in virtual time
`Ignore` No-op; can be used to test whether the target process exists and the current process has permission to signal it
The `Expert` module contains functions that novice users should avoid, due to their complexity.

An OCaml signal handler can run at any time, which introduces all the semantic complexities of multithreading. It is much easier to use Async's signal handling, see `Async_unix.Signal`, which does not involve multithreading, and runs user code as ordinary Async jobs. Also, beware that there can only be a single OCaml signal handler for any signal, so handling a signal with a `Core` signal handler will interfere if Async is attempting to handle the same signal.

All signal handler functions are called with `Exn.handle_uncaught_and_exit`, to prevent the signal handler from raising, because raising from a signal handler could raise to any allocation or GC point in any thread, which would be impossible to reason about.

If you do use `Core` signal handlers, you should strive to make the signal handler perform a simple idempotent action, like setting a ref.
`signal t` sets the behavior of the system on receipt of signal `t` and returns the behavior previously associated with `t`. If `t` is not available on your system, `signal` raises.
`set t b` is `ignore (signal t b)`
`handle t f` is `set t (`Handle f)`.