NOTIFY(3)

💖 NOTIFY(3) — Library Functions Manual but make it group-chat 💖

okay so bestie, welcome to the notify(3) page from the Library Functions Manual 🦋 this is the whole async process notification situation and we're gonna get through it together, no cap. It's giving low-level signal realness but make it readable.

💖 NAME 💖

notify, noted, atnotify, noteenable, notedisable, notifyon, notifyoff — the whole squad handles 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 🌸

🫶 the basics, bestie

When a process raises an exceptional condition — like 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.

🌀 handler rules — do not just return, omg

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 💀 like bestie do not do that.

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 signals, masks, and the vibe check

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 handler 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 👀

🧚 atnotify — the one most programs should use

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.

🎀 return-value tea

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 common note list, periodt

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

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

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

The notes prefixed sys: are usually generated by the operating system.

🧚 SOURCE 🧚

• /src/lib9/notify.c
• /src/lib9/atnotify.c

🔥 SEE ALSO 🔥

• intro(3)
• notejmp in setjmp(3)

---

mwah 💋 this page's footer/source-version says NOTIFY(3), and there's literally no date line, so we are not inventing one — byeee 🫶✨