diff options
Diffstat (limited to 'contrib/bind9/lib/bind/isc/eventlib.mdoc')
| -rw-r--r-- | contrib/bind9/lib/bind/isc/eventlib.mdoc | 918 |
1 files changed, 0 insertions, 918 deletions
diff --git a/contrib/bind9/lib/bind/isc/eventlib.mdoc b/contrib/bind9/lib/bind/isc/eventlib.mdoc deleted file mode 100644 index 5e9cd85..0000000 --- a/contrib/bind9/lib/bind/isc/eventlib.mdoc +++ /dev/null @@ -1,918 +0,0 @@ -.\" $Id: eventlib.mdoc,v 1.3 2004/03/09 06:30:08 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 DESCRIPTION -This library provides multiple outstanding asynchronous timers and I/O -to a cooperating application. The model is similar to that of the X -Toolkit, in that events are registered with the library and the application -spends most of its time in the -.Fn evMainLoop -function. If an application already has a main loop, it can safely register -events with this library as long as it periodically calls the -.Fn evGetNext -and -.Fn evDispatch -functions. (Note that -.Fn evGetNext -has both polling and blocking modes.) -.Pp -The function -.Fn evCreate -creates an event context which is needed by all the other functions in this -library. All information used internally by this library is bound to this -context, rather than to static storage. This makes the library -.Dq thread safe , -and permits other library functions to use events without -disrupting the application's use of events. -.Pp -The function -.Fn evDestroy -destroys a context that has been created by -.Fn evCreate . -All dynamic memory bound to this context will be freed. An implicit -.Fn evTimerClear -will be done on all timers set in this event context. An implicit -.Fn evDeselectFD -will be done on all file descriptors selected in this event context. -.Pp -The function -.Fn evGetNext -potentially waits for and then retrieves the next asynchronous event, -placing it in the object of the -.Fa ev -pointer argument. The following -.Fa options -are available: -.Fa EV_POLL , -meaning that -.Fn evGetNext -should not block, but rather return -.Dq Fa -1 -with -.Fa errno -set to -.Fa EWOULDBLOCK -if no events have occurred; -.Fa EV_WAIT , -which tells -.Fn evGetNext -to block internally until the next event occurs; and -.Fa EV_NULL , -which tells -.Fn evGetNext -that it should return a special -.Dq no-op -event, which is ignored by -.Fn evDispatch -but handled correctly by -.Fn evDrop . -.Fa EV_NULL -can 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, and -the default behaviour of internally ignoring such events is undesirable. -Note that -.Fa EV_POLL -and -.Fa EV_WAIT -are mutually exclusive. -.Pp -The function -.Fn evDispatch -dispatches an event retrieved by -.Fn evGetNext . -This usually involves calling the function that was associated with the event -when the event was registered with -.Fn evSetTimer , -.Fn evResetTimer , -or -.Fn evSelectFD . -All events retrieved by -.Fn evGetNext -must be given over to -.Fn evDispatch -at some point, since there is some dynamic memory associated with each event. -.Pp -The function -.Fn evDrop -deallocates dynamic memory that has been allocated by -.Fn evGetNext . -Calling -.Fn evDispatch -has the side effect of calling -.Fn evDrop , -but if you are going to drop the event rather than dispatch it, you will have -to call -.Fn evDrop -directly. -.Pp -The function -.Fn evMainLoop -is just: -.Bd -literal -offset indent -while ((x = evGetNext(opaqueCtx, &event, EV_WAIT)) == 0) - if ((x = evDispatch(opaqueCtx, event)) < 0) - break; -return (x); -.Ed -.Pp -In other words, get events and dispatch them until an error occurs. One such -error would be that all the events under this context become unregistered; in -that event, there will be nothing to wait for and -.Fn evGetNext -becomes an undefined operation. -.Pp -The function -.Fn evConsTime -is a constructor for -.Dq Fa struct timespec -which allows these structures to be created and then passed as arguments to -other functions without the use of temporary variables. (If C had inline -constructors, there would be no need for this function.) -.Pp -The functions -.Fn evTimeSpec -and -.Fn evTimeVal -are utilities which allow the caller to convert a -.Dq Fa struct timeval -to 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. -.Pp -The function -.Fn evAddTime -adds two -.Dq Fa struct timespec -values and returns the result as a -.Dq Fa struct timespec . -.Pp -The function -.Fn evSubTime -subtracts its second -.Dq Fa struct timespec -argument from its first -.Dq Fa struct timespec -argument and returns the result as a -.Dq Fa struct timespec . -.Pp -The function -.Fn evCmpTime -compares its two -.Dq Fa struct timespec -arguments and returns an -.Dq Fa int -that is less than zero if the first argument specifies an earlier time than -the second, or more than zero if the first argument specifies a later time -than the second, or equal to zero if both arguments specify the same time. -.Pp -The function -.Fn evNowTime -returns a -.Dq Fa struct timespec -which 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 if -the "monotime" option has been enabled with -.Fn evSetOption . -.Pp -The function -.Fn evUTCTime -is like -.Fn evNowTime -except the result is always on the UTC timescale. -.Pp -The function -.Fn evLastEventTime -returns the -.Dq Fa struct timespec -which 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 2 -returns); it is routinely compared with other times in the internal handling -of, e.g., timers. -.Pp -The function -.Fn evSetTimer -registers a timer event, which will be delivered as a function call to the -function specified by the -.Fa func -argument. The event will be delivered at absolute time -.Fa due , -and then if time -.Fa inter -is not equal to -.Dq Fn evConsTime 0 0 , -subsequently at intervals equal to time -.Fa inter . -As a special case, specifying a -.Fa due -argument equal to -.Dq Fn evConsTime 0 0 -means -.Dq due immediately . -The -.Fa opaqueID -argument, 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 inter -argument equal to -.Dq Fa evConsTime(0,0) ) -the user function -.Fa func -should deallocate any dynamic memory that is uniquely bound to the -.Fa uap , -since no handles to this memory will exist within the event library -after a one\-shot timer has been delivered. -.Pp -The function -.Fn evResetTimer -resets the values of the timer specified by -.Fa id -to the given arguments. The arguments are the same as in the description of -.Fn evSetTimer -above. -.Pp -The function -.Fn evClearTimer -will unregister the timer event specified by -.Fa id . -Note that if the -.Fa uap -specified in the corresponding -.Fn evSetTimer -call is uniquely bound to any dynamic memory, then that dynamic memory should -be freed by the caller before the handle is lost. After a call to -.Fn evClearTimer , -no handles to this -.Fa uap -will exist within the event library. -.Pp -The function -.Fn evConfigTimer -can be used to manipulate other aspects of a timer. -Currently two modes are defined "rate" and "interval" which affect the -way recurrent timers are scheduled. -The default mode is "interval" where the event gets scheduled -.Fa inter -after last time it was run. -If mode "rate" is selected the event gets scheduled -.Fa inter -after last time it was scheduled. -For both "rate" and "interval" the numerical argument -.Fa value -is ignored. -.Pp -The 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 func -to occur. However, for an -.Em idle -timer, the call will occur after at least -.Dq Fa max_idle -time 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 func -is 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 . -.Pp -The -.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_idle -time has passed since this (possibly new) time, providing a caller mechanism -for resetting the call to the -.Fa func -associated with the idle timer. (See the description of -.Fn evSetIdleTimer , -above, for information about -.Fa func -and -.Fa max_idle . ) -.Pp -The -.Fn evResetIdleTimer -function reschedules a timer and resets the callback function and its argument. -Note that resetting a timer also ``touches'' it. -.Pp -The -.Fn evClearIdleTimer -function unregisters the idle timer associated with -.Fa id . -See the discussion under -.Fn evClearTimer , -above, for information regarding caller handling of the -.Fa uap -associated with the corresponding -.Fn evSetIdleTimer -call. -.Pp -The function -.Fn evWaitFor -places the function -.Fa func -on the given event context's wait queue with the associated (possibly -.Dv NULL ) -.Dq Fa tag ; -if -.Fa id -is -.No non- Ns Dv NULL , -then it will contain the -.Dq wait \s-1ID\s+1 -associated with the created queue element. -.Pp -The function -.Fn evDo -marks -.Em all -of the -.Dq waiting -functions in the given event context's wait queue with the associated (possibly -.Dv NULL ) -.Dq Fa tag -as runnable. This places these functions in a -.Dq done -queue which will be read by -.Fn evGetNext . -.Pp -The function -.Fn evUnwait -will search for the -.Dq wait \s-1ID\s+1 -.Fa id -in the wait queue of the given event context; if an element with the given -.Fa id -is not found, then the -.Dq done -queue of that context is searched. If found, the queue element is removed -from the appropriate list. -.Pp -The function -.Fn evDefer -causes a function (specified as -.Fa func , -with argument -.Fa uap ) -to be dispatched at some later time. Note that the -.Fa tag -argument to -.Fa func -will always be -.Fa NULL -when dispatched. -.Pp -The function -.Fn evSelectFD -registers a file I/O event for the file descriptor specified by -.Fa fd . -Bits in the -.Fa eventmask -argument are named -.Fa EV_READ , -.Fa EV_WRITE , -and -.Fa EV_EXCEPT . -At least one of these bits must be specified. If the -.Fa id -argument 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_NONBLOCK -flag with -.Xr fcntl 2 -on its first concurrent registration via -.Fn evSelectFD . -An -.Fn evSelectFD -remains in effect until cancelled via -.Fn evDeselectFD . -.Pp -The function -.Fn evDeselectFD -unregisters the ``file event'' specified by the -.Fa id -argument. If the corresponding -.Fa uap -uniquely points to dynamic memory, that memory should be freed before its -handle is lost, since after a call to -.Fn evDeselectFD , -no handles to this event's -.Fa uap -will remain within the event library. A file descriptor will be taken out of -nonblocking mode (see -.Fa O_NONBLOCK -and -.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 . -.Pp -The function -.Fn evConsIovec -is a constructor for a single -.Ft struct iovec -structure, which is useful for -.Fn evWrite -and -.Fn evRead . -.Pp -The functions -.Fn evWrite -and -.Fn evRead -start 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 iov -and -.Fa cnt . -The supplied function -.Fa func -will be called with argument -.Fa uap -when the I/O operation is complete. If -.Fa id -is not -.Fa NULL , -it will be filled a with the stream event identifier suitable for use with -.Fn evCancelRW . -.Pp -The function -.Fn evCancelRW -extinguishes an outstanding -.Fn evWrite -or -.Fn evRead -call. System I/O calls cannot always be cancelled, but you are guaranteed -that the -.Fa func -function supplied to -.Fn evWrite -or -.Fn evRead -will not be called after a call to -.Fn evCancelRW . -Care should be taken not to deallocate or otherwise reuse the space pointed -to by the segment descriptors in -.Fa iov -unless the underlying file descriptor is closed first. -.Pp -The function -.Fn evTimeRW -sets the stream associated with the given stream \s-1ID\s+1 -.Dq Fa id -to have the idle timer associated with the timer \s-1ID\s+1 -.Dq Fa timer . -.Pp -The function -.Fn evUntimeRW -says that the stream associated with the given stream \s-1ID\s+1 -.Dq Fa id -should ignore its idle timer, if present. -.Pp -The functions -.Fn evListen , -.Fn evConnect , -and -.Fn evCancelConn -can be used to manage asynchronous incoming and outgoing socket connections. -Sockets to be used with these functions should first be created with -.Xr socket 2 -and given a local name with -.Xr bind 2 . -It is extremely unlikely that the same socket will ever be -useful for both incoming and outgoing connections. The -.Fa id -argument to -.Fn evListen -and -.Fn evConnect -is either -.Fa NULL -or the address of a -.Ft evFileID -variable which can then be used in a subsequent call to -.Fn evCancelConn . -.Pp -After a call to -.Fn evListen , -each incoming connection arriving on -.Fa fd -will cause -.Fa func -to be called with -.Fa uap -as one of its arguments. -.Fn evConnect -initiates an outgoing connection on -.Fa fd -to destination address -.Fa ra -(whose length is -.Fa ralen ) . -When the connection is complete, -.Fa func -will be called with -.Fa uap -as one of its arguments. The argument -.Fa fd -to -.Fn \*(lp*func\*(rp -will be -.Fa -1 -if an error occurred that prevented this connection from completing -successfully. In this case -.Fn errno -will have been set and the socket described by -.Fa fd -will have been closed. The -.Fn evCancelConn -function will prevent delivery of all pending and subsequent -events for the outstanding connection. The -.Fn evHold -function will suspend the acceptance of new connections on the listener -specified by -.Fa id . -Connections will be queued by the protocol stack up to the system's limit. The -.Fn evUnhold -function will reverse the effects of -.Fn evHold , -allowing incoming connections to be delivered for listener -.Fa id . -The -.Fn evTryAccept -function will poll the listener specified by -.Fa id , -accepting a new connection if one is available, and queuing a connection event -for later retrieval by -.Fn evGetNext . -If the connection event queued is an accept error(), sys_errno will contain -the error code; otherwise it will be zero. All connection events queued by -.Fn evTryAccept -will be delivered by -.Fn evGetNext -before a new select is done on the listener. -.Pp -The function -.Fn evSetDebug -sets the debugging -.Fa level -and diagnostic -.Fa output -file handle for an event context. Greater numeric levels will -result in more verbose output being sent to the output FILE during program -execution. -.Pp -The function -.Fn evPrintf -prints a message with the format -.Dq Fa fmt -and the following arguments (if any), on the output stream associated -with the event context pointed to by -.Fa ctx . -The message is output if the event context's debug level is greater than -or equal to the indicated -.Fa level . -.Pp -The function -.Fn evInitID -will 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 evTestID -will recognize. -This is useful to make a handle as "not in use". -.Pp -The function -.Fn evTestID -will examine an opaque \s-1ID\s+1 and return -.Dq TRUE -only if it is not in its initialized state. -.Pp -The functions -.Fn evGetOption -and -.Fn evSetOption -can 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. -.Pp -The default value for the "monotime" option is zero which selects -the UTC timescale. -When set to a value of one, eventlib will use the -CLOCK_MONOTONIC timescale from -.Xr clock_gettime -instead. -The CLOCK_MONOTONIC timescale is never stepped and should -run at a rate as close to TAI as possible, so it is unaffected -when the system clock is set. -If timerevents should run at a predictable rate, set the value -to one, of they should run at a predictable time of day, leave -it at zero. -If the CLOCK_MONOTONIC timescale is not available on the system, -attempts to set/get this option will fail. -.Sh RETURN VALUES -All the functions whose return type is -.Dq Fa int -use the standard convention of returning zero (0) to indicate success, or -returning -.Dq Fa -1 -and setting -.Fa errno -to indicate failure. -.Sh FILE -.Pa heap.h , -which is in the -.Pa src/lib/isc -directory of the current -.Sy BIND -distribution. -.Sh ERRORS -The possible values for -.Fa errno -when one of the -.Dq Fa int -functions in this library returns -.Dq Fa -1 -include those of the Standard C Library and also: -.Bl -tag -width EWOULDBLOCKAA -.It Bq Er EINVAL -Some function argument has an unreasonable value. -.It Bq Er EINVAL -The 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 ENOENT -The specified -.Dq event \s-1ID\s+1 -does not exist. -.It Bq Er EWOULDBLOCK -No events have occurred and the -.Fa EV_POLL -option was specified. -.It Bq Er EBADF -The 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 BUGS -This huge man page needs to be broken up into a handful of smaller ones. -.Sh HISTORY -The -.Nm eventlib -library was designed by Paul Vixie with excellent advice from his friends -and with tips 'o the cap to the X Consortium and the implementors of DEC SRC -Modula-3. |
