|  | 
 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 operations. 
    
    
    After a note is posted, the handler is called with two arguments:
    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 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 handlers. The parameter
    in is non-zero to register the function 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: See /usr/lib/plan9/src/lib9/await.c
    (sic) for the full list. 
    
    
    The notes prefixed sys: are usually generated by the operating
    system.|  |  |  | 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
 
 | 
 
 | 
 SOURCE     
 SEE ALSO    
 |  |