mdw@git.distorted.org.uk Git - mLib/blob - sel/selbuf.3

   1 .\" -*-nroff-*-
   2 .TH selbuf 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
   3 .SH NAME
   4 selbuf \- line-buffering input selector
   5 .\" @selbuf_enable
   6 .\" @selbuf_disable
   7 .\" @selbuf_setsize
   8 .\" @selbuf_init
   9 .\" @selbuf_destroy
  10 .SH SYNOPSIS
  11 .nf
  12 .B "#include <mLib/selbuf.h>"
  13
  14 .BI "void selbuf_enable(selbuf *" b );
  15 .BI "void selbuf_disable(selbuf *" b );
  16 .BI "void selbuf_setsize(selbuf *" b ", size_t " sz );
  17 .ds mT \fBvoid selbuf_init(
  18 .BI "\*(mTselbuf *" b ", sel_state *" s ", int " fd ,
  19 .BI "\h'\w'\*(mT'u'lbuf_func *" func ", void *" p );
  20 .BI "void selbuf_destroy(selbuf *" b );
  21 .fi
  22 .SH DESCRIPTION
  23 The
  24 .B selbuf
  25 subsystem is a selector which integrates with the
  26 .BR sel (3)
  27 system for I/O multiplexing.  It reads entire text lines from a file
  28 descriptor and passes them to a caller-defined function.  It uses the
  29 line buffer described in
  30 .BR lbuf (3)
  31 to do its work: you should read about it in order to understand exactly
  32 what gets considered to be a line of text and what doesn't, and the
  33 exact rules about what your line handling function should and shouldn't
  34 do.
  35 .PP
  36 The data for a line selector is stored in an object of type
  37 .BR selbuf .
  38 This object must be allocated by the caller, and initialized using the
  39 .B selbuf_init
  40 function.  This requires a fair few arguments:
  41 .TP
  42 .BI "selbuf *" b
  43 Pointer to the
  44 .B selbuf
  45 object to initialize.
  46 .TP
  47 .BI "sel_state *" s
  48 Pointer to a multiplexor object (type
  49 .BR sel_state )
  50 to which this selector should be attached.  See
  51 .BR sel (3)
  52 for more details about multiplexors, and how this whole system works.
  53 .TP
  54 .BI "int " fd
  55 The file descriptor of the stream the selector should read from.
  56 .TP
  57 .BI "lbuf_func *" func
  58 The
  59 .I "line handler"
  60 function.  It is passed a pointer to each line read from the file (or
  61 null to indicate end-of-file), the length of the line, and an arbitrary
  62 pointer (the
  63 .I p
  64 argument to
  65 .B selbuf_init
  66 described below).  For full details, see
  67 .BR lbuf (3).
  68 .TP
  69 .BI "void *" p
  70 A pointer argument passed to
  71 .I func
  72 for each line read from the file.  Apart from this, the pointer is not
  73 used at all.
  74 .PP
  75 The
  76 .B selbuf
  77 selector is immediately active.  Subsequent calls to
  78 .B sel_select
  79 on the same multiplexor will cause any complete lines read from the file
  80 to be passed to your handling function.  This function can at any time
  81 call
  82 .B selbuf_disable
  83 to stop itself from being called any more.  The selector is then
  84 disengaged from the I/O multiplexor and won't do anything until
  85 .B selbuf_enable
  86 is called.  Note that
  87 .B selbuf_enable
  88 may well immediately start emitting complete lines of text which were
  89 queued up from the last I/O operation: it doesn't necessarily wait for
  90 the next
  91 .B sel_select
  92 call.
  93 .PP
  94 The line buffer has a finite amount of memory for reading strings.  The
  95 size of this buffer is set by calling
  96 .B selbuf_setsize
  97 with the requested size.  The default buffer size is 256 bytes.
  98 .PP
  99 When it's finished with, a line buffer selector must be destroyed by
 100 calling
 101 .BR selbuf_destroy .
 102 .SH "SEE ALSO"
 103 .BR lbuf (3),
 104 .BR sel (3),
 105 .BR mLib (3).
 106 .SH AUTHOR
 107 Mark Wooding, <mdw@distorted.org.uk>