New function `sel_force' to force a descriptor to be `selected'.

[mLib] / man / sel.3

diff --git a/man/sel.3 b/man/sel.3
index e1dd9ee57e82fdc733f4ab8cda22a5a48d2f6306..8af80f007b5641e151f820954d7a3356f0143230 100644 (file)
--- a/man/sel.3
+++ b/man/sel.3
@@ -5,6 +5,7 @@ sel \- low level interface for waiting for I/O
 .\" @sel_init
 .\" @sel_initfile
 .\" @sel_addfile
+.\" @sel_force
 .\" @sel_rmfile
 .\" @sel_addtimer
 .\" @sel_rmtimer
@@ -23,6 +24,7 @@ sel \- low level interface for waiting for I/O
 .BI "                  void (*" func ")(int " fd ", unsigned " mode ", void *" p ),
 .BI "                  void *" p );
 .BI "void sel_addfile(sel_file *" f );
+.BI "void sel_force(sel_file *" f );
 .BI "void sel_rmfile(sel_file *" f );
 
 .BI "void sel_addtimer(sel_state *" s ", sel_timer *" t ,
@@ -110,6 +112,7 @@ interface.  For examples, see
 and
 .BR conn (3).
 .SH "PROGRAMMING INTERFACE"
+.SS "Multiplexors"
 A multiplexor is represented using the type
 .B sel_state
 defined in the
@@ -129,7 +132,7 @@ initialization, addition to multiplexor, and removal from a
 multiplexor.  It's convenient to separate addition and removal from
 initialization because file selectors often get added and removed many
 times over during their lifetimes.
-.PP
+.SS "File selectors"
 A file selector is initialized by the
 .B sel_initfile
 function.  This requires a large number of arguments:
@@ -192,6 +195,16 @@ the file descriptor for the file, a mode argument which describes the
 file's new condition, and the pointer argument set up at initialization
 time.
 .PP
+The function
+.B sel_force
+will sometimes be useful while a
+.B sel_select
+call (see below) is in progress.  It marks a file selector as being
+ready even if it's not really.  This is most useful when dynamically
+adding a write selector: it's likely that the write will succeed
+immediately, so it's worth trying.  This will only work properly if
+the write is non-blocking.
+.PP
 The member
 .B fd
 of the
@@ -199,7 +212,7 @@ of the
 structure is exported.  It contains the file descriptor in which the
 selector is interested.  You may not modify this value, but it's useful
 to be able to read it out \- it saves having to keep a copy.
-.PP
+.SS "Timer selectors"
 Timer selectors are simpler.  There are only two operations provided on
 timer selectors: addition and removal.  Initialization is performed as
 part of the addition operation.
@@ -250,7 +263,7 @@ Note that timer events are a one-shot thing.  Once they've happened, the
 timer selector is removed and the event can't happen again.  This is
 normally what you want.  Removing a timer is only useful (or safe!)
 before the timer event has been sent.
-.PP
+.SS "Performing I/O"
 Finally, the function
 .B sel_select
 is passed a multiplexor object.  It waits for something interesting to
@@ -260,7 +273,7 @@ everything went according to plan,
 returns zero.  Otherwise it returns -1, and the global variable
 .B errno
 is set appropriately.
-.SH "SELECT HOOK FUNCTIONS"
+.SS "Hook functions"
 In order to interface other I/O multiplexing systems to this one, it's
 possible to register
 .I hook
@@ -373,6 +386,8 @@ though.
 .SH "SEE ALSO"
 .BR select (2),
 .BR poll (2),
+.BR conn (3),
+.BR selbuf (3),
 .BR mLib (3).
 .SH AUTHOR
 Mark Wooding, <mdw@nsict.org>