home | help 
KQUEUE(2)		       System Calls Manual		       KQUEUE(2)

NAME
     kqueue, kevent -- kernel event notification mechanism

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <sys/types.h>
     #include <sys/event.h>

     int
     kqueue(void);

     int
     kevent(int kq, const struct kevent *changelist, int nchanges,
	 struct kevent *eventlist, int nevents, const struct timespec *timeout);

DESCRIPTION
     kqueue() provides a generic method of notifying the user when an event hap-
     pens  or  a condition holds, based on the results of small pieces of kernel
     code termed filters.  A kevent is identified by the (ident,  filter)  pair;
     there may only be one unique kevent per kqueue.

     The  filter  is executed upon the initial registration of a kevent in order
     to detect whether a preexisting condition is present, and is also	executed
     whenever  an  event  is passed to the filter for evaluation.  If the filter
     determines that the condition should be reported, then the kevent is placed
     on the kqueue for the user to retrieve.

     The filter is also run when the user attempts to retrieve the  kevent  from
     the  kqueue.  If the filter indicates that the condition that triggered the
     event no longer holds, the kevent is removed from the kqueue and is not re-
     turned.

     Multiple events which trigger the filter do not result in multiple  kevents
     being  placed  on the kqueue; instead, the filter will aggregate the events
     into a single struct kevent.  Calling close() on a file descriptor will re-
     move any kevents that reference the descriptor.

     kqueue() creates a new kernel event queue and returns  a  descriptor.   The
     queue  is	not  inherited	by  a  child  created with fork(2).  However, if
     rfork(2) is called with the RFFDG flag, the  descriptor  table  is  shared,
     which will allow sharing of the kqueue between two processes.

     kevent()  is used to register events with the queue, and return any pending
     events to the user.  changelist is a pointer to an array of  kevent  struc-
     tures,  as  defined  in <event.h>.  All changes contained in the changelist
     are applied before any pending events are read from  the  queue.	nchanges
     gives the size of changelist.  eventlist is a pointer to an array of kevent
     structures.   nevents  determines	the  size of eventlist.  If timeout is a
     non-NULL pointer, it specifies a maximum interval to wait for an event.  If
     timeout is a NULL pointer, kevent() waits indefinitely.  To effect a  poll,
     the timeout argument should be non-NULL, pointing to a zero-valued timespec
     structure.

     The kevent structure is defined as:

     struct kevent {
	     uintptr_t ident;	     /* identifier for this event */
	     short     filter;	     /* filter for event */
	     u_short   flags;	     /* action flags for kqueue */
	     u_int     fflags;	     /* filter flag value */
	     intptr_t  data;	     /* filter data value */
	     void      *udata;	     /* opaque user data identifier */
     };

     The fields of struct kevent are:

     ident	Value  used to identify this event.  The exact interpretation is
		determined by the attached filter, but often is a file	descrip-
		tor.

     filter	Identifies  the  kernel  filter used to process this event.  The
		pre-defined system filters are described below.

     flags	Actions to perform on the event.

     fflags	Filter-specific flags.

     data	Filter-specific data value.

     udata	Opaque user-defined value passed through the kernel unchanged.

     The flags field can contain the following values:

     EV_ADD	    Adds the event to the kqueue.  Re-adding an  existing  event
		    will  modify  the  parameters of the original event, and not
		    result in a duplicate entry.  Adding an event  automatically
		    enables it, unless overridden by the EV_DISABLE flag.

     EV_ENABLE	    Permit kevent() to return the event if it is triggered.

     EV_DISABLE     Disable  the event so kevent() will not return it.	The fil-
		    ter itself is not disabled.

     EV_DELETE	    Removes the event from the kqueue.	 Events  which	are  at-
		    tached  to file descriptors are automatically deleted on the
		    last close of the descriptor.

     EV_ONESHOT     Causes the event to return only the first occurrence of  the
		    filter  being triggered.  After the user retrieves the event
		    from the kqueue, it is deleted.

     EV_CLEAR	    After the event is retrieved by the user, its state  is  re-
		    set.   This is useful for filters which report state transi-
		    tions instead of the current state.  Note that some  filters
		    may automatically set this flag internally.

     EV_EOF	    Filters  may  set  this flag to indicate filter-specific EOF
		    condition.

     EV_ERROR	    See "RETURN VALUES" below.

     The predefined system filters are listed below.  Arguments may be passed to
     and from the filter via the fflags and data fields in the kevent structure.

     EVFILT_READ
	     Takes a descriptor as the identifier, and returns whenever there is
	     data available to read.  The behavior of  the  filter  is	slightly
	     different depending on the descriptor type.

	     Sockets
		     Sockets  which  have previously been passed to listen() re-
		     turn when there is an incoming  connection  pending.   data
		     contains the size of the listen backlog.

		     Other  socket  descriptors  return when there is data to be
		     read, subject  to	the  SO_RCVLOWAT  value  of  the  socket
		     buffer.   data  contains  the number of bytes in the socket
		     buffer.

		     If the read direction of the socket has shutdown, then  the
		     filter  also  sets EV_EOF in flags.  It is possible for EOF
		     to be returned (indicating the connection	is  gone)  while
		     there is still data pending in the socket buffer.

	     Vnodes  Returns  when  the  file pointer is not at the end of file.
		     data contains the offset from current position  to  end  of
		     file, and may be negative.

	     Fifos, Pipes
		     Returns  when  the there is data to read; data contains the
		     number of bytes available.

		     When the last  writer  disconnects,  the  filter  will  set
		     EV_EOF  in  flags.   This	may  be  cleared  by  passing in
		     EV_CLEAR, at which point the filter will resume waiting for
		     data to become available before returning.

     EVFILT_WRITE
	     Takes a descriptor as the identifier, and returns	whenever  it  is
	     possible to write to the descriptor.  For sockets, pipes and fifos,
	     data  will  contain  the  amount  of  space  remaining in the write
	     buffer.  The filter will set EV_EOF when  the  reader  disconnects,
	     and  for  the  fifo  case,  this may be cleared by use of EV_CLEAR.
	     Note that this filter is not supported for vnodes.

     EVFILT_AIO
	     A kevent structure is initialized, with ident  containing	the  de-
	     scriptor  of  the kqueue that the event should be attached to.  The
	     address  of  the  kevent  structure   is	then   placed	in   the
	     aio_lio_opcode  field of the AIO request, and the aio_* function is
	     then called.  The event  will  be	registered  with  the  specified
	     kqueue,  and the ident argument set to the struct aiocb returned by
	     the aio_* function.  The filter returns under the	same  conditions
	     as aio_error.

	     NOTE: this interface is unstable and subject to change.

     EVFILT_VNODE
	     Takes  a  file descriptor as the identifier and the events to watch
	     for in fflags, and returns when one or more of the requested events
	     occurs on the descriptor.	The events to monitor are:

	     NOTE_DELETE    unlink() was called on the file  referenced  by  the
			    descriptor.

	     NOTE_WRITE     A  write  occurred on the file referenced by the de-
			    scriptor.

	     NOTE_EXTEND    The file referenced by the descriptor was extended.

	     NOTE_ATTRIB    The file referenced by the descriptor  had	its  at-
			    tributes changed.

	     NOTE_LINK	    The link count on the file changed.

	     NOTE_RENAME    The file referenced by the descriptor was renamed.

	     On return, fflags contains the events which triggered the filter.

     EVFILT_PROC
	     Takes the process ID to monitor as the identifier and the events to
	     watch  for  in fflags, and returns when the process performs one or
	     more of the requested events.  If a process can  normally	see  an-
	     other process, it can attach an event to it.  The events to monitor
	     are:

	     NOTE_EXIT	      The process has exited.

	     NOTE_FORK	      The process has called fork().

	     NOTE_EXEC	      The  process  has  executed  a new process via ex-
			      ecve(2) or similar call.

	     NOTE_TRACK       Follow a process across fork() calls.  The  parent
			      process  will  return  with  NOTE_TRACK set in the
			      fflags field, while the child process will  return
			      with  NOTE_CHILD	set in fflags and the parent PID
			      in data.

	     NOTE_TRACKERR    This flag is returned if the system was unable  to
			      attach  an event to the child process, usually due
			      to resource limitations.

	     On return, fflags contains the events which triggered the filter.

     EVFILT_SIGNAL
	     Takes the signal number to monitor as the	identifier  and  returns
	     when  the	given signal is delivered to the process.  This coexists
	     with the signal() and  sigaction()  facilities,  and  has	a  lower
	     precedence.   The filter will record all attempts to deliver a sig-
	     nal to a process, even if the signal has been  marked  as	SIG_IGN.
	     Event notification happens after normal signal delivery processing.
	     data  returns the number of times the signal has occurred since the
	     last call to kqueue().  This filter automatically sets the EV_CLEAR
	     flag internally.

RETURN VALUES
     kqueue() creates a new kernel event queue and returns  a  file  descriptor.
     If there was an error creating the kernel event queue, a value of -1 is re-
     turned and errno set.

     kevent()  returns	the  number of events placed in the eventlist, up to the
     value given by nevents.  If an error occurs while processing an element  of
     the  changelist  and  there is enough room in the eventlist, then the event
     will be placed in the eventlist with EV_ERROR set in flags and  the  system
     error  in	data.	Otherwise, -1 will be returned, and errno will be set to
     indicate the error condition.  If the time limit expires, then kevent() re-
     turns 0.

ERRORS
     The kqueue() function fails if:

     [ENOMEM]		The kernel failed to allocate enough memory for the ker-
			nel queue.

     [EMFILE]		The per-process descriptor table is full.

     [ENFILE]		The system file table is full.

     The kevent() function fails if:

     [EACCESS]		The process does not have permission to register a  fil-
			ter.

     [EFAULT]		There  was an error reading or writing the kevent struc-
			ture.

     [EBADF]		The specified descriptor is invalid.

     [EINTR]		A signal was delivered before the  timeout  expired  and
			before any events were placed on the kqueue for return.

     [EINVAL]		The specified time limit or filter is invalid.

     [ENOMEM]		No memory was available to register the event.

     [ESRCH]		The specified process to attach to does not exist.

SEE ALSO
     aio_error(2),  aio_read(2),  aio_return(2),  poll(2),  read(2),  select(2),
     sigaction(2), write(2), signal(3)

HISTORY
     The kqueue() and kevent() functions first appeared in FreeBSD 4.1.

AUTHORS
     The kqueue() system and this manual page were  written  by  Jonathan  Lemon
     <jlemon@FreeBSD.org>.

BUGS
     It  is  currently not possible to watch a vnode(9) that resides on anything
     but a UFS file system.

FreeBSD 4.1			 April 14, 2000 		       KQUEUE(2)
home | help