.Fa uapwill exist within the event library..PpThe function.Fn evConfigTimercan be used to manipulate other aspects of a timer.Currently two modes are defined "rate" and "interval" which affect theway recurrent timers are scheduled.The default mode is "interval" where the event gets scheduled.Fa interafter last time it was run.If mode "rate" is selected the event gets scheduled.Fa interafter last time it was scheduled.For both "rate" and "interval" the numerical argument.Fa valueis ignored..PpThe function.Fn evSetIdleTimer is similar to (and built on).Fn evSetTimer ;it registers an idle timer event which provides for the function call to.Fa functo occur.  However, for an.Em idletimer, the call will occur after at least.Dq Fa max_idletime has passed since the time the idle timer was.Dq last touched ;originally, this is set to the time returned by.Fn evLastEventTime (described above) for the event context specified by .Fa opaqueCtx .  This is a .Dq one\-shot timer, but the time at which the.Fa funcis actually called can be changed by recourse to.Fn evTouchIdleTimer(described below).  The pointer to the underlying .Dq timer \s-1ID\s+1 is returned in.Fa opaqueID ,if it is.No non- Ns Dv NULL ..PpThe.Fn evTouchIdleTimer function updates the idle timer associated with.Fa id ,setting its idea of the time it was last accessed to the value returned by.Fn evLastEventTime(described above) for the event context specified by.Fa opaqueCtx .This means that the idle timer will expire after at least.Fa max_idletime has passed since this (possibly new) time, providing a caller mechanismfor resetting the call to the.Fa funcassociated with the idle timer.  (See the description of.Fn evSetIdleTimer ,above, for information about.Fa funcand.Fa max_idle . ).PpThe.Fn evResetIdleTimerfunction reschedules a timer and resets the callback function and its argument.Note that resetting a timer also ``touches'' it..PpThe.Fn evClearIdleTimerfunction unregisters the idle timer associated with.Fa id .See the discussion under.Fn evClearTimer , above, for information regarding caller handling of the.Fa uapassociated with the corresponding.Fn evSetIdleTimercall..PpThe function.Fn evWaitForplaces the function.Fa funcon the given event context's wait queue with the associated (possibly.Dv NULL ).Dq Fa tag ;if .Fa idis .No non- Ns Dv NULL ,then it will contain the .Dq wait \s-1ID\s+1 associated with the created queue element..PpThe function.Fn evDo marks .Em allof the .Dq waiting functions in the given event context's wait queue with the associated (possibly.Dv NULL ).Dq Fa tagas runnable.  This places these functions in a.Dq donequeue which will be read by.Fn evGetNext ..PpThe function.Fn evUnwait will search for the.Dq wait \s-1ID\s+1 .Fa idin the wait queue of the given event context; if an element with the given.Fa id is not found, then the.Dq donequeue of that context is searched.  If found, the queue element is removedfrom the appropriate list..PpThe function.Fn evDefercauses a function (specified as.Fa func ,with argument.Fa uap )to be dispatched at some later time.  Note that the.Fa tagargument to.Fa funcwill always be.Fa NULLwhen dispatched..PpThe function.Fn evSelectFDregisters a file I/O event for the file descriptor specified by.Fa fd .Bits in the.Fa eventmaskargument are named.Fa EV_READ ,.Fa EV_WRITE ,and.Fa EV_EXCEPT .At least one of these bits must be specified.  If the.Fa idargument is not equal to.Fa NULL ,it will be used to store a unique ``file event \s-1ID\s+1'' for this event,which is useful in subsequent calls to.Fn evDeselectFD .A file descriptor will be made nonblocking using the.Fa O_NONBLOCKflag with.Xr fcntl 2on its first concurrent registration via.Fn evSelectFD .An.Fn evSelectFDremains in effect until cancelled via.Fn evDeselectFD ..PpThe function.Fn evDeselectFDunregisters the ``file event'' specified by the.Fa idargument.  If the corresponding.Fa uapuniquely points to dynamic memory, that memory should be freed before itshandle is lost, since after a call to.Fn evDeselectFD ,no handles to this event's.Fa uapwill remain within the event library.  A file descriptor will be taken out ofnonblocking mode (see.Fa O_NONBLOCKand.Xr fcntl 2 )when its last event registration is removed via.Fn evDeselectFD ,if it was in blocking mode before the first registration via.Fn evSelectFD ..PpThe function.Fn evConsIovecis a constructor for a single.Ft struct iovecstructure, which is useful for.Fn evWriteand.Fn evRead ..PpThe functions.Fn evWriteand.Fn evReadstart asynchronous stream I/O operations on file descriptor.Fa fd .The data to be written or read is in the scatter/gather descriptor specified by.Fa iovand.Fa cnt .The supplied function.Fa funcwill be called with argument.Fa uapwhen the I/O operation is complete.  If.Fa idis not.Fa NULL ,it will be filled a with the stream event identifier suitable for use with.Fn evCancelRW ..PpThe function.Fn evCancelRWextinguishes an outstanding.Fn evWriteor.Fn evReadcall.  System I/O calls cannot always be cancelled, but you are guaranteedthat the.Fa funcfunction supplied to.Fn evWriteor.Fn evReadwill not be called after a call to.Fn evCancelRW .Care should be taken not to deallocate or otherwise reuse the space pointedto by the segment descriptors in.Fa iovunless the underlying file descriptor is closed first..PpThe function.Fn evTimeRWsets the stream associated with the given stream \s-1ID\s+1 .Dq Fa idto have the idle timer associated with the timer \s-1ID\s+1 .Dq Fa timer ..PpThe function.Fn evUntimeRWsays that the stream associated with the given stream \s-1ID\s+1.Dq Fa idshould ignore its idle timer, if present..PpThe functions.Fn evListen ,.Fn evConnect ,and.Fn evCancelConncan be used to manage asynchronous incoming and outgoing socket connections.Sockets to be used with these functions should first be created with.Xr socket 2and given a local name with.Xr bind 2 .It is extremely unlikely that the same socket will ever beuseful for both incoming and outgoing connections.  The.Fa idargument to.Fn evListenand.Fn evConnectis either.Fa NULLor the address of a.Ft evFileIDvariable which can then be used in a subsequent call to.Fn evCancelConn ..PpAfter a call to.Fn evListen ,each incoming connection arriving on.Fa fdwill cause.Fa functo be called with.Fa uapas one of its arguments..Fn evConnectinitiates an outgoing connection on.Fa fdto destination address.Fa ra(whose length is.Fa ralen ) .When the connection is complete,.Fa funcwill be called with.Fa uapas one of its arguments.  The argument.Fa fdto.Fn \*(lp*func\*(rpwill be.Fa -1if an error occurred that prevented this connection from completing successfully.  In this case.Fn errnowill have been set and the socket described by.Fa fdwill have been closed.  The.Fn evCancelConnfunction will prevent delivery of all pending and subsequentevents for the outstanding connection.  The.Fn evHoldfunction will suspend the acceptance of new connections on the listenerspecified by.Fa id .Connections will be queued by the protocol stack up to the system's limit.  The.Fn evUnholdfunction will reverse the effects of.Fn evHold ,allowing incoming connections to be delivered for listener.Fa id .The.Fn evTryAcceptfunction will poll the listener specified by.Fa id ,accepting a new connection if one is available, and queuing a connection eventfor later retrieval by.Fn evGetNext .If the connection event queued is an accept error(), sys_errno will containthe error code; otherwise it will be zero.  All connection events queued by.Fn evTryAcceptwill be delivered by.Fn evGetNextbefore a new select is done on the listener..PpThe function.Fn evSetDebugsets the debugging.Fa leveland diagnostic.Fa outputfile handle for an event context.  Greater numeric levels willresult in more verbose output being sent to the output FILE during programexecution..PpThe function.Fn evPrintfprints a message with the format.Dq Fa fmtand the following arguments (if any), on the output stream associatedwith the event context pointed to by.Fa ctx .The message is output if the event context's debug level is greater thanor equal to the indicated.Fa level ..PpThe function.Fn evInitIDwill initialize an opaque .Dq evConn \s-1ID\s+1 , .Dq evFile \s-1ID\s+1 , .Dq evStream \s-1ID\s+1 , .Dq evTimer \s-1ID\s+1 , .Dq evWait \s-1ID\s+1 , .Dq evContext , or.Dq evEvent ,which is passed by reference to a state which.Fn evTestIDwill recognize.This is useful to make a handle as "not in use"..PpThe function.Fn evTestIDwill examine an opaque \s-1ID\s+1 and return.Dq TRUEonly if it is not in its initialized state..PpThe functions.Fn evGetOptionand .Fn evSetOptioncan be used to inspect and modify options.Currently there is only one option,  "monotime" and it is global for all instances of eventlib so the ctx argument must be passed as NULL..PpThe default value for the "monotime" option is zero which selectsthe UTC timescale.When set to a value of one, eventlib will use theCLOCK_MONOTONIC timescale from.Xr clock_gettimeinstead.The CLOCK_MONOTONIC timescale is never stepped and shouldrun at a rate as close to TAI as possible, so it is unaffectedwhen the system clock is set.If timerevents should run at a predictable rate, set the valueto one, of they should run at a predictable time of day, leaveit at zero.If the CLOCK_MONOTONIC timescale is not available on the system,attempts to set/get this option will fail..Sh RETURN VALUESAll the functions whose return type is.Dq Fa intuse the standard convention of returning zero (0) to indicate success, orreturning.Dq Fa -1and setting.Fa errnoto indicate failure..Sh FILE.Pa heap.h ,which is in the .Pa src/lib/iscdirectory of the current .Sy BINDdistribution..Sh ERRORSThe possible values for.Fa errnowhen one of the.Dq Fa intfunctions in this library returns.Dq Fa -1include those of the Standard C Library and also:.Bl -tag -width EWOULDBLOCKAA.It Bq Er EINVALSome function argument has an unreasonable value..It Bq Er EINVALThe specified file descriptor has an integer value greater than the default.Fa FD_SETSIZE ,meaning that the application's limit is higher than the library's..It Bq Er ENOENTThe specified .Dq event \s-1ID\s+1 does not exist..It Bq Er EWOULDBLOCKNo events have occurred and the.Fa EV_POLLoption was specified..It Bq Er EBADFThe specified signal was unblocked outside the library..El.Sh SEE ALSO.Xr gettimeofday 2 ,.Xr select 2 ,.Xr fcntl 3 ,.Xr malloc 3 ,.Xr @INDOT@named @SYS_OPS_EXT@ ,.Xr readv 3 ,.Xr writev 3 ..Sh BUGSThis huge man page needs to be broken up into a handful of smaller ones..Sh HISTORYThe.Nm eventliblibrary was designed by Paul Vixie with excellent advice from his friendsand with tips 'o the cap to the X Consortium and the implementors of DEC SRCModula-3.