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

   1 .TH substdio_out 3
   2 .SH NAME
   3 substdio_out \- substdio output routines
   4 .SH SYNTAX
   5 .B #include <substdio.h>
   6
   7 int \fBsubstdio_put\fP(&\fIs\fR,\fIfrom\fR,\fIlen\fR);
   8 .br
   9 int \fBsubstdio_puts\fP(&\fIs\fR,\fIfrom\fR);
  10
  11 int \fBsubstdio_bput\fP(&\fIs\fR,\fIfrom\fR,\fIlen\fR);
  12 .br
  13 int \fBsubstdio_bputs\fP(&\fIs\fR,\fIfrom\fR);
  14
  15 int \fBsubstdio_flush\fP(&\fIs\fR);
  16
  17 int \fBsubstdio_putflush\fP(&\fIs\fR,\fIfrom\fR,\fIlen\fR);
  18 .br
  19 int \fBsubstdio_putsflush\fP(&\fIs\fR,\fIfrom\fR);
  20
  21 substdio \fIs\fR;
  22 .br
  23 char *\fIfrom\fR;
  24 .br
  25 int \fIlen\fR;
  26 .SH DESCRIPTION
  27 .B substdio_put
  28 writes
  29 .I len
  30 characters to
  31 .I s
  32 out of the character array
  33 .IR from .
  34 It returns 0 on success, -1 on error.
  35
  36 .B substdio_bput
  37 has the same function as
  38 .BR substdio_put .
  39 The difference is how the buffer is flushed
  40 when there isn't enough room for
  41 .I len
  42 characters:
  43 .B substdio_put
  44 flushes the buffered data before copying the new data,
  45 whereas
  46 .B substdio_bput
  47 fills the buffer with new data before flushing.
  48
  49 .B substdio_flush
  50 forces all data to be written from the internal buffer.
  51 It returns 0 on success, -1 on error.
  52
  53 .B substdio_putflush
  54 is similar to
  55 .B substdio_put
  56 followed by
  57 .BR substdio_flush ,
  58 but it avoids all internal copies.
  59
  60 .BR substdio_puts ,
  61 .BR substdio_bputs ,
  62 and
  63 .B substdio_putsflush
  64 are the same as
  65 .BR substdio_put ,
  66 .BR substdio_bput ,
  67 and
  68 .B substdio_putflush
  69 except that
  70 .I from
  71 must be a 0-terminated string of characters.
  72 The string, not including the 0, is written.
  73
  74 The
  75 .B SUBSTDIO_OUTSIZE
  76 macro is defined as a reasonably large output buffer size for
  77 .BR substdio_fdbuf .
  78 .SH "INTERNALS"
  79 When a
  80 .B substdio
  81 variable
  82 .I s
  83 is used for output,
  84 data is buffered from
  85 .I s\fB.x
  86 to
  87 .I s\fB.x\fR +
  88 .I s\fB.p\fR;
  89 there is free buffer space from
  90 to
  91 .I s\fB.x\fR +
  92 .I s\fB.p
  93 to
  94 .I s\fB.x\fR +
  95 .I s\fB.n\fR;
  96 the total buffer length is
  97 .I s\fB.n\fR.
  98 .SH "SEE ALSO"
  99 substdio(3)