Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NOTIFY(3)		   Library Functions Manual		     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	excep-
       tion.  A	note may also be posted	by another process via On Unix,	 notes
       are implemented as signals.

       When a note is received,	the action taken depends on the	note.  See 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 re-
       ceived.	The argument to	notify replaces	the previous handler, if  any.
       An  argument  of	zero cancels a previous	handler, restoring the default
       action.	A system call leaves the handler registered in both the	parent
       and the child; 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	exter-
       nally-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  in-
       complete	system call, that call returns an error	(with error string in-
       terrupted) after	the process resumes.  A	notification handler can  also
       jump  out  to an	environment set	up with	setjmp using the notejmp func-
       tion (see

       Unix provides a fixed set of notes (typically there are 32) called sig-
       nals.   It  also	allows a process to block certain notes	from being de-
       livered (see and	to ignore certain notes	by setting the	signal	hander
       to  the special value SIG_IGN (see 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 un-
       til 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	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 registra-
       tion.   A  handler must return a	non-zero number	if the note was	recog-
       nized (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  re-
       turns  non-zero.	 Then noted is called with argument NCONT.  If no reg-
       istered 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	previ-
       ously enabled (notified).

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

	  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 operating system.

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

SEE ALSO
       notejmp in

								     NOTIFY(3)

NAME | SYNOPSIS | DESCRIPTION | SOURCE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=notify&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help