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