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 194This library provides multiple outstanding asynchronous timers and I/O 195to a cooperating application. The model is similar to that of the X 196Toolkit, in that events are registered with the library and the application 197spends most of its time in the 198.Fn evMainLoop 199function. If an application already has a main loop, it can safely register 200events with this library as long as it periodically calls the 201.Fn evGetNext 202and 203.Fn evDispatch 204functions. (Note that 205.Fn evGetNext 206has both polling and blocking modes.) 207.Pp 208The function 209.Fn evCreate 210creates an event context which is needed by all the other functions in this 211library. All information used internally by this library is bound to this 212context, rather than to static storage. This makes the library 213.Dq thread safe , 214and permits other library functions to use events without 215disrupting the application's use of events. 216.Pp 217The function 218.Fn evDestroy 219destroys a context that has been created by 220.Fn evCreate . 221All dynamic memory bound to this context will be freed. An implicit 222.Fn evTimerClear 223will be done on all timers set in this event context. An implicit 224.Fn evDeselectFD 225will be done on all file descriptors selected in this event context. 226.Pp 227The function 228.Fn evGetNext 229potentially waits for and then retrieves the next asynchronous event, 230placing it in the object of the 231.Fa ev 232pointer argument. The following 233.Fa options 234are available: 235.Fa EV_POLL , 236meaning that 237.Fn evGetNext 238should not block, but rather return 239.Dq Fa -1 240with 241.Fa errno 242set to 243.Fa EWOULDBLOCK 244if no events have occurred; 245.Fa EV_WAIT , 246which tells 247.Fn evGetNext 248to block internally until the next event occurs; and 249.Fa EV_NULL , 250which tells 251.Fn evGetNext 252that it should return a special 253.Dq no-op 254event, which is ignored by 255.Fn evDispatch 256but handled correctly by 257.Fn evDrop . 258.Fa EV_NULL 259can be necessary to the correct functioning of a caller\-written equivilent to 260.Fn evMainLoop , 261wherein perterbations caused by external system events must be polled for, and 262the default behaviour of internally ignoring such events is undesirable. 263Note that 264.Fa EV_POLL 265and 266.Fa EV_WAIT 267are mutually exclusive. 268.Pp 269The function 270.Fn evDispatch 271dispatches an event retrieved by 272.Fn evGetNext . 273This usually involves calling the function that was associated with the event 274when the event was registered with 275.Fn evSetTimer , 276.Fn evResetTimer , 277or 278.Fn evSelectFD . 279All events retrieved by 280.Fn evGetNext 281must be given over to 282.Fn evDispatch 283at some point, since there is some dynamic memory associated with each event. 284.Pp 285The function 286.Fn evDrop 287deallocates dynamic memory that has been allocated by 288.Fn evGetNext . 289Calling 290.Fn evDispatch 291has the side effect of calling 292.Fn evDrop , 293but if you are going to drop the event rather than dispatch it, you will have 294to call 295.Fn evDrop 296directly. 297.Pp 298The function 299.Fn evMainLoop 300is just: 301.Bd -literal -offset indent 302while ((x = evGetNext(opaqueCtx, &event, EV_WAIT)) == 0) 303 if ((x = evDispatch(opaqueCtx, event)) < 0) 304 break; 305return (x); 306.Ed 307.Pp 308In other words, get events and dispatch them until an error occurs. One such 309error would be that all the events under this context become unregistered; in 310that event, there will be nothing to wait for and 311.Fn evGetNext 312becomes an undefined operation. 313.Pp 314The function 315.Fn evConsTime 316is a constructor for 317.Dq Fa struct timespec 318which allows these structures to be created and then passed as arguments to 319other functions without the use of temporary variables. (If C had inline 320constructors, there would be no need for this function.) 321.Pp 322The functions 323.Fn evTimeSpec 324and 325.Fn evTimeVal 326are utilities which allow the caller to convert a 327.Dq Fa struct timeval 328to a 329.Dq Fa struct timespec 330(the function of 331.Fn evTimeSpec ) 332or vice versa (the function of 333.Fn evTimeVal ) . 334Note that the name of the function indicates the type of the return value. 335.Pp 336The function 337.Fn evAddTime 338adds two 339.Dq Fa struct timespec 340values and returns the result as a 341.Dq Fa struct timespec . 342.Pp 343The function 344.Fn evSubTime 345subtracts its second 346.Dq Fa struct timespec 347argument from its first 348.Dq Fa struct timespec 349argument and returns the result as a 350.Dq Fa struct timespec . 351.Pp 352The function 353.Fn evCmpTime 354compares its two 355.Dq Fa struct timespec 356arguments and returns an 357.Dq Fa int 358that is less than zero if the first argument specifies an earlier time than 359the second, or more than zero if the first argument specifies a later time 360than the second, or equal to zero if both arguments specify the same time. 361.Pp 362The function 363.Fn evNowTime 364returns a 365.Dq Fa struct timespec 366which either describes the current time 367(using 368.Xr clock_gettime 2 or 369.Xr gettimeofday 2 ) , 370if 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 , 373since it will be set by 374.Xr gettimeofday 2 . ) 375The timestamp returned may not be UTC time if 376the "monotime" option has been enabled with 377.Fn evSetOption . 378.Pp 379The function 380.Fn evUTCTime 381is like 382.Fn evNowTime 383except the result is always on the UTC timescale. 384.Pp 385The function 386.Fn evLastEventTime 387returns the 388.Dq Fa struct timespec 389which describes the last time that certain events happened to the 390event context indicated by 391.Fa opaqueCtx . 392This value is updated by 393.Fn evCreate 394and 395.Fn evGetNext 396(upon entry and after 397.Xr select 2 398returns); it is routinely compared with other times in the internal handling 399of, e.g., timers. 400.Pp 401The function 402.Fn evSetTimer 403registers a timer event, which will be delivered as a function call to the 404function specified by the 405.Fa func 406argument. The event will be delivered at absolute time 407.Fa due , 408and then if time 409.Fa inter 410is not equal to 411.Dq Fn evConsTime 0 0 , 412subsequently at intervals equal to time 413.Fa inter . 414As a special case, specifying a 415.Fa due 416argument equal to 417.Dq Fn evConsTime 0 0 418means 419.Dq due immediately . 420The 421.Fa opaqueID 422argument, if specified as a value other than 423.Fa NULL , 424will be used to store the resulting 425.Dq timer \s-1ID\s+1 , 426useful as an argument to 427.Fn evClearTimer . 428Note that in a 429.Dq one\-shot 430timer (which has an 431.Fa inter 432argument equal to 433.Dq Fa evConsTime(0,0) ) 434the user function 435.Fa func 436should deallocate any dynamic memory that is uniquely bound to the 437.Fa uap , 438since no handles to this memory will exist within the event library 439after a one\-shot timer has been delivered. 440.Pp 441The function 442.Fn evResetTimer 443resets the values of the timer specified by 444.Fa id 445to the given arguments. The arguments are the same as in the description of 446.Fn evSetTimer 447above. 448.Pp 449The function 450.Fn evClearTimer 451will unregister the timer event specified by 452.Fa id . 453Note that if the 454.Fa uap 455specified in the corresponding 456.Fn evSetTimer 457call is uniquely bound to any dynamic memory, then that dynamic memory should 458be freed by the caller before the handle is lost. After a call to 459.Fn evClearTimer , 460no handles to this 461.Fa uap 462will exist within the event library. 463.Pp 464The function 465.Fn evConfigTimer 466can be used to manipulate other aspects of a timer. 467Currently two modes are defined "rate" and "interval" which affect the 468way recurrent timers are scheduled. 469The default mode is "interval" where the event gets scheduled 470.Fa inter 471after last time it was run. 472If mode "rate" is selected the event gets scheduled 473.Fa inter 474after last time it was scheduled. 475For both "rate" and "interval" the numerical argument 476.Fa value 477is ignored. 478.Pp 479The function 480.Fn evSetIdleTimer 481is similar to (and built on) 482.Fn evSetTimer ; 483it registers an idle timer event which provides for the function call to 484.Fa func 485to occur. However, for an 486.Em idle 487timer, the call will occur after at least 488.Dq Fa max_idle 489time has passed since the time the idle timer was 490.Dq last touched ; 491originally, this is set to the time returned by 492.Fn evLastEventTime 493(described above) for the event context specified by 494.Fa opaqueCtx . 495This is a 496.Dq one\-shot 497timer, but the time at which the 498.Fa func 499is 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 503is returned in 504.Fa opaqueID , 505if it is 506.No non- Ns Dv NULL . 507.Pp 508The 509.Fn evTouchIdleTimer 510function updates the idle timer associated with 511.Fa id , 512setting 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 . 516This means that the idle timer will expire after at least 517.Fa max_idle 518time has passed since this (possibly new) time, providing a caller mechanism 519for resetting the call to the 520.Fa func 521associated with the idle timer. (See the description of 522.Fn evSetIdleTimer , 523above, for information about 524.Fa func 525and 526.Fa max_idle . ) 527.Pp 528The 529.Fn evResetIdleTimer 530function reschedules a timer and resets the callback function and its argument. 531Note that resetting a timer also ``touches'' it. 532.Pp 533The 534.Fn evClearIdleTimer 535function unregisters the idle timer associated with 536.Fa id . 537See the discussion under 538.Fn evClearTimer , 539above, for information regarding caller handling of the 540.Fa uap 541associated with the corresponding 542.Fn evSetIdleTimer 543call. 544.Pp 545The function 546.Fn evWaitFor 547places the function 548.Fa func 549on the given event context's wait queue with the associated (possibly 550.Dv NULL ) 551.Dq Fa tag ; 552if 553.Fa id 554is 555.No non- Ns Dv NULL , 556then it will contain the 557.Dq wait \s-1ID\s+1 558associated with the created queue element. 559.Pp 560The function 561.Fn evDo 562marks 563.Em all 564of the 565.Dq waiting 566functions in the given event context's wait queue with the associated (possibly 567.Dv NULL ) 568.Dq Fa tag 569as runnable. This places these functions in a 570.Dq done 571queue which will be read by 572.Fn evGetNext . 573.Pp 574The function 575.Fn evUnwait 576will search for the 577.Dq wait \s-1ID\s+1 578.Fa id 579in the wait queue of the given event context; if an element with the given 580.Fa id 581is not found, then the 582.Dq done 583queue of that context is searched. If found, the queue element is removed 584from the appropriate list. 585.Pp 586The function 587.Fn evDefer 588causes a function (specified as 589.Fa func , 590with argument 591.Fa uap ) 592to be dispatched at some later time. Note that the 593.Fa tag 594argument to 595.Fa func 596will always be 597.Fa NULL 598when dispatched. 599.Pp 600The function 601.Fn evSelectFD 602registers a file I/O event for the file descriptor specified by 603.Fa fd . 604Bits in the 605.Fa eventmask 606argument are named 607.Fa EV_READ , 608.Fa EV_WRITE , 609and 610.Fa EV_EXCEPT . 611At least one of these bits must be specified. If the 612.Fa id 613argument is not equal to 614.Fa NULL , 615it will be used to store a unique ``file event \s-1ID\s+1'' for this event, 616which is useful in subsequent calls to 617.Fn evDeselectFD . 618A file descriptor will be made nonblocking using the 619.Fa O_NONBLOCK 620flag with 621.Xr fcntl 2 622on its first concurrent registration via 623.Fn evSelectFD . 624An 625.Fn evSelectFD 626remains in effect until cancelled via 627.Fn evDeselectFD . 628.Pp 629The function 630.Fn evDeselectFD 631unregisters the ``file event'' specified by the 632.Fa id 633argument. If the corresponding 634.Fa uap 635uniquely points to dynamic memory, that memory should be freed before its 636handle is lost, since after a call to 637.Fn evDeselectFD , 638no handles to this event's 639.Fa uap 640will remain within the event library. A file descriptor will be taken out of 641nonblocking mode (see 642.Fa O_NONBLOCK 643and 644.Xr fcntl 2 ) 645when its last event registration is removed via 646.Fn evDeselectFD , 647if it was in blocking mode before the first registration via 648.Fn evSelectFD . 649.Pp 650The function 651.Fn evConsIovec 652is a constructor for a single 653.Ft struct iovec 654structure, which is useful for 655.Fn evWrite 656and 657.Fn evRead . 658.Pp 659The functions 660.Fn evWrite 661and 662.Fn evRead 663start asynchronous stream I/O operations on file descriptor 664.Fa fd . 665The data to be written or read is in the scatter/gather descriptor specified by 666.Fa iov 667and 668.Fa cnt . 669The supplied function 670.Fa func 671will be called with argument 672.Fa uap 673when the I/O operation is complete. If 674.Fa id 675is not 676.Fa NULL , 677it will be filled a with the stream event identifier suitable for use with 678.Fn evCancelRW . 679.Pp 680The function 681.Fn evCancelRW 682extinguishes an outstanding 683.Fn evWrite 684or 685.Fn evRead 686call. System I/O calls cannot always be cancelled, but you are guaranteed 687that the 688.Fa func 689function supplied to 690.Fn evWrite 691or 692.Fn evRead 693will not be called after a call to 694.Fn evCancelRW . 695Care should be taken not to deallocate or otherwise reuse the space pointed 696to by the segment descriptors in 697.Fa iov 698unless the underlying file descriptor is closed first. 699.Pp 700The function 701.Fn evTimeRW 702sets the stream associated with the given stream \s-1ID\s+1 703.Dq Fa id 704to have the idle timer associated with the timer \s-1ID\s+1 705.Dq Fa timer . 706.Pp 707The function 708.Fn evUntimeRW 709says that the stream associated with the given stream \s-1ID\s+1 710.Dq Fa id 711should ignore its idle timer, if present. 712.Pp 713The functions 714.Fn evListen , 715.Fn evConnect , 716and 717.Fn evCancelConn 718can be used to manage asynchronous incoming and outgoing socket connections. 719Sockets to be used with these functions should first be created with 720.Xr socket 2 721and given a local name with 722.Xr bind 2 . 723It is extremely unlikely that the same socket will ever be 724useful for both incoming and outgoing connections. The 725.Fa id 726argument to 727.Fn evListen 728and 729.Fn evConnect 730is either 731.Fa NULL 732or the address of a 733.Ft evFileID 734variable which can then be used in a subsequent call to 735.Fn evCancelConn . 736.Pp 737After a call to 738.Fn evListen , 739each incoming connection arriving on 740.Fa fd 741will cause 742.Fa func 743to be called with 744.Fa uap 745as one of its arguments. 746.Fn evConnect 747initiates an outgoing connection on 748.Fa fd 749to destination address 750.Fa ra 751(whose length is 752.Fa ralen ) . 753When the connection is complete, 754.Fa func 755will be called with 756.Fa uap 757as one of its arguments. The argument 758.Fa fd 759to 760.Fn \*(lp*func\*(rp 761will be 762.Fa -1 763if an error occurred that prevented this connection from completing 764successfully. In this case 765.Fn errno 766will have been set and the socket described by 767.Fa fd 768will have been closed. The 769.Fn evCancelConn 770function will prevent delivery of all pending and subsequent 771events for the outstanding connection. The 772.Fn evHold 773function will suspend the acceptance of new connections on the listener 774specified by 775.Fa id . 776Connections will be queued by the protocol stack up to the system's limit. The 777.Fn evUnhold 778function will reverse the effects of 779.Fn evHold , 780allowing incoming connections to be delivered for listener 781.Fa id . 782The 783.Fn evTryAccept 784function will poll the listener specified by 785.Fa id , 786accepting a new connection if one is available, and queuing a connection event 787for later retrieval by 788.Fn evGetNext . 789If the connection event queued is an accept error(), sys_errno will contain 790the error code; otherwise it will be zero. All connection events queued by 791.Fn evTryAccept 792will be delivered by 793.Fn evGetNext 794before a new select is done on the listener. 795.Pp 796The function 797.Fn evSetDebug 798sets the debugging 799.Fa level 800and diagnostic 801.Fa output 802file handle for an event context. Greater numeric levels will 803result in more verbose output being sent to the output FILE during program 804execution. 805.Pp 806The function 807.Fn evPrintf 808prints a message with the format 809.Dq Fa fmt 810and the following arguments (if any), on the output stream associated 811with the event context pointed to by 812.Fa ctx . 813The message is output if the event context's debug level is greater than 814or equal to the indicated 815.Fa level . 816.Pp 817The function 818.Fn evInitID 819will 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 , 826or 827.Dq evEvent , 828which is passed by reference to a state which 829.Fn evTestID 830will recognize. 831This is useful to make a handle as "not in use". 832.Pp 833The function 834.Fn evTestID 835will examine an opaque \s-1ID\s+1 and return 836.Dq TRUE 837only if it is not in its initialized state. 838.Pp 839The functions 840.Fn evGetOption 841and 842.Fn evSetOption 843can be used to inspect and modify options. 844Currently there is only one option, "monotime" and it is global for all 845instances of eventlib so the ctx argument must be passed as NULL. 846.Pp 847The default value for the "monotime" option is zero which selects 848the UTC timescale. 849When set to a value of one, eventlib will use the 850CLOCK_MONOTONIC timescale from 851.Xr clock_gettime 852instead. 853The CLOCK_MONOTONIC timescale is never stepped and should 854run at a rate as close to TAI as possible, so it is unaffected 855when the system clock is set. 856If timerevents should run at a predictable rate, set the value 857to one, of they should run at a predictable time of day, leave 858it at zero. 859If the CLOCK_MONOTONIC timescale is not available on the system, 860attempts to set/get this option will fail. 861.Sh RETURN VALUES 862All the functions whose return type is 863.Dq Fa int 864use the standard convention of returning zero (0) to indicate success, or 865returning 866.Dq Fa -1 867and setting 868.Fa errno 869to indicate failure. 870.Sh FILE 871.Pa heap.h , 872which is in the 873.Pa src/lib/isc 874directory of the current 875.Sy BIND 876distribution. 877.Sh ERRORS 878The possible values for 879.Fa errno 880when one of the 881.Dq Fa int 882functions in this library returns 883.Dq Fa -1 884include those of the Standard C Library and also: 885.Bl -tag -width EWOULDBLOCKAA 886.It Bq Er EINVAL 887Some function argument has an unreasonable value. 888.It Bq Er EINVAL 889The specified file descriptor has an integer value greater than the default 890.Fa FD_SETSIZE , 891meaning that the application's limit is higher than the library's. 892.It Bq Er ENOENT 893The specified 894.Dq event \s-1ID\s+1 895does not exist. 896.It Bq Er EWOULDBLOCK 897No events have occurred and the 898.Fa EV_POLL 899option was specified. 900.It Bq Er EBADF 901The 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 912This huge man page needs to be broken up into a handful of smaller ones. 913.Sh HISTORY 914The 915.Nm eventlib 916library was designed by Paul Vixie with excellent advice from his friends 917and with tips 'o the cap to the X Consortium and the implementors of DEC SRC 918Modula-3. 919