chiark - git - mdw - mLib/blob - man/selbuf.3

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