| blob | 5e9cd85b1bc9127536f6aea860ac81d4fab8c6bf |
1 .\" $Id: eventlib.mdoc,v 1.3 2004/03/09 06:30:08 marka Exp $
2 .\"
3 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
4 .\" Copyright (c) 1995-1999 by Internet Software Consortium
5 .\"
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
16 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .\"
18 .Dd March 6, 1996
19 .Dt EVENTLIB 3
20 .Os BSD 4
21 .Sh NAME
22 .Nm evConnFunc ,
23 .Nm evFileFunc ,
24 .Nm evStreamFunc ,
25 .Nm evTimerFunc ,
26 .Nm evWaitFunc ,
27 .Nm evCreate ,
28 .Nm evDestroy ,
29 .Nm evGetNext ,
30 .Nm evDispatch ,
31 .Nm evDrop ,
32 .Nm evMainLoop ,
33 .Nm evConsTime ,
34 .Nm evTimeSpec ,
35 .Nm evTimeVal ,
36 .Nm evAddTime ,
37 .Nm evSubTime ,
38 .Nm evCmpTime ,
39 .Nm evNowTime ,
40 .Nm evUTCTime ,
41 .Nm evLastEventTime ,
42 .Nm evSetTimer ,
43 .Nm evResetTimer ,
44 .Nm evConfigTimer ,
45 .Nm evClearTimer ,
46 .Nm evSetIdleTimer ,
47 .Nm evTouchIdleTimer ,
48 .Nm evClearIdleTimer ,
49 .Nm evWaitFor ,
50 .Nm evDo ,
51 .Nm evUnwait ,
52 .Nm evDefer ,
53 .Nm evSelectFD ,
54 .Nm evDeselectFD ,
55 .Nm evWrite ,
56 .Nm evRead ,
57 .Nm evCancelRW ,
58 .Nm evTimeRW ,
59 .Nm evUntimeRW ,
60 .Nm evListen ,
61 .Nm evConnect ,
62 .Nm evCancelConn ,
63 .Nm evHold ,
64 .Nm evUnhold ,
65 .Nm evTryAccept ,
66 .Nm evConsIovec ,
67 .Nm evSetDebug ,
68 .Nm evPrintf ,
69 .Nm evInitID ,
70 .Nm evTestID ,
71 .Nm evGetOption ,
72 .Nm evSetOption
73 .Nd event handling library
74 .Sh SYNOPSIS
75 .Fd #include <isc/eventlib.h>
76 .Ft typedef void
77 .Fn \*(lp*evConnFunc\*(rp "evContext ctx" "void *uap" "int fd" \
78 "const void *la" "int lalen" "const void *ra" "int ralen"
79 .Ft typedef void
80 .Fn \*(lp*evTimerFunc\*(rp "evContext ctx" "void *uap" \
81 "struct timespec due" "struct timespec inter"
82 .Ft typedef void
83 .Fn \*(lp*evFileFunc\*(rp "evContext ctx" "void *uap" "int fd" "int eventmask"
84 .Ft typedef void
85 .Fn \*(lp*evStreamFunc\*(rp "evContext ctx" "void *uap" "int fd" "int bytes"
86 .Ft typedef void
87 .Fn \*(lp*evWaitFunc\*(rp "evContext ctx" "void *uap" "const void *tag"
88 .Ft int
89 .Fn evCreate "evContext *ctx"
90 .Ft int
91 .Fn evDestroy "evContext ctx"
92 .Ft int
93 .Fn evGetNext "evContext ctx" "evEvent *ev" "int options"
94 .Ft int
95 .Fn evDispatch "evContext ctx" "evEvent ev"
96 .Ft void
97 .Fn evDrop "evContext ctx" "evEvent ev"
98 .Ft int
99 .Fn evMainLoop "evContext ctx"
100 .Ft struct timespec
101 .Fn evConsTime "int sec" "int usec"
102 .Ft struct timespec
103 .Fn evTimeSpec "struct timeval tv"
104 .Ft struct timeval
105 .Fn evTimeVal "struct timespec ts"
106 .Ft struct timespec
107 .Fn evAddTime "struct timespec addend1" "struct timespec addend2"
108 .Ft struct timespec
109 .Fn evSubTime "struct timespec minuend" "struct timespec subtrahend"
110 .Ft struct timespec
111 .Fn evCmpTime "struct timespec a" "struct timespec b"
112 .Ft struct timespec
113 .Fn evNowTime "void"
114 .Ft struct timespec
115 .Fn evUTCTime "void"
116 .Ft struct timespec
117 .Fn evLastEventTime "evContext opaqueCtx"
118 .Ft int
119 .Fn evSetTimer "evContext ctx" "evTimerFunc func" "void *uap" \
120 "struct timespec due" "struct timespec inter" "evTimerID *id"
121 .Ft int
122 .Fn evResetTimer "evContext ctx" "evTimerID id" "evTimerFunc func" \
123 "void *uap" "struct timespec due" "struct timespec inter"
124 .Ft int
125 .Fn evConfigTimer "evContext ctx" "evTimerID id" "const char *param" \
126 "int value"
127 .Ft int
128 .Fn evClearTimer "evContext ctx" "evTimerID id"
129 .Ft int
130 .Fn evSetIdleTimer "evContext opaqueCtx" "evTimerFunc func" "void *uap" \
131 "struct timespec max_idle" "evTimerID *opaqueID"
132 .Ft int
133 .Fn evTouchIdleTimer "evContext opaqueCtx" "evTimerID id"
134 .Ft int
135 .Fn evResetIdleTimer "evContext opaqueCtx" "evTimerID id" "evTimerFunc func" \
136 "void *uap" "struct timespec max_idle"
137 .Ft int
138 .Fn evClearIdleTimer "evContext opaqueCtx" "evTimerID id"
139 .Ft int
140 .Fn evWaitFor "evContext opaqueCtx" "const void *tag" \
141 "evWaitFunc func" "void *uap" "evWaitID *id"
142 .Ft int
143 .Fn evDo "evContext opaqueCtx" "const void *tag"
144 .Ft int
145 .Fn evUnwait "evContext opaqueCtx" "evWaitID id"
146 .Ft int
147 .Fn evDefer "evContext opaqueCtx" "evWaitFunc func" "void *uap"
148 .Ft int
149 .Fn evSelectFD "evContext ctx" "int fd" "int eventmask" \
150 "evFileFunc func" "void *uap" "evFileID *id"
151 .Ft int
152 .Fn evDeselectFD "evContext ctx" "evFileID id"
153 .Ft struct iovec
154 .Fn evConsIovec "void *buf" "size_t cnt"
155 .Ft int
156 .Fn evWrite "evContext ctx" "int fd" "const struct iovec *iov" "int cnt" \
157 "evStreamFunc func" "void *uap" "evStreamID *id"
158 .Ft int
159 .Fn evRead "evContext ctx" "int fd" "const struct iovec *iov" "int cnt" \
160 "evStreamFunc func" "void *uap" "evStreamID *id"
161 .Ft int
162 .Fn evCancelRW "evContext ctx" "evStreamID id"
163 .Ft int
164 .Fn evTimeRW "evContext opaqueCtx" "evStreamID id" "evTimerID timer"
165 .Ft int
166 .Fn evUntimeRW "evContext opaqueCtx" "evStreamID id"
167 .Ft int
168 .Fn evListen "evContext ctx" "int fd" "int maxconn" \
169 "evConnFunc func" "void *uap" "evConnID *id"
170 .Ft int
171 .Fn evConnect "evContext ctx" "int fd" "void *ra" "int ralen" \
172 "evConnFunc func" "void *uap" "evConnID *id"
173 .Ft int
174 .Fn evCancelConn "evContext ctx" "evConnID id"
175 .Ft int
176 .Fn evHold "evContext ctx" "evConnID id"
177 .Ft int
178 .Fn evUnhold "evContext ctx" "evConnID id"
179 .Ft int
180 .Fn evTryAccept "evContext ctx" "evConnID id" "int *sys_errno"
181 .Ft void
182 .Fn evSetDebug "evContext ctx" "int level" "FILE *output"
183 .Ft void
184 .Fn evPrintf "const evContext_p *ctx" "int level" "const char *fmt" "..."
185 .Ft void
186 .Fn evInitID "*\s-1ID\s+1"
187 .Ft int
188 .Fn evTestID "\s-1ID\s+1"
189 .Ft int
190 .Fn evGetOption "evContext *ctx" "const char *option" "int *ret"
191 .Ft int
192 .Fn evSetOption "evContext *ctx" "const char *option" "int val"
193 .Sh DESCRIPTION
194 This library provides multiple outstanding asynchronous timers and I/O
195 to a cooperating application. The model is similar to that of the X
196 Toolkit, in that events are registered with the library and the application
197 spends most of its time in the
198 .Fn evMainLoop
199 function. If an application already has a main loop, it can safely register
200 events with this library as long as it periodically calls the
201 .Fn evGetNext
202 and
203 .Fn evDispatch
204 functions. (Note that
205 .Fn evGetNext
206 has both polling and blocking modes.)
207 .Pp
208 The function
209 .Fn evCreate
210 creates an event context which is needed by all the other functions in this
211 library. All information used internally by this library is bound to this
212 context, rather than to static storage. This makes the library
213 .Dq thread safe ,
214 and permits other library functions to use events without
215 disrupting the application's use of events.
216 .Pp
217 The function
218 .Fn evDestroy
219 destroys a context that has been created by
220 .Fn evCreate .
221 All dynamic memory bound to this context will be freed. An implicit
222 .Fn evTimerClear
223 will be done on all timers set in this event context. An implicit
224 .Fn evDeselectFD
225 will be done on all file descriptors selected in this event context.
226 .Pp
227 The function
228 .Fn evGetNext
229 potentially waits for and then retrieves the next asynchronous event,
230 placing it in the object of the
231 .Fa ev
232 pointer argument. The following
233 .Fa options
234 are available:
235 .Fa EV_POLL ,
236 meaning that
237 .Fn evGetNext
238 should not block, but rather return
239 .Dq Fa -1
240 with
241 .Fa errno
242 set to
243 .Fa EWOULDBLOCK
244 if no events have occurred;
245 .Fa EV_WAIT ,
246 which tells
247 .Fn evGetNext
248 to block internally until the next event occurs; and
249 .Fa EV_NULL ,
250 which tells
251 .Fn evGetNext
252 that it should return a special
253 .Dq no-op
254 event, which is ignored by
255 .Fn evDispatch
256 but handled correctly by
257 .Fn evDrop .
258 .Fa EV_NULL
259 can be necessary to the correct functioning of a caller\-written equivilent to
260 .Fn evMainLoop ,
261 wherein perterbations caused by external system events must be polled for, and
262 the default behaviour of internally ignoring such events is undesirable.
263 Note that
264 .Fa EV_POLL
265 and
266 .Fa EV_WAIT
267 are mutually exclusive.
268 .Pp
269 The function
270 .Fn evDispatch
271 dispatches an event retrieved by
272 .Fn evGetNext .
273 This usually involves calling the function that was associated with the event
274 when the event was registered with
275 .Fn evSetTimer ,
276 .Fn evResetTimer ,
277 or
278 .Fn evSelectFD .
279 All events retrieved by
280 .Fn evGetNext
281 must be given over to
282 .Fn evDispatch
283 at some point, since there is some dynamic memory associated with each event.
284 .Pp
285 The function
286 .Fn evDrop
287 deallocates dynamic memory that has been allocated by
288 .Fn evGetNext .
289 Calling
290 .Fn evDispatch
291 has the side effect of calling
292 .Fn evDrop ,
293 but if you are going to drop the event rather than dispatch it, you will have
294 to call
295 .Fn evDrop
296 directly.
297 .Pp
298 The function
299 .Fn evMainLoop
300 is just:
301 .Bd -literal -offset indent
302 while ((x = evGetNext(opaqueCtx, &event, EV_WAIT)) == 0)
303 if ((x = evDispatch(opaqueCtx, event)) < 0)
304 break;
305 return (x);
306 .Ed
307 .Pp
308 In other words, get events and dispatch them until an error occurs. One such
309 error would be that all the events under this context become unregistered; in
310 that event, there will be nothing to wait for and
311 .Fn evGetNext
312 becomes an undefined operation.
313 .Pp
314 The function
315 .Fn evConsTime
316 is a constructor for
317 .Dq Fa struct timespec
318 which allows these structures to be created and then passed as arguments to
319 other functions without the use of temporary variables. (If C had inline
320 constructors, there would be no need for this function.)
321 .Pp
322 The functions
323 .Fn evTimeSpec
324 and
325 .Fn evTimeVal
326 are utilities which allow the caller to convert a
327 .Dq Fa struct timeval
328 to a
329 .Dq Fa struct timespec
330 (the function of
331 .Fn evTimeSpec )
332 or vice versa (the function of
333 .Fn evTimeVal ) .
334 Note that the name of the function indicates the type of the return value.
335 .Pp
336 The function
337 .Fn evAddTime
338 adds two
339 .Dq Fa struct timespec
340 values and returns the result as a
341 .Dq Fa struct timespec .
342 .Pp
343 The function
344 .Fn evSubTime
345 subtracts its second
346 .Dq Fa struct timespec
347 argument from its first
348 .Dq Fa struct timespec
349 argument and returns the result as a
350 .Dq Fa struct timespec .
351 .Pp
352 The function
353 .Fn evCmpTime
354 compares its two
355 .Dq Fa struct timespec
356 arguments and returns an
357 .Dq Fa int
358 that is less than zero if the first argument specifies an earlier time than
359 the second, or more than zero if the first argument specifies a later time
360 than the second, or equal to zero if both arguments specify the same time.
361 .Pp
362 The function
363 .Fn evNowTime
364 returns a
365 .Dq Fa struct timespec
366 which either describes the current time
367 (using
368 .Xr clock_gettime 2 or
369 .Xr gettimeofday 2 ) ,
370 if successful, or has its fields set to zero, if there is an error.
371 (In the latter case, the caller can check
372 .Va errno ,
373 since it will be set by
374 .Xr gettimeofday 2 . )
375 The timestamp returned may not be UTC time if
376 the "monotime" option has been enabled with
377 .Fn evSetOption .
378 .Pp
379 The function
380 .Fn evUTCTime
381 is like
382 .Fn evNowTime
383 except the result is always on the UTC timescale.
384 .Pp
385 The function
386 .Fn evLastEventTime
387 returns the
388 .Dq Fa struct timespec
389 which describes the last time that certain events happened to the
390 event context indicated by
391 .Fa opaqueCtx .
392 This value is updated by
393 .Fn evCreate
394 and
395 .Fn evGetNext
396 (upon entry and after
397 .Xr select 2
398 returns); it is routinely compared with other times in the internal handling
399 of, e.g., timers.
400 .Pp
401 The function
402 .Fn evSetTimer
403 registers a timer event, which will be delivered as a function call to the
404 function specified by the
405 .Fa func
406 argument. The event will be delivered at absolute time
407 .Fa due ,
408 and then if time
409 .Fa inter
410 is not equal to
411 .Dq Fn evConsTime 0 0 ,
412 subsequently at intervals equal to time
413 .Fa inter .
414 As a special case, specifying a
415 .Fa due
416 argument equal to
417 .Dq Fn evConsTime 0 0
418 means
419 .Dq due immediately .
420 The
421 .Fa opaqueID
422 argument, if specified as a value other than
423 .Fa NULL ,
424 will be used to store the resulting
425 .Dq timer \s-1ID\s+1 ,
426 useful as an argument to
427 .Fn evClearTimer .
428 Note that in a
429 .Dq one\-shot
430 timer (which has an
431 .Fa inter
432 argument equal to
433 .Dq Fa evConsTime(0,0) )
434 the user function
435 .Fa func
436 should deallocate any dynamic memory that is uniquely bound to the
437 .Fa uap ,
438 since no handles to this memory will exist within the event library
439 after a one\-shot timer has been delivered.
440 .Pp
441 The function
442 .Fn evResetTimer
443 resets the values of the timer specified by
444 .Fa id
445 to the given arguments. The arguments are the same as in the description of
446 .Fn evSetTimer
447 above.
448 .Pp
449 The function
450 .Fn evClearTimer
451 will unregister the timer event specified by
452 .Fa id .
453 Note that if the
454 .Fa uap
455 specified in the corresponding
456 .Fn evSetTimer
457 call is uniquely bound to any dynamic memory, then that dynamic memory should
458 be freed by the caller before the handle is lost. After a call to
459 .Fn evClearTimer ,
460 no handles to this
461 .Fa uap
462 will exist within the event library.
463 .Pp
464 The function
465 .Fn evConfigTimer
466 can be used to manipulate other aspects of a timer.
467 Currently two modes are defined "rate" and "interval" which affect the
468 way recurrent timers are scheduled.
469 The default mode is "interval" where the event gets scheduled
470 .Fa inter
471 after last time it was run.
472 If mode "rate" is selected the event gets scheduled
473 .Fa inter
474 after last time it was scheduled.
475 For both "rate" and "interval" the numerical argument
476 .Fa value
477 is ignored.
478 .Pp
479 The function
480 .Fn evSetIdleTimer
481 is similar to (and built on)
482 .Fn evSetTimer ;
483 it registers an idle timer event which provides for the function call to
484 .Fa func
485 to occur. However, for an
486 .Em idle
487 timer, the call will occur after at least
488 .Dq Fa max_idle
489 time has passed since the time the idle timer was
490 .Dq last touched ;
491 originally, this is set to the time returned by
492 .Fn evLastEventTime
493 (described above) for the event context specified by
494 .Fa opaqueCtx .
495 This is a
496 .Dq one\-shot
497 timer, but the time at which the
498 .Fa func
499 is actually called can be changed by recourse to
500 .Fn evTouchIdleTimer
501 (described below). The pointer to the underlying
502 .Dq timer \s-1ID\s+1
503 is returned in
504 .Fa opaqueID ,
505 if it is
506 .No non- Ns Dv NULL .
507 .Pp
508 The
509 .Fn evTouchIdleTimer
510 function updates the idle timer associated with
511 .Fa id ,
512 setting its idea of the time it was last accessed to the value returned by
513 .Fn evLastEventTime
514 (described above) for the event context specified by
515 .Fa opaqueCtx .
516 This means that the idle timer will expire after at least
517 .Fa max_idle
518 time has passed since this (possibly new) time, providing a caller mechanism
519 for resetting the call to the
520 .Fa func
521 associated with the idle timer. (See the description of
522 .Fn evSetIdleTimer ,
523 above, for information about
524 .Fa func
525 and
526 .Fa max_idle . )
527 .Pp
528 The
529 .Fn evResetIdleTimer
530 function reschedules a timer and resets the callback function and its argument.
531 Note that resetting a timer also ``touches'' it.
532 .Pp
533 The
534 .Fn evClearIdleTimer
535 function unregisters the idle timer associated with
536 .Fa id .
537 See the discussion under
538 .Fn evClearTimer ,
539 above, for information regarding caller handling of the
540 .Fa uap
541 associated with the corresponding
542 .Fn evSetIdleTimer
543 call.
544 .Pp
545 The function
546 .Fn evWaitFor
547 places the function
548 .Fa func
549 on the given event context's wait queue with the associated (possibly
550 .Dv NULL )
551 .Dq Fa tag ;
552 if
553 .Fa id
554 is
555 .No non- Ns Dv NULL ,
556 then it will contain the
557 .Dq wait \s-1ID\s+1
558 associated with the created queue element.
559 .Pp
560 The function
561 .Fn evDo
562 marks
563 .Em all
564 of the
565 .Dq waiting
566 functions in the given event context's wait queue with the associated (possibly
567 .Dv NULL )
568 .Dq Fa tag
569 as runnable. This places these functions in a
570 .Dq done
571 queue which will be read by
572 .Fn evGetNext .
573 .Pp
574 The function
575 .Fn evUnwait
576 will search for the
577 .Dq wait \s-1ID\s+1
578 .Fa id
579 in the wait queue of the given event context; if an element with the given
580 .Fa id
581 is not found, then the
582 .Dq done
583 queue of that context is searched. If found, the queue element is removed
584 from the appropriate list.
585 .Pp
586 The function
587 .Fn evDefer
588 causes a function (specified as
589 .Fa func ,
590 with argument
591 .Fa uap )
592 to be dispatched at some later time. Note that the
593 .Fa tag
594 argument to
595 .Fa func
596 will always be
597 .Fa NULL
598 when dispatched.
599 .Pp
600 The function
601 .Fn evSelectFD
602 registers a file I/O event for the file descriptor specified by
603 .Fa fd .
604 Bits in the
605 .Fa eventmask
606 argument are named
607 .Fa EV_READ ,
608 .Fa EV_WRITE ,
609 and
610 .Fa EV_EXCEPT .
611 At least one of these bits must be specified. If the
612 .Fa id
613 argument is not equal to
614 .Fa NULL ,
615 it will be used to store a unique ``file event \s-1ID\s+1'' for this event,
616 which is useful in subsequent calls to
617 .Fn evDeselectFD .
618 A file descriptor will be made nonblocking using the
619 .Fa O_NONBLOCK
620 flag with
621 .Xr fcntl 2
622 on its first concurrent registration via
623 .Fn evSelectFD .
624 An
625 .Fn evSelectFD
626 remains in effect until cancelled via
627 .Fn evDeselectFD .
628 .Pp
629 The function
630 .Fn evDeselectFD
631 unregisters the ``file event'' specified by the
632 .Fa id
633 argument. If the corresponding
634 .Fa uap
635 uniquely points to dynamic memory, that memory should be freed before its
636 handle is lost, since after a call to
637 .Fn evDeselectFD ,
638 no handles to this event's
639 .Fa uap
640 will remain within the event library. A file descriptor will be taken out of
641 nonblocking mode (see
642 .Fa O_NONBLOCK
643 and
644 .Xr fcntl 2 )
645 when its last event registration is removed via
646 .Fn evDeselectFD ,
647 if it was in blocking mode before the first registration via
648 .Fn evSelectFD .
649 .Pp
650 The function
651 .Fn evConsIovec
652 is a constructor for a single
653 .Ft struct iovec
654 structure, which is useful for
655 .Fn evWrite
656 and
657 .Fn evRead .
658 .Pp
659 The functions
660 .Fn evWrite
661 and
662 .Fn evRead
663 start asynchronous stream I/O operations on file descriptor
664 .Fa fd .
665 The data to be written or read is in the scatter/gather descriptor specified by
666 .Fa iov
667 and
668 .Fa cnt .
669 The supplied function
670 .Fa func
671 will be called with argument
672 .Fa uap
673 when the I/O operation is complete. If
674 .Fa id
675 is not
676 .Fa NULL ,
677 it will be filled a with the stream event identifier suitable for use with
678 .Fn evCancelRW .
679 .Pp
680 The function
681 .Fn evCancelRW
682 extinguishes an outstanding
683 .Fn evWrite
684 or
685 .Fn evRead
686 call. System I/O calls cannot always be cancelled, but you are guaranteed
687 that the
688 .Fa func
689 function supplied to
690 .Fn evWrite
691 or
692 .Fn evRead
693 will not be called after a call to
694 .Fn evCancelRW .
695 Care should be taken not to deallocate or otherwise reuse the space pointed
696 to by the segment descriptors in
697 .Fa iov
698 unless the underlying file descriptor is closed first.
699 .Pp
700 The function
701 .Fn evTimeRW
702 sets the stream associated with the given stream \s-1ID\s+1
703 .Dq Fa id
704 to have the idle timer associated with the timer \s-1ID\s+1
705 .Dq Fa timer .
706 .Pp
707 The function
708 .Fn evUntimeRW
709 says that the stream associated with the given stream \s-1ID\s+1
710 .Dq Fa id
711 should ignore its idle timer, if present.
712 .Pp
713 The functions
714 .Fn evListen ,
715 .Fn evConnect ,
716 and
717 .Fn evCancelConn
718 can be used to manage asynchronous incoming and outgoing socket connections.
719 Sockets to be used with these functions should first be created with
720 .Xr socket 2
721 and given a local name with
722 .Xr bind 2 .
723 It is extremely unlikely that the same socket will ever be
724 useful for both incoming and outgoing connections. The
725 .Fa id
726 argument to
727 .Fn evListen
728 and
729 .Fn evConnect
730 is either
731 .Fa NULL
732 or the address of a
733 .Ft evFileID
734 variable which can then be used in a subsequent call to
735 .Fn evCancelConn .
736 .Pp
737 After a call to
738 .Fn evListen ,
739 each incoming connection arriving on
740 .Fa fd
741 will cause
742 .Fa func
743 to be called with
744 .Fa uap
745 as one of its arguments.
746 .Fn evConnect
747 initiates an outgoing connection on
748 .Fa fd
749 to destination address
750 .Fa ra
751 (whose length is
752 .Fa ralen ) .
753 When the connection is complete,
754 .Fa func
755 will be called with
756 .Fa uap
757 as one of its arguments. The argument
758 .Fa fd
759 to
760 .Fn \*(lp*func\*(rp
761 will be
762 .Fa -1
763 if an error occurred that prevented this connection from completing
764 successfully. In this case
765 .Fn errno
766 will have been set and the socket described by
767 .Fa fd
768 will have been closed. The
769 .Fn evCancelConn
770 function will prevent delivery of all pending and subsequent
771 events for the outstanding connection. The
772 .Fn evHold
773 function will suspend the acceptance of new connections on the listener
774 specified by
775 .Fa id .
776 Connections will be queued by the protocol stack up to the system's limit. The
777 .Fn evUnhold
778 function will reverse the effects of
779 .Fn evHold ,
780 allowing incoming connections to be delivered for listener
781 .Fa id .
782 The
783 .Fn evTryAccept
784 function will poll the listener specified by
785 .Fa id ,
786 accepting a new connection if one is available, and queuing a connection event
787 for later retrieval by
788 .Fn evGetNext .
789 If the connection event queued is an accept error(), sys_errno will contain
790 the error code; otherwise it will be zero. All connection events queued by
791 .Fn evTryAccept
792 will be delivered by
793 .Fn evGetNext
794 before a new select is done on the listener.
795 .Pp
796 The function
797 .Fn evSetDebug
798 sets the debugging
799 .Fa level
800 and diagnostic
801 .Fa output
802 file handle for an event context. Greater numeric levels will
803 result in more verbose output being sent to the output FILE during program
804 execution.
805 .Pp
806 The function
807 .Fn evPrintf
808 prints a message with the format
809 .Dq Fa fmt
810 and the following arguments (if any), on the output stream associated
811 with the event context pointed to by
812 .Fa ctx .
813 The message is output if the event context's debug level is greater than
814 or equal to the indicated
815 .Fa level .
816 .Pp
817 The function
818 .Fn evInitID
819 will initialize an opaque
820 .Dq evConn \s-1ID\s+1 ,
821 .Dq evFile \s-1ID\s+1 ,
822 .Dq evStream \s-1ID\s+1 ,
823 .Dq evTimer \s-1ID\s+1 ,
824 .Dq evWait \s-1ID\s+1 ,
825 .Dq evContext ,
826 or
827 .Dq evEvent ,
828 which is passed by reference to a state which
829 .Fn evTestID
830 will recognize.
831 This is useful to make a handle as "not in use".
832 .Pp
833 The function
834 .Fn evTestID
835 will examine an opaque \s-1ID\s+1 and return
836 .Dq TRUE
837 only if it is not in its initialized state.
838 .Pp
839 The functions
840 .Fn evGetOption
841 and
842 .Fn evSetOption
843 can be used to inspect and modify options.
844 Currently there is only one option, "monotime" and it is global for all
845 instances of eventlib so the ctx argument must be passed as NULL.
846 .Pp
847 The default value for the "monotime" option is zero which selects
848 the UTC timescale.
849 When set to a value of one, eventlib will use the
850 CLOCK_MONOTONIC timescale from
851 .Xr clock_gettime
852 instead.
853 The CLOCK_MONOTONIC timescale is never stepped and should
854 run at a rate as close to TAI as possible, so it is unaffected
855 when the system clock is set.
856 If timerevents should run at a predictable rate, set the value
857 to one, of they should run at a predictable time of day, leave
858 it at zero.
859 If the CLOCK_MONOTONIC timescale is not available on the system,
860 attempts to set/get this option will fail.
861 .Sh RETURN VALUES
862 All the functions whose return type is
863 .Dq Fa int
864 use the standard convention of returning zero (0) to indicate success, or
865 returning
866 .Dq Fa -1
867 and setting
868 .Fa errno
869 to indicate failure.
870 .Sh FILE
871 .Pa heap.h ,
872 which is in the
873 .Pa src/lib/isc
874 directory of the current
875 .Sy BIND
876 distribution.
877 .Sh ERRORS
878 The possible values for
879 .Fa errno
880 when one of the
881 .Dq Fa int
882 functions in this library returns
883 .Dq Fa -1
884 include those of the Standard C Library and also:
885 .Bl -tag -width EWOULDBLOCKAA
886 .It Bq Er EINVAL
887 Some function argument has an unreasonable value.
888 .It Bq Er EINVAL
889 The specified file descriptor has an integer value greater than the default
890 .Fa FD_SETSIZE ,
891 meaning that the application's limit is higher than the library's.
892 .It Bq Er ENOENT
893 The specified
894 .Dq event \s-1ID\s+1
895 does not exist.
896 .It Bq Er EWOULDBLOCK
897 No events have occurred and the
898 .Fa EV_POLL
899 option was specified.
900 .It Bq Er EBADF
901 The specified signal was unblocked outside the library.
902 .El
903 .Sh SEE ALSO
904 .Xr gettimeofday 2 ,
905 .Xr select 2 ,
906 .Xr fcntl 3 ,
907 .Xr malloc 3 ,
908 .Xr @INDOT@named @SYS_OPS_EXT@ ,
909 .Xr readv 3 ,
910 .Xr writev 3 .
911 .Sh BUGS
912 This huge man page needs to be broken up into a handful of smaller ones.
913 .Sh HISTORY
914 The
915 .Nm eventlib
916 library was designed by Paul Vixie with excellent advice from his friends
917 and with tips 'o the cap to the X Consortium and the implementors of DEC SRC
918 Modula-3.