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 .B "typedef struct { ...\& } selpk;"
  15
  16 .BI "void selpk_enable(selpk *" pk );
  17 .BI "void selpk_disable(selpk *" pk );
  18 .BI "void selpk_want(selpk *" pk ", size_t " sz );
  19 .ta \w'\fBvoid selpk_init('u
  20 .BI "void selpk_init(selpk *" pk ", sel_state *" s ", int " fd ,
  21 .BI "   pkbuf_func *" func ", void *" p );
  22 .BI "void selpk_destroy(selpk *" b );
  23 .fi
  24 .SH DESCRIPTION
  25 The
  26 .B selpk
  27 subsystem is a selector which integrates with the
  28 .BR sel (3)
  29 system for I/O multiplexing.  It reads packets from a file descriptor
  30 and passes them to a caller-defined function.  It uses the packet buffer
  31 described in
  32 .BR pkbuf (3)
  33 to do its work: you should read about it in order to understand exactly
  34 how the packet buffer decides how much data is in each packet and the
  35 exact rules about what your packet handling function should and
  36 shouldn't do.
  37 .PP
  38 The data for a packet selector is stored in an object of type
  39 .BR selpk .
  40 This object must be allocated by the caller, and initialized using the
  41 .B selpk_init
  42 function.  This requires a fair few arguments:
  43 .TP
  44 .BI "selpk *" pk
  45 Pointer to the
  46 .B selpk
  47 object to initialize.
  48 .TP
  49 .BI "sel_state *" s
  50 Pointer to a multiplexor object (type
  51 .BR sel_state )
  52 to which this selector should be attached.  See
  53 .BR sel (3)
  54 for more details about multiplexors, and how this whole system works.
  55 .TP
  56 .BI "int " fd
  57 The file descriptor of the stream the selector should read from.
  58 .TP
  59 .BI "pkbuf_func *" func
  60 The
  61 .I "packet handler"
  62 function.  It is given a pointer to each packet read from the file (or
  63 null to indicate end-of-file) and an arbitrary pointer (the
  64 .I p
  65 argument to
  66 .B selpk_init
  67 described below).  See
  68 .BR pkbuf (3)
  69 for full details.
  70 .TP
  71 .BI "void *" p
  72 A pointer argument passed to
  73 .I func
  74 for each packet read from the file.  Apart from this, the pointer is not
  75 used at all.
  76 .PP
  77 The
  78 .B selpk
  79 selector is immediately active.  Subsequent calls to
  80 .B sel_select
  81 on the same multiplexor will cause any packets read from the file to be
  82 passed to your handling function.  This function can at any time call
  83 .B selpk_disable
  84 to stop itself from being called any more.  The selector is then
  85 disengaged from the I/O multiplexor and won't do anything until
  86 .B selpk_enable
  87 is called.  Note that
  88 .B selpk_enable
  89 may well immediately start emitting complete packets of text which were
  90 queued up from the last I/O operation: it doesn't necessarily wait for
  91 the next
  92 .B sel_select
  93 call.
  94 .PP
  95 The size of packets read by the buffer is set by calling
  96 .BR selpk_want .
  97 See
  98 .BR pkbuf (3)
  99 for more details about how packet buffering works.
 100 .PP
 101 When it's finished with, a packet selector must be destroyed by calling
 102 .BR selpk_destroy .
 103 .SH "SEE ALSO"
 104 .BR pkbuf (3),
 105 .BR sel (3),
 106 .BR selbuf (3),
 107 .BR mLib (3).
 108 .SH AUTHOR
 109 Mark Wooding, <mdw@distorted.org.uk>