.\" $Id: eventlib.mdoc,v 1.1.2.1.10.1 2004/03/09 08:33:43 marka Exp $.\".\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC").\" Copyright (c) 1995-1999 by Internet Software Consortium.\".\" Permission to use, copy, modify, and distribute this software for any.\" purpose with or without fee is hereby granted, provided that the above.\" copyright notice and this permission notice appear in all copies..\".\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE..\".Dd March 6, 1996.Dt EVENTLIB 3.Os BSD 4.Sh NAME.Nm evConnFunc ,.Nm evFileFunc ,.Nm evStreamFunc ,.Nm evTimerFunc ,.Nm evWaitFunc ,.Nm evCreate ,.Nm evDestroy ,.Nm evGetNext ,.Nm evDispatch ,.Nm evDrop ,.Nm evMainLoop ,.Nm evConsTime ,.Nm evTimeSpec ,.Nm evTimeVal ,.Nm evAddTime ,.Nm evSubTime ,.Nm evCmpTime ,.Nm evNowTime ,.Nm evUTCTime ,.Nm evLastEventTime ,.Nm evSetTimer ,.Nm evResetTimer ,.Nm evConfigTimer ,.Nm evClearTimer ,.Nm evSetIdleTimer ,.Nm evTouchIdleTimer ,.Nm evClearIdleTimer ,.Nm evWaitFor ,.Nm evDo ,.Nm evUnwait ,.Nm evDefer ,.Nm evSelectFD ,.Nm evDeselectFD ,.Nm evWrite ,.Nm evRead ,.Nm evCancelRW ,.Nm evTimeRW ,.Nm evUntimeRW ,.Nm evListen ,.Nm evConnect ,.Nm evCancelConn ,.Nm evHold ,.Nm evUnhold ,.Nm evTryAccept ,.Nm evConsIovec ,.Nm evSetDebug ,.Nm evPrintf ,.Nm evInitID ,.Nm evTestID ,.Nm evGetOption ,.Nm evSetOption.Nd event handling library.Sh SYNOPSIS.Fd #include <isc/eventlib.h>.Ft typedef void.Fn \*(lp*evConnFunc\*(rp "evContext ctx" "void *uap" "int fd" \"const void *la" "int lalen" "const void *ra" "int ralen".Ft typedef void.Fn \*(lp*evTimerFunc\*(rp "evContext ctx" "void *uap" \"struct timespec due" "struct timespec inter".Ft typedef void.Fn \*(lp*evFileFunc\*(rp "evContext ctx" "void *uap" "int fd" "int eventmask".Ft typedef void.Fn \*(lp*evStreamFunc\*(rp "evContext ctx" "void *uap" "int fd" "int bytes".Ft typedef void.Fn \*(lp*evWaitFunc\*(rp "evContext ctx" "void *uap" "const void *tag".Ft int.Fn evCreate "evContext *ctx".Ft int.Fn evDestroy "evContext ctx".Ft int.Fn evGetNext "evContext ctx" "evEvent *ev" "int options".Ft int.Fn evDispatch "evContext ctx" "evEvent ev".Ft void.Fn evDrop "evContext ctx" "evEvent ev".Ft int.Fn evMainLoop "evContext ctx".Ft struct timespec.Fn evConsTime "int sec" "int usec".Ft struct timespec.Fn evTimeSpec "struct timeval tv".Ft struct timeval.Fn evTimeVal "struct timespec ts".Ft struct timespec.Fn evAddTime "struct timespec addend1" "struct timespec addend2".Ft struct timespec.Fn evSubTime "struct timespec minuend" "struct timespec subtrahend".Ft struct timespec.Fn evCmpTime "struct timespec a" "struct timespec b".Ft struct timespec.Fn evNowTime "void".Ft struct timespec.Fn evUTCTime "void".Ft struct timespec.Fn evLastEventTime "evContext opaqueCtx".Ft int.Fn evSetTimer "evContext ctx" "evTimerFunc func" "void *uap" \"struct timespec due" "struct timespec inter" "evTimerID *id".Ft int.Fn evResetTimer "evContext ctx" "evTimerID id" "evTimerFunc func" \"void *uap" "struct timespec due" "struct timespec inter".Ft int.Fn evConfigTimer "evContext ctx" "evTimerID id" "const char *param" \"int value".Ft int.Fn evClearTimer "evContext ctx" "evTimerID id".Ft int.Fn evSetIdleTimer "evContext opaqueCtx" "evTimerFunc func" "void *uap" \"struct timespec max_idle" "evTimerID *opaqueID".Ft int .Fn evTouchIdleTimer "evContext opaqueCtx" "evTimerID id".Ft int .Fn evResetIdleTimer "evContext opaqueCtx" "evTimerID id" "evTimerFunc func" \"void *uap" "struct timespec max_idle".Ft int.Fn evClearIdleTimer "evContext opaqueCtx" "evTimerID id".Ft int.Fn evWaitFor "evContext opaqueCtx" "const void *tag" \"evWaitFunc func" "void *uap" "evWaitID *id".Ft int.Fn evDo "evContext opaqueCtx" "const void *tag".Ft int.Fn evUnwait "evContext opaqueCtx" "evWaitID id".Ft int.Fn evDefer "evContext opaqueCtx" "evWaitFunc func" "void *uap".Ft int.Fn evSelectFD "evContext ctx" "int fd" "int eventmask" \"evFileFunc func" "void *uap" "evFileID *id".Ft int.Fn evDeselectFD "evContext ctx" "evFileID id".Ft struct iovec.Fn evConsIovec "void *buf" "size_t cnt".Ft int.Fn evWrite "evContext ctx" "int fd" "const struct iovec *iov" "int cnt" \"evStreamFunc func" "void *uap" "evStreamID *id".Ft int.Fn evRead "evContext ctx" "int fd" "const struct iovec *iov" "int cnt" \"evStreamFunc func" "void *uap" "evStreamID *id".Ft int.Fn evCancelRW "evContext ctx" "evStreamID id".Ft int.Fn evTimeRW "evContext opaqueCtx" "evStreamID id" "evTimerID timer".Ft int.Fn evUntimeRW "evContext opaqueCtx" "evStreamID id".Ft int.Fn evListen "evContext ctx" "int fd" "int maxconn" \"evConnFunc func" "void *uap" "evConnID *id".Ft int.Fn evConnect "evContext ctx" "int fd" "void *ra" "int ralen" \"evConnFunc func" "void *uap" "evConnID *id".Ft int.Fn evCancelConn "evContext ctx" "evConnID id".Ft int.Fn evHold "evContext ctx" "evConnID id".Ft int.Fn evUnhold "evContext ctx" "evConnID id".Ft int.Fn evTryAccept "evContext ctx" "evConnID id" "int *sys_errno".Ft void.Fn evSetDebug "evContext ctx" "int level" "FILE *output".Ft void.Fn evPrintf "const evContext_p *ctx" "int level" "const char *fmt" "...".Ft void.Fn evInitID "*\s-1ID\s+1".Ft int.Fn evTestID "\s-1ID\s+1".Ft int.Fn evGetOption "evContext *ctx" "const char *option" "int *ret".Ft int.Fn evSetOption "evContext *ctx" "const char *option" "int val".Sh DESCRIPTIONThis library provides multiple outstanding asynchronous timers and I/Oto a cooperating application.  The model is similar to that of the XToolkit, in that events are registered with the library and the applicationspends most of its time in the.Fn evMainLoopfunction.  If an application already has a main loop, it can safely registerevents with this library as long as it periodically calls the.Fn evGetNextand.Fn evDispatchfunctions.  (Note that.Fn evGetNexthas both polling and blocking modes.).PpThe function.Fn evCreatecreates an event context which is needed by all the other functions in thislibrary.  All information used internally by this library is bound to thiscontext, rather than to static storage.  This makes the library .Dq thread safe ,and permits other library functions to use events withoutdisrupting the application's use of events..PpThe function.Fn evDestroydestroys a context that has been created by.Fn evCreate .All dynamic memory bound to this context will be freed.  An implicit.Fn evTimerClearwill be done on all timers set in this event context.  An implicit.Fn evDeselectFDwill be done on all file descriptors selected in this event context..PpThe function.Fn evGetNextpotentially waits for and then retrieves the next asynchronous event,placing it in the object of the.Fa evpointer argument.  The following.Fa optionsare available:.Fa EV_POLL ,meaning that.Fn evGetNextshould not block, but rather return.Dq Fa -1with.Fa errnoset to.Fa EWOULDBLOCKif no events have occurred;.Fa EV_WAIT ,which tells.Fn evGetNextto block internally until the next event occurs; and.Fa EV_NULL ,which tells.Fn evGetNextthat it should return a special .Dq no-op event, which is ignored by.Fn evDispatchbut handled correctly by.Fn evDrop ..Fa EV_NULLcan be necessary to the correct functioning of a caller\-written equivilent to.Fn evMainLoop ,wherein perterbations caused by external system events must be polled for, andthe default behaviour of internally ignoring such events is undesirable.Note that.Fa EV_POLLand.Fa EV_WAITare mutually exclusive..PpThe function.Fn evDispatchdispatches an event retrieved by.Fn evGetNext .This usually involves calling the function that was associated with the eventwhen the event was registered with.Fn evSetTimer ,.Fn evResetTimer ,or.Fn evSelectFD .All events retrieved by.Fn evGetNextmust be given over to.Fn evDispatchat some point, since there is some dynamic memory associated with each event..PpThe function.Fn evDropdeallocates dynamic memory that has been allocated by.Fn evGetNext .Calling.Fn evDispatchhas the side effect of calling.Fn evDrop ,but if you are going to drop the event rather than dispatch it, you will haveto call.Fn evDropdirectly..PpThe function.Fn evMainLoopis just:.Bd -literal -offset indentwhile ((x = evGetNext(opaqueCtx, &event, EV_WAIT)) == 0)	if ((x = evDispatch(opaqueCtx, event)) < 0)		break;return (x);.Ed.PpIn other words, get events and dispatch them until an error occurs.  One sucherror would be that all the events under this context become unregistered; inthat event, there will be nothing to wait for and.Fn evGetNextbecomes an undefined operation..PpThe function.Fn evConsTimeis a constructor for.Dq Fa struct timespecwhich allows these structures to be created and then passed as arguments toother functions without the use of temporary variables.  (If C had inlineconstructors, there would be no need for this function.).PpThe functions.Fn evTimeSpecand.Fn evTimeVal are utilities which allow the caller to convert a.Dq Fa struct timevalto a .Dq Fa struct timespec(the function of.Fn evTimeSpec )or vice versa (the function of.Fn evTimeVal ) .Note that the name of the function indicates the type of the return value..PpThe function.Fn evAddTimeadds two.Dq Fa struct timespecvalues and returns the result as a.Dq Fa struct timespec ..PpThe function.Fn evSubTimesubtracts its second.Dq Fa struct timespecargument from its first.Dq Fa struct timespecargument and returns the result as a.Dq Fa struct timespec ..PpThe function.Fn evCmpTimecompares its two.Dq Fa struct timespecarguments and returns an.Dq Fa intthat is less than zero if the first argument specifies an earlier time thanthe second, or more than zero if the first argument specifies a later timethan the second, or equal to zero if both arguments specify the same time..PpThe function.Fn evNowTimereturns a.Dq Fa struct timespecwhich either describes the current time(using.Xr clock_gettime 2 or.Xr gettimeofday 2 ) ,if successful, or has its fields set to zero, if there is an error.(In the latter case, the caller can check.Va errno ,since it will be set by.Xr gettimeofday 2 . )The timestamp returned may not be UTC time ifthe "monotime" option has been enabled with.Fn evSetOption ..PpThe function .Fn evUTCTimeis like .Fn evNowTimeexcept the result is always on the UTC timescale..PpThe function.Fn evLastEventTime returns the.Dq Fa struct timespecwhich describes the last time that certain events happened to the event context indicated by .Fa opaqueCtx .This value is updated by.Fn evCreate and.Fn evGetNext (upon entry and after.Xr select 2returns); it is routinely compared with other times in the internal handlingof, e.g., timers..PpThe function.Fn evSetTimerregisters a timer event, which will be delivered as a function call to thefunction specified by the.Fa funcargument.  The event will be delivered at absolute time.Fa due ,and then if time.Fa interis not equal to.Dq Fn evConsTime 0 0 ,subsequently at intervals equal to time.Fa inter .As a special case, specifying a.Fa dueargument equal to.Dq Fn evConsTime 0 0means .Dq due immediately .The.Fa opaqueIDargument, if specified as a value other than.Fa NULL ,will be used to store the resulting .Dq timer \s-1ID\s+1 , useful as an argument to.Fn evClearTimer .Note that in a .Dq one\-shot timer (which has an.Fa interargument equal to.Dq Fa evConsTime(0,0) )the user function.Fa funcshould deallocate any dynamic memory that is uniquely bound to the.Fa uap ,since no handles to this memory will exist within the event libraryafter a one\-shot timer has been delivered..PpThe function.Fn evResetTimerresets the values of the timer specified by.Fa idto the given arguments.  The arguments are the same as in the description of.Fn evSetTimerabove..PpThe function.Fn evClearTimerwill unregister the timer event specified by.Fa id .Note that if the.Fa uapspecified in the corresponding.Fn evSetTimercall is uniquely bound to any dynamic memory, then that dynamic memory shouldbe freed by the caller before the handle is lost.  After a call to.Fn evClearTimer ,no handles to this