chiark - git - mdw - mLib/blob - sel/selbuf.3.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for event-driven line buffer
   4 .\"
   5 .\" (c) 1999--2002, 2005, 2009, 2023, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH selbuf 3mLib "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @selbuf_enable
  33 .\" @selbuf_disable
  34 .\" @selbuf_setsize
  35 .\" @selbuf_init
  36 .\" @selbuf_destroy
  37 .
  38 .\"--------------------------------------------------------------------------
  39 .SH NAME
  40 selbuf \- line-buffering input selector
  41 .
  42 .\"--------------------------------------------------------------------------
  43 .SH SYNOPSIS
  44 .
  45 .nf
  46 .B "#include <mLib/selbuf.h>"
  47 .PP
  48 .B "typedef struct { ...\& } selbuf;"
  49 .PP
  50 .BI "void selbuf_enable(selbuf *" b );
  51 .BI "void selbuf_disable(selbuf *" b );
  52 .BI "void selbuf_setsize(selbuf *" b ", size_t " sz );
  53 .ta \w'\fBvoid selbuf_init('u
  54 .BI "void selbuf_init(selbuf *" b ", sel_state *" s ", int " fd ,
  55 .BI "   lbuf_func *" func ", void *" p );
  56 .BI "void selbuf_destroy(selbuf *" b );
  57 .fi
  58 .
  59 .\"--------------------------------------------------------------------------
  60 .SH DESCRIPTION
  61 The
  62 .B selbuf
  63 subsystem is a selector which integrates with the
  64 .BR sel (3)
  65 system for I/O multiplexing.  It reads entire text lines from a file
  66 descriptor and passes them to a caller-defined function.  It uses the
  67 line buffer described in
  68 .BR lbuf (3)
  69 to do its work: you should read about it in order to understand exactly
  70 what gets considered to be a line of text and what doesn't, and the
  71 exact rules about what your line handling function should and shouldn't
  72 do.
  73 .PP
  74 The data for a line selector is stored in an object of type
  75 .BR selbuf .
  76 This object must be allocated by the caller, and initialized using the
  77 .B selbuf_init
  78 function.  This requires a fair few arguments:
  79 .TP
  80 .BI "selbuf *" b
  81 Pointer to the
  82 .B selbuf
  83 object to initialize.
  84 .TP
  85 .BI "sel_state *" s
  86 Pointer to a multiplexor object (type
  87 .BR sel_state )
  88 to which this selector should be attached.  See
  89 .BR sel (3)
  90 for more details about multiplexors, and how this whole system works.
  91 .TP
  92 .BI "int " fd
  93 The file descriptor of the stream the selector should read from.
  94 .TP
  95 .BI "lbuf_func *" func
  96 The
  97 .I "line handler"
  98 function.  It is passed a pointer to each line read from the file (or
  99 null to indicate end-of-file), the length of the line, and an arbitrary
 100 pointer (the
 101 .I p
 102 argument to
 103 .B selbuf_init
 104 described below).  For full details, see
 105 .BR lbuf (3).
 106 .TP
 107 .BI "void *" p
 108 A pointer argument passed to
 109 .I func
 110 for each line read from the file.  Apart from this, the pointer is not
 111 used at all.
 112 .PP
 113 The
 114 .B selbuf
 115 selector is immediately active.  Subsequent calls to
 116 .B sel_select
 117 on the same multiplexor will cause any complete lines read from the file
 118 to be passed to your handling function.  This function can at any time
 119 call
 120 .B selbuf_disable
 121 to stop itself from being called any more.  The selector is then
 122 disengaged from the I/O multiplexor and won't do anything until
 123 .B selbuf_enable
 124 is called.  Note that
 125 .B selbuf_enable
 126 may well immediately start emitting complete lines of text which were
 127 queued up from the last I/O operation: it doesn't necessarily wait for
 128 the next
 129 .B sel_select
 130 call.
 131 .PP
 132 The line buffer has a finite amount of memory for reading strings.  The
 133 size of this buffer is set by calling
 134 .B selbuf_setsize
 135 with the requested size.  The default buffer size is 256 bytes.
 136 .PP
 137 When it's finished with, a line buffer selector must be destroyed by
 138 calling
 139 .BR selbuf_destroy .
 140 .
 141 .\"--------------------------------------------------------------------------
 142 .SH "SEE ALSO"
 143 .
 144 .BR lbuf (3),
 145 .BR sel (3),
 146 .BR mLib (3).
 147 .
 148 .\"--------------------------------------------------------------------------
 149 .SH AUTHOR
 150 .
 151 Mark Wooding, <mdw@distorted.org.uk>
 152 .
 153 .\"----- That's all, folks --------------------------------------------------