contrib/bind-9.2.4rc7/lib/bind/isc/eventlib.mdoc

   1 .\" $Id: eventlib.mdoc,v 1.1.2.2 2004/03/09 09:17:35 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.