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

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