Update manual style.

[mLib] / man / selbuf.3

diff --git a/man/selbuf.3 b/man/selbuf.3
index 386a718a47795f9878b0ea763819166d79225d94..cc7c884be3fc23b4679409b9197ff42a1cd98d2a 100644 (file)
--- a/man/selbuf.3
+++ b/man/selbuf.3
@@ -1,57 +1,62 @@
 .\" -*-nroff-*-
 .\" -*-nroff-*-

-.TH selbuf 3mLib "23 May 1999" mLib
+.TH selbuf 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"

 .SH NAME
 selbuf \- line-buffering input selector
 .SH NAME
 selbuf \- line-buffering input selector

+.\" @selbuf_enable
+.\" @selbuf_disable
+.\" @selbuf_setsize
+.\" @selbuf_init
+.\" @selbuf_destroy

 .SH SYNOPSIS
 .nf
 .B "#include <mLib/selbuf.h>"
 
 .BI "void selbuf_enable(selbuf *" b );
 .BI "void selbuf_disable(selbuf *" b );
 .SH SYNOPSIS
 .nf
 .B "#include <mLib/selbuf.h>"
 
 .BI "void selbuf_enable(selbuf *" b );
 .BI "void selbuf_disable(selbuf *" b );

+.BI "void selbuf_setsize(selbuf *" b ", size_t " sz );

 .BI "void selbuf_init(selbuf *" b ,
 .BI "                 sel_state *" s ,
 .BI "                 int " fd ,
 .BI "                 void (*" func ")(char *" s ", void *" p ),
 .BI "                 void *" p );
 .BI "void selbuf_init(selbuf *" b ,
 .BI "                 sel_state *" s ,
 .BI "                 int " fd ,
 .BI "                 void (*" func ")(char *" s ", void *" p ),
 .BI "                 void *" p );

+.BI "void selbuf_destroy(selbuf *" b );

 .fi
 .SH DESCRIPTION
 The
 .B selbuf
 subsystem is a selector which integrates with the
 .fi
 .SH DESCRIPTION
 The
 .B selbuf
 subsystem is a selector which integrates with the

-.BR sel (3mLib)
+.BR sel (3)

 system for I/O multiplexing.  It reads entire text lines from a file
 descriptor and passes them to a caller-defined function.  It uses the
 line buffer described in
 system for I/O multiplexing.  It reads entire text lines from a file
 descriptor and passes them to a caller-defined function.  It uses the
 line buffer described in

-.BR lbuf (3mLib)
+.BR lbuf (3)

 to do its work: you should read about it in order to understand exactly
 what gets considered to be a line of text and what doesn't, and the
 exact rules about what your line handling function should and shouldn't
 do.
 .PP
 to do its work: you should read about it in order to understand exactly
 what gets considered to be a line of text and what doesn't, and the
 exact rules about what your line handling function should and shouldn't
 do.
 .PP

-All the data for a
-.B selbuf
-selector is stored in an object of type
+The data for a line selector is stored in an object of type

 .BR selbuf .
 This object must be allocated by the caller, and initialized using the
 .B selbuf_init
 function.  This requires a fair few arguments:
 .TP
 .BR selbuf .
 This object must be allocated by the caller, and initialized using the
 .B selbuf_init
 function.  This requires a fair few arguments:
 .TP

-.I b
+.BI "selbuf *" b

 Pointer to the
 .B selbuf
 object to initialize.
 .TP
 Pointer to the
 .B selbuf
 object to initialize.
 .TP

-.I s
+.BI "sel_state *" s

 Pointer to a multiplexor object (type
 .BR sel_state )
 to which this selector should be attached.  See
 Pointer to a multiplexor object (type
 .BR sel_state )
 to which this selector should be attached.  See

-.BR sel (3mLib)
+.BR sel (3)

 for more details about multiplexors, and how this whole system works.
 .TP
 for more details about multiplexors, and how this whole system works.
 .TP

-.I fd
+.BI "int " fd

 The file descriptor of the stream the selector should read from.
 .TP
 The file descriptor of the stream the selector should read from.
 .TP

-.I func
+.BI "void (*" func ")(char *" s ", void *" p )

 The
 .I "line handler"
 function.  It is passed a pointer to each line read from the file (or
 The
 .I "line handler"
 function.  It is passed a pointer to each line read from the file (or


@@ -61,7 +66,7 @@ argument to
 .B selbuf_init
 described below).
 .TP
 .B selbuf_init
 described below).
 .TP

-.I p
+.BI "void *" p

 A pointer argument passed to
 .I func
 for each line read from the file.  Apart from this, the pointer is not
 A pointer argument passed to
 .I func
 for each line read from the file.  Apart from this, the pointer is not


@@ -85,5 +90,18 @@ queued up from the last I/O operation: it doesn't necessarily wait for
 the next
 .B sel_select
 call.
 the next
 .B sel_select
 call.

+.PP
+The line buffer has a finite amount of memory for reading strings.  The
+size of this buffer is set by calling
+.B selbuf_setsize
+with the requested size.  The default buffer size is 256 bytes.
+.PP
+When it's finished with, a line buffer selector must be destroyed by
+calling
+.BR selbuf_destroy .
+.SH "SEE ALSO"
+.BR lbuf (3),
+.BR sel (3),
+.BR mLib (3).

 .SH AUTHOR
 Mark Wooding, <mdw@nsict.org>
 .SH AUTHOR
 Mark Wooding, <mdw@nsict.org>