NOTIFY(3)                                               NOTIFY(3)

     NAME
          notify, noted, atnotify, noteenable, notedisable, notifyon,
          notifyoff - handle asynchronous process notification

     SYNOPSIS
          #include <u.h>
          #include <libc.h>

          int notify(void (*f)(void*, char*))

          int noted(int v)

          int atnotify(int (*f)(void*, char*), int in)

          int noteenable(char *msg)
          int notedisable(char *msg)

          int notifyon(char *msg)
          int notifyoff(char *msg)

     DESCRIPTION
          When a process raises an exceptional condition such as
          dividing by zero or writing on a closed pipe, a note is
          posted to communicate the exception.  A note may also be
          posted by another process via postnote(3). On Unix, notes
          are implemented as signals.

          When a note is received, the action taken depends on the
          note.  See signal(7) for the full description of the
          defaults.

          The default actions may be overridden.  The notify function
          registers a notification handler to be called within the
          process when a note is received.  The argument to notify
          replaces the previous handler, if any.  An argument of zero
          cancels a previous handler, restoring the default action.  A
          fork(2) system call leaves the handler registered in both
          the parent and the child; exec(3) restores the default
          behavior.  Handlers may not perform floating point opera-
          tions.

          After a note is posted, the handler is called with two argu-
          ments: the first is unimplemented and should not be used (on
          Plan 9 it is a Ureg structure giving the current values of
          registers); the second is a pointer to the note itself, a
          null-terminated string.

          A notification handler must finish either by exiting the
          program or by calling noted; if the handler returns the
          behavior is undefined and probably erroneous.  Until the

     NOTIFY(3)                                               NOTIFY(3)

          program calls noted, any further externally-generated notes
          (e.g., hangup or alarm) will be held off, and any further
          notes generated by erroneous behavior by the program (such
          as divide by zero) will kill the program.  The argument to
          noted defines the action to take: NDFLT instructs the system
          to perform the default action as if the handler had never
          been registered; NCONT instructs the system to resume the
          process at the point it was notified.  In neither case does
          noted return to the handler.  If the note interrupted an
          incomplete system call, that call returns an error (with
          error string interrupted) after the process resumes.  A
          notification handler can also jump out to an environment set
          up with setjmp using the notejmp function (see setjmp(3)).

          Unix provides a fixed set of notes (typically there are 32)
          called signals. It also allows a process to block certain
          notes from being delivered (see sigprocmask(2)) and to
          ignore certain notes by setting the signal hander to the
          special value SIG_IGN (see signal(2)). Noteenable and
          notedisable enable or disable receipt of a particular note
          by changing the current process's blocked signal mask.
          Receipt of a disabled note will be postponed until it is
          reenabled.  Notifyon and notifyoff enable or disable whether
          the notification handler is called upon receipt of the note;
          if the handler is not called, the note is discarded.

          Regardless of the origin of the note or the presence of a
          handler, if the process is being debugged (see ptrace(2))
          the arrival of a note puts the process in the Stopped state
          and awakens the debugger.

          Rather than using the system calls notify and noted, most
          programs should use atnotify to register notification han-
          dlers.  The parameter in is non-zero to register the func-
          tion f, and zero to cancel registration.  A handler must
          return a non-zero number if the note was recognized (and
          resolved); otherwise it must return zero.  When the system
          posts a note to the process, each handler registered with
          atnotify is called with arguments as described above until
          one of the handlers returns non-zero.  Then noted is called
          with argument NCONT.  If no registered function returns
          non-zero, atnotify calls noted with argument NDFLT.

          Notify and atnotify return -1 on error and 0 on success.
          Noted returns -1 on error; successful calls to noted do not
          return.  Noteenable and notedisable (notitfyon and
          notifyoff) return -1 on error, 0 if the note was previously
          disabled (not notified), and 1 if the note was previously
          enabled (notified).

          The set of notes a process may receive is system-dependent,
          but there is a common set that includes:

     NOTIFY(3)                                               NOTIFY(3)

             Note                         Meaning                       Unix signal
             interrupt                    user interrupt (DEL key)      SIGINTR
             hangup                       I/O connection closed         SIGHUP
             alarm                        alarm expired                 SIGLARM
             quit                         quit from keyboard            SIGQUIT
             kill                         process requested to exit     SIGTERM
             sys: kill                    process forced to exit        SIGKILL
             sys: bus error               bus error                     SIGBUS
             sys: segmentation violation  segmentation violation        SIGSEGV
             sys: write on closed pipe    write on closed pipe          SIGPIPE
             sys: child                   child wait status change      SIGCHLD

          See /src/lib9/await.c (sic) for the full list.

          The notes prefixed sys: are usually generated by the operat-
          ing system.

     SOURCE
          /src/lib9/notify.c
          /src/lib9/atnotify.c

     SEE ALSO
          intro(3), notejmp in setjmp(3)