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  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 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 fork(2) system call leaves the handler  registered  in  both
       the  parent and the child; exec(3) restores the default behavior.  Han-
       dlers 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 setjmp(3)).

       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 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 dis-
       abled note will be postponed until it is	reenabled.  Notifyon and noti-
       fyoff enable or disable whether the notification	handler	is called upon
       receipt of the note; if the handler is not called,  the	note  is  dis-
       carded.

       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 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 /usr/local/plan9/src/lib9/await.c (sic) for the full	list.

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

SOURCE
       /usr/local/plan9/src/lib9/notify.c
       /usr/local/plan9/src/lib9/atnotify.c

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

								     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