Import buf from Catacomb; split out the dstr bits, and throw away the mp and

[mLib] / man / sel.3

diff --git a/man/sel.3 b/man/sel.3
index e1dd9ee57e82fdc733f4ab8cda22a5a48d2f6306..de62ed1e6d8c9a427a586e22fcb70e8bee5fe37e 100644 (file)
--- a/man/sel.3
+++ b/man/sel.3
@@ -1,10 +1,11 @@
 .\" -*-nroff-*-
-.TH sel 3 "22 May 1999" mLib
+.TH sel 3 "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
 .SH NAME
 sel \- low level interface for waiting for I/O
 .\" @sel_init
 .\" @sel_initfile
 .\" @sel_addfile
+.\" @sel_force
 .\" @sel_rmfile
 .\" @sel_addtimer
 .\" @sel_rmtimer
@@ -23,11 +24,13 @@ 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 ,
 .BI "                  struct timeval *" tv ,
 .BI "                  void (*" func ")(struct timeval *" tv ", void *" p ),
+.BI "                  void *" p );
 .BI "void sel_rmtimer(sel_timer *" t );
 
 .BI "void sel_addhook(sel_state *" s ", sel_hook *" h ,
@@ -110,6 +113,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 +133,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 +196,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 +213,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,17 +264,17 @@ 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
 happen, informs the appropriate selector handlers, and returns.  If
 everything went according to plan,
 .B sel_select
-returns zero.  Otherwise it returns -1, and the global variable
+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 +387,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>
+Mark Wooding, <mdw@distorted.org.uk>