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