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

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for event-driven packet splitting
   4 .\"
   5 .\" (c) 2000--2003, 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 selpk 3mLib "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @selpk_enable
  33 .\" @selpk_disable
  34 .\" @selpk_want
  35 .\" @selpk_init
  36 .\" @selpk_destroy
  37 .
  38 .\"--------------------------------------------------------------------------
  39 .SH NAME
  40 selpk \- packet-buffering input selector
  41 .
  42 .SH SYNOPSIS
  43 .nf
  44 .B "#include <mLib/selpk.h>"
  45 .PP
  46 .B "typedef struct { ...\& } selpk;"
  47 .PP
  48 .BI "void selpk_enable(selpk *" pk );
  49 .BI "void selpk_disable(selpk *" pk );
  50 .BI "void selpk_want(selpk *" pk ", size_t " sz );
  51 .ta \w'\fBvoid selpk_init('u
  52 .BI "void selpk_init(selpk *" pk ", sel_state *" s ", int " fd ,
  53 .BI "   pkbuf_func *" func ", void *" p );
  54 .BI "void selpk_destroy(selpk *" b );
  55 .fi
  56 .
  57 .\"--------------------------------------------------------------------------
  58 .SH DESCRIPTION
  59 .
  60 The
  61 .B selpk
  62 subsystem is a selector which integrates with the
  63 .BR sel (3)
  64 system for I/O multiplexing.  It reads packets from a file descriptor
  65 and passes them to a caller-defined function.  It uses the packet buffer
  66 described in
  67 .BR pkbuf (3)
  68 to do its work: you should read about it in order to understand exactly
  69 how the packet buffer decides how much data is in each packet and the
  70 exact rules about what your packet handling function should and
  71 shouldn't do.
  72 .PP
  73 The data for a packet selector is stored in an object of type
  74 .BR selpk .
  75 This object must be allocated by the caller, and initialized using the
  76 .B selpk_init
  77 function.  This requires a fair few arguments:
  78 .TP
  79 .BI "selpk *" pk
  80 Pointer to the
  81 .B selpk
  82 object to initialize.
  83 .TP
  84 .BI "sel_state *" s
  85 Pointer to a multiplexor object (type
  86 .BR sel_state )
  87 to which this selector should be attached.  See
  88 .BR sel (3)
  89 for more details about multiplexors, and how this whole system works.
  90 .TP
  91 .BI "int " fd
  92 The file descriptor of the stream the selector should read from.
  93 .TP
  94 .BI "pkbuf_func *" func
  95 The
  96 .I "packet handler"
  97 function.  It is given a pointer to each packet read from the file (or
  98 null to indicate end-of-file) and an arbitrary pointer (the
  99 .I p
 100 argument to
 101 .B selpk_init
 102 described below).  See
 103 .BR pkbuf (3)
 104 for full details.
 105 .TP
 106 .BI "void *" p
 107 A pointer argument passed to
 108 .I func
 109 for each packet read from the file.  Apart from this, the pointer is not
 110 used at all.
 111 .PP
 112 The
 113 .B selpk
 114 selector is immediately active.  Subsequent calls to
 115 .B sel_select
 116 on the same multiplexor will cause any packets read from the file to be
 117 passed to your handling function.  This function can at any time call
 118 .B selpk_disable
 119 to stop itself from being called any more.  The selector is then
 120 disengaged from the I/O multiplexor and won't do anything until
 121 .B selpk_enable
 122 is called.  Note that
 123 .B selpk_enable
 124 may well immediately start emitting complete packets of text which were
 125 queued up from the last I/O operation: it doesn't necessarily wait for
 126 the next
 127 .B sel_select
 128 call.
 129 .PP
 130 The size of packets read by the buffer is set by calling
 131 .BR selpk_want .
 132 See
 133 .BR pkbuf (3)
 134 for more details about how packet buffering works.
 135 .PP
 136 When it's finished with, a packet selector must be destroyed by calling
 137 .BR selpk_destroy .
 138 .
 139 .\"--------------------------------------------------------------------------
 140 .SH "SEE ALSO"
 141 .
 142 .BR pkbuf (3),
 143 .BR sel (3),
 144 .BR selbuf (3),
 145 .BR mLib (3).
 146 .
 147 .\"--------------------------------------------------------------------------
 148 .SH AUTHOR
 149 .
 150 Mark Wooding, <mdw@distorted.org.uk>
 151 .
 152 .\"----- That's all, folks --------------------------------------------------