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

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