SIGNAL(9)              NetBSD Kernel Developer's Manual              SIGNAL(9)

NAME
     signal, siginit, sigactsinit, sigactsunshare, sigactsfree, execsigs,
     sigaction1, sigprocmask1, sigpending1, sigsuspend1, sigaltstack1,
     gsignal, pgsignal, psignal, sched_psignal, issignal, postsig, killproc,
     sigexit, sigmasked, trapsignal, sendsig, sigcode, sigtramp -- software
     signal facilities

SYNOPSIS
     #include <sys/signal.h>
     #include <sys/signalvar.h>

     void
     siginit(struct proc *p);

     void
     sigactsinit(struct proc *np, struct proc *pp, int share);

     void
     sigactsunshare(struct proc *p);

     void
     sigactsfree(struct proc *p);

     void
     execsigs(struct proc *p);

     int
     sigaction1(struct proc *p, int signum, const struct sigaction *nsa,
         struct sigaction *osa, void *tramp, int vers);

     int
     sigprocmask1(struct proc *p, int how, const sigset_t *nss,
         sigset_t *oss);

     void
     sigpending1(struct proc *p, sigset_t *ss);

     int
     sigsuspend1(struct proc *p, const sigset_t *ss);

     int
     sigaltstack1(struct proc *p, const struct sigaltstack *nss,
         struct sigaltstack *oss);

     void
     gsignal(int pgid, int signum);

     void
     kgsignal(int pgid, ksiginfo_t *ks, void *data);

     void
     pgsignal(struct pgrp *pgrp, int signum, int checkctty);

     void
     kpgsignal(struct pgrp *pgrp, ksiginfo_t *ks, void *data, int checkctty);

     void
     psignal(struct proc *p, int signum);

     void
     kpsignal(struct proc *p, ksiginfo_t *ks, void *data);

     void
     sched_psignal(struct proc *p, int signum);

     int
     issignal(struct lwp *l);

     void
     postsig(int signum);

     void
     killproc(struct proc *p, const char *why);

     void
     sigexit(struct proc *p, int signum);

     int
     sigmasked(struct proc *p, int signum);

     void
     trapsignal(struct proc *p, const ksiginfo_t *ks);

     void
     sendsig(const ksiginfo_t *ks, const sigset_t *mask);

DESCRIPTION
     The system defines a set of signals that may be delivered to a process.
     These functions implement the kernel portion of the signal facility.

     Signal numbers used throughout the kernel signal facilities should always
     be within the range of [1-NSIG].

     Most of the kernel's signal infrastructure is implemented in machine-
     independent code.  Machine-dependent code provides support for invoking a
     process's signal handler, restoring context when the signal handler
     returns, generating signals when hardware traps occur, triggering the
     delivery of signals when a process is about to return from the kernel to
     userspace.

     The signal state for a process is contained in struct sigctx.  This
     includes the list of signals with delivery pending, information about the
     signal handler stack, the signal mask, and the address of the signal
     trampoline.

     The registered signal handlers for a process are recorded in struct
     sigacts.  This structure may be shared by multiple processes.

     The kernel's signal facilities are implemented by the following func-
     tions:

     void siginit(struct proc *p)

            This function initializes the signal state of proc0 to the system
            default.  This signal state is then inherited by init(8) when it
            is started by the kernel.

     void sigactsinit(struct proc *np, struct proc *pp, int share)

            This function creates an initial struct sigacts for the process
            np.  If the share argument is non-zero, then np shares the struct
            sigacts with the process pp.  Otherwise, np receives a new struct
            sigacts which is copied from pp if non-NULL.

     void sigactsunshare(struct proc *p)

            This function causes the process p to no longer share its struct
            sigacts The current state of the signal actions is maintained in
            the new copy.

     void sigactsfree(struct proc *p)

            This function decrements the reference count on the struct sigacts
            of process p.  If the reference count reaches zero, the struct
            sigacts is freed.

     void execsigs(struct proc *p)

            This function is used to reset the signal state of the process p
            to the system defaults when the process execs a new program image.

     int sigaction1(struct proc *p, int signum, const struct sigaction *nsa,
            struct sigaction *osa, void *tramp, int vers)

            This function implements the sigaction(2) system call.  The tramp
            and vers arguments provide support for userspace signal trampo-
            lines.  Trampoline version 0 is reserved for the legacy kernel-
            provided signal trampoline; tramp must be NULL in this case.  Oth-
            erwise, vers specifies the ABI of the trampoline specified by
            tramp.  The signal trampoline ABI is machine-dependent, and must
            be coordinated with the sendsig() function.

     int sigprocmask1(struct proc *p, int how, const sigset_t *nss, sigset_t
            *oss)

            This function implements the sigprocmask(2) system call.

     void sigpending1(struct proc *p, sigset_t *ss)

            This function implements the sigpending(2) system call.

     int sigsuspend1(struct proc *p, const sigset_t *ss)

            This function implements the sigsuspend(2) system call.

     int sigaltstack1(struct proc *p, const struct sigaltstack *nss, struct
            sigaltstack *oss)

            This function implements the sigaltstack(2) system call.

     void gsignal(int pgid, int signum)

            This is a wrapper function for kgsignal() which is described
            below.

     void kgsignal(int pgid, ksiginfo_t *ks, void *data)

            Schedule the signal ks->ksi_signo to be delivered to all members
            of the process group specified by pgid.  The data argument and the
            complete signal scheduling semantics are described in the
            kpsignal() function below.  below for a complete description of
            the signal scheduling semantics.

     void pgsignal(struct pgrp *pgrp, int signum, int checkctty)

            This is a wrapper function for kpgsignal() which is described
            below.

     void kpgsignal(struct pgrp *pgrp, ksiginfo_t *ks, void *data, int
            checkctty)

            Schedule the signal ks->ksi_signo to be delivered to all members
            of the process group pgrp.  If checkctty is non-zero, the signal
            is only sent to processes which have a controlling terminal.  The
            data argument and the complete signal scheduling semantics are
            described in the kpsignal() function below.

     void trapsignal(struct proc *p, const ksiginfo_t *ks)

            Sends the signal ks->ksi_signo caused by a hardware trap to the
            process p.  This function is meant to be called by machine-depen-
            dent trap handling code, through the p->p_emul->e_trapsignal func-
            tion pointer because some emulations define their own trapsignal
            functions that remap the signal information to what the emulation
            expects.

     void psignal(struct proc *p, int signum)

            This is a wrapper function for kpsignal() which is described
            below.

     void kpsignal(struct proc *p, ksiginfo_t *ks, void *data)

            Schedule the signal ks->ksi_signo to be delivered to the process
            p.  The data argument, if not NULL, points to the file descriptor
            data that caused the signal to be generated in the SIGIO case.

            With a few exceptions noted below, the target process signal dis-
            position is updated and is marked as runnable, so further handling
            of the signal is done in the context of the target process after a
            context switch; see issignal() below.  Note that kpsignal() does
            not by itself cause a context switch to happen.

            The target process is not marked as runnable in the following
            cases:

                  +   The target process is sleeping uninterruptibly.  The
                      signal will be noticed when the process returns from the
                      system call or trap.

                  +   The target process is currently ignoring the signal.

                  +   If a stop signal is sent to a sleeping process that
                      takes the default action (see sigaction(2)), the process
                      is stopped without awakening it.

                  +   SIGCONT restarts a stopped process (or puts them back to
                      sleep) regardless of the signal action (e.g., blocked or
                      ignored).

            If the target process is being traced, kpsignal() behaves as if
            the target process were taking the default action for signum.
            This allows the tracing process to be notified of the signal.

     void sched_psignal(struct proc *p, int signum)

            An alternate version of kpsignal() which is intended for use by
            code which holds the scheduler lock.

     int issignal(struct lwp *l)

            This function determines which signal, if any, is to be posted to
            the process p.  A signal is to be posted if:

                  +   The signal has a handler provided by the program image.

                  +   The signal should cause the process to dump core and/or
                      terminate.

                  +   The signal should interrupt the current system call.

            Signals which cause the process to be stopped are handled within
            issignal() directly.

            issignal() should be called by machine-dependent code when return-
            ing to userspace from a system call or other trap or interrupt by
            using the following code:

                  while (signum = CURSIG(curproc))
                          postsig(signum);

     void postsig(int signum)

            The postsig() function is used to invoke the action for the signal
            signum in the current process.  If the default action of a signal
            is to terminate the process, and the signal does not have a regis-
            tered handler, the process exits using sigexit(), dumping a core
            image if necessary.

     void killproc(struct proc *p, const char *why)

            This function sends a SIGKILL signal to the specified process.
            The message provided by why is sent to the system log and is also
            displayed on the process's controlling terminal.

     void sigexit(struct proc *p, int signum)

            This function forces the process p to exit with the signal signum,
            generating a core file if appropriate.  No checks are made for
            masked or caught signals; the process always exits.

     int sigmasked(struct proc *p, int signum)

            This function returns non-zero if the signal specified by signum
            is ignored or masked for process p.

     void sendsig(const ksiginfo_t *ks, const sigset_t *mask)

            This function is provided by machine-dependent code, and is used
            to invoke a signal handler for the current process.  sendsig()
            must prepare the registers and stack of the current process to
            invoke the signal handler stored in the process's struct sigacts.
            This may include switching to an alternate signal stack specified
            by the process.  The previous register, stack, and signal state
            are stored in a ucontext_t, which is then copied out to the user's
            stack.

            The registers and stack must be set up to invoke the signal han-
            dler as follows:

                  (*handler)(int signum, siginfo_t *info, void *ctx)

            where signum is the signal number, info contains additional signal
            specific information when SA_SIGINFO is specified when setting up
            the signal handler.  ctx is the pointer to ucontext_t on the
            user's stack.  The registers and stack must also arrange for the
            signal handler to return to the signal trampoline.  The trampoline
            is then used to return to the code which was executing when the
            signal was delivered using the setcontext(2) system call.

            For performance reasons, it is recommended that sendsig() arrange
            for the signal handler to be invoked directly on architectures
            where it is convenient to do so.  In this case, the trampoline is
            used only for the signal return path.  If it is not feasible to
            directly invoke the signal handler, the trampoline is also used to
            invoke the handler, performing any final set up that was not pos-
            sible for sendsig() to perform.

            sendsig() must invoke the signal trampoline with the correct ABI.
            The ABI of the signal trampoline is specified on a per-signal
            basis in the sigacts() structure for the process.  Trampoline ver-
            sion 0 is reserved for the legacy kernel-provided, on-stack signal
            trampoline.  All other trampoline versions indicate a specific
            trampoline ABI.  This ABI is coordinated with machine-dependent
            code in the system C library.

   SIGNAL TRAMPOLINE
     The signal trampoline is a special piece of code which provides support
     for invoking the signal handlers for a process.  The trampoline is used
     to return from the signal handler back to the code which was executing
     when the signal was delivered, and is also used to invoke the handler
     itself on architectures where it is not feasible to have the kernel
     invoke the handler directly.

     In traditional UNIX systems, the signal trampoline, also referred to as
     the ``sigcode'', is provided by the kernel and copied to the top of the
     user's stack when a new process is created or a new program image is
     exec'd.  Starting in NetBSD 2.0, the signal trampoline is provided by the
     system C library.  This allows for more flexibility when the signal
     facility is extended, makes dealing with signals easier in debuggers,
     such as gdb(1), and may also enhance system security by allowing the ker-
     nel to disallow execution of code on the stack.

     The signal trampoline is specified on a per-signal basis.  The correct
     trampoline is selected automatically by the C library when a signal han-
     dler is registered by a process.

     Signal trampolines have a special naming convention which enables debug-
     gers to determine the characteristics of the signal handler and its argu-
     ments.  Trampoline functions are named like so:

           __sigtramp_<flavor>_<version>

     where:

     <flavor>   The flavor of the signal handler.  The following flavors are
                valid:

                sigcontext    Specifies a traditional BSD-style (deprecated)
                              signal handler with the following signature:

                              void (*handler)(int signum,
                                      int code,
                                      struct sigcontext *scp);

                siginfo       Specifies a POSIX-style signal handler with the
                              following signature:

                              void (*handler)(int signum,
                                      siginfo_t *si,
                                      void *uc);

                              Note: sigcontext style signal handlers are dep-
                              recated, and retained only for compatibility
                              with older binaries.

     <version>  Specifies the ABI version of the signal trampoline.  The tram-
                poline ABI is coordinated with the machine-dependent kernel
                sendsig() function.  The trampoline version needs to be unique
                even across different trampoline flavors, in order to simplify
                trampoline selection in the kernel.

     The following is an example if a signal trampoline name which indicates
     that the trampoline is used for traditional BSD-style signal handlers and
     implements version 1 of the signal trampoline ABI:

           __sigtramp_sigcontext_1

     The current signal trampoline is:

           __sigtramp_siginfo_2

SEE ALSO
     sigaction(2), signal(7), condvar(9)

NetBSD 5.0.1                   December 20, 2005                  NetBSD 5.0.1

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen