chiark - git - mdw - mLib/blob - sel/selpk.3

   1 .\" -*-nroff-*-
   2 .TH selpk 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
   3 .SH NAME
   4 selpk \- packet-buffering input selector
   5 .\" @selpk_enable
   6 .\" @selpk_disable
   7 .\" @selpk_want
   8 .\" @selpk_init
   9 .\" @selpk_destroy
  10 .SH SYNOPSIS
  11 .nf
  12 .B "#include <mLib/selpk.h>"
  13
  14 .BI "void selpk_enable(selpk *" pk );
  15 .BI "void selpk_disable(selpk *" pk );
  16 .BI "void selpk_want(selpk *" pk ", size_t " sz );
  17 .BI "void selpk_init(selpk *" pk ", sel_state *" s ", int " fd ,
  18 .BI "                pkbuf_func *" func ", void *" p );
  19 .BI "void selpk_destroy(selpk *" b );
  20 .fi
  21 .SH DESCRIPTION
  22 The
  23 .B selpk
  24 subsystem is a selector which integrates with the
  25 .BR sel (3)
  26 system for I/O multiplexing.  It reads packets from a file descriptor
  27 and passes them to a caller-defined function.  It uses the packet buffer
  28 described in
  29 .BR pkbuf (3)
  30 to do its work: you should read about it in order to understand exactly
  31 how the packet buffer decides how much data is in each packet and the
  32 exact rules about what your packet handling function should and
  33 shouldn't do.
  34 .PP
  35 The data for a packet selector is stored in an object of type
  36 .BR selpk .
  37 This object must be allocated by the caller, and initialized using the
  38 .B selpk_init
  39 function.  This requires a fair few arguments:
  40 .TP
  41 .BI "selpk *" pk
  42 Pointer to the
  43 .B selpk
  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 "pkbuf_func *" func
  57 The
  58 .I "packet handler"
  59 function.  It is given a pointer to each packet read from the file (or
  60 null to indicate end-of-file) and an arbitrary pointer (the
  61 .I p
  62 argument to
  63 .B selpk_init
  64 described below).  See
  65 .BR pkbuf (3)
  66 for full details.
  67 .TP
  68 .BI "void *" p
  69 A pointer argument passed to
  70 .I func
  71 for each packet read from the file.  Apart from this, the pointer is not
  72 used at all.
  73 .PP
  74 The
  75 .B selpk
  76 selector is immediately active.  Subsequent calls to
  77 .B sel_select
  78 on the same multiplexor will cause any packets read from the file to be
  79 passed to your handling function.  This function can at any time call
  80 .B selpk_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 selpk_enable
  84 is called.  Note that
  85 .B selpk_enable
  86 may well immediately start emitting complete packets 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 .PP
  92 The size of packets read by the buffer is set by calling
  93 .BR selpk_want .
  94 See
  95 .BR pkbuf (3)
  96 for more details about how packet buffering works.
  97 .PP
  98 When it's finished with, a packet selector must be destroyed by calling
  99 .BR selpk_destroy .
 100 .SH "SEE ALSO"
 101 .BR pkbuf (3),
 102 .BR sel (3),
 103 .BR selbuf (3),
 104 .BR mLib (3).
 105 .SH AUTHOR
 106 Mark Wooding, <mdw@distorted.org.uk>