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