mdw@git.distorted.org.uk Git - ezmlm/blob - substdio.3

   1 .TH substdio 3
   2 .SH NAME
   3 substdio \- the Sub-Standard Input/Output Library
   4 .SH SYNTAX
   5 .B #include <substdio.h>
   6
   7 void \fBsubstdio_fdbuf\fP(&\fIs\fR,\fIop\fR,\fIfd\fR,\fIbuf\fR,\fIlen\fR);
   8
   9 int \fBsubstdio_fileno\fP(&\fIs\fR);
  10
  11 substdio \fIs\fR;
  12 .br
  13 int (*\fIop\fR)();
  14 .br
  15 int \fIfd\fR;
  16 .br
  17 char *\fIbuf\fR;
  18 .br
  19 int \fIlen\fR;
  20 .SH DESCRIPTION
  21 .B substdio
  22 is the Sub-Standard I/O Library.
  23 .B substdio
  24 contains only a few of the features of stdio;
  25 it is a fast, lightweight, low-level library,
  26 suitable for use as a component of higher-level I/O libraries.
  27
  28 The point of
  29 .B substdio
  30 is to provide buffered I/O.
  31 The basic object in
  32 .B substdio
  33 is the
  34 .B substdio
  35 structure;
  36 a
  37 .B substdio
  38 variable stores
  39 an operation,
  40 a descriptor,
  41 and
  42 a pointer into a buffer of some nonzero length.
  43 The
  44 .B substdio
  45 operations read data from the buffer,
  46 filling the buffer as necessary using the operation on the descriptor,
  47 or write data to the buffer,
  48 flushing the buffer as necessary using the operation on the descriptor.
  49 Input and output operations cannot be mixed.
  50
  51 .B substdio_fdbuf
  52 initializes a
  53 .B substdio
  54 variable.
  55 The operation is
  56 .IR op .
  57 The descriptor is
  58 .IR fd .
  59 The buffer is
  60 .IR buf ,
  61 an array of
  62 .I len
  63 chars.
  64
  65 .I op
  66 will be called as
  67 .I op\fR(\fIfd\fR,\fIx\fR,\fIn\fR).
  68 Here
  69 .I x
  70 is a pointer to an array of characters of length
  71 .IR n ;
  72 .I op
  73 must read some characters from
  74 .I fd
  75 to that array, or write some characters to
  76 .I fd
  77 from that array.
  78 The return value from
  79 .I op
  80 must be the number of characters read or written.
  81 0 characters read means end of input;
  82 0 characters written means that the write operation
  83 should be tried again immediately.
  84 On error,
  85 .I op
  86 must return -1,
  87 setting
  88 .B errno
  89 appropriately, without reading or writing anything.
  90 Most errors are returned directly to the
  91 .B substdio
  92 caller, but an error of
  93 .B error_intr
  94 means that the operation should be tried again immediately.
  95
  96 There is a
  97 .B SUBSTDIO_FDBUF
  98 macro that can be used to statically initialize a
  99 .B substdio
 100 variable:
 101
 102 .EX
 103    substdio s = SUBSTDIO_FDBUF(op,fd,buf,len);
 104 .EE
 105
 106 .B substdio_fileno
 107 returns the
 108 descriptor for an initialized
 109 .B substdio
 110 variable.
 111 .SH "SEE ALSO"
 112 substdio_in(3),
 113 substdio_out(3),
 114 substdio_copy(3),
 115 error(3)