src/pthr_iolib.h

   1 /* A small buffered I/O library.
   2  * - by Richard W.M. Jones <rich@annexia.org>.
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the Free
  16  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17  *
  18  * $Id: pthr_iolib.h,v 1.5 2002/12/01 14:29:28 rich Exp $
  19  */
  20
  21 #ifndef PTHR_IOLIB_H
  22 #define PTHR_IOLIB_H
  23
  24 #include <stdlib.h>
  25 #include <stdarg.h>
  26
  27 #include <setjmp.h>
  28
  29 #include <pool.h>
  30
  31 #include "pthr_pseudothread.h"
  32
  33 #define IOLIB_INPUT_BUFFER_SIZE 1024
  34 #define IOLIB_OUTPUT_BUFFER_SIZE 1024
  35
  36 struct io_handle;
  37 typedef struct io_handle *io_handle;
  38
  39 /* Buffer modes. */
  40 #define IO_MODE_LINE_BUFFERED  0 /* Default. */
  41 #define IO_MODE_UNBUFFERED     1
  42 #define IO_MODE_FULLY_BUFFERED 2
  43
  44 /* Function: io_fdopen - A buffered I/O library
  45  * Function: io_fclose
  46  * Function: io_fgetc
  47  * Function: io_fgets
  48  * Function: io_ungetc
  49  * Function: io_fread
  50  * Function: io_fputc
  51  * Function: io_fputs
  52  * Function: io_fprintf
  53  * Function: io_fwrite
  54  * Function: io_fflush
  55  * Function: io_fileno
  56  * Function: io_popen
  57  * Function: io_pclose
  58  * Function: io_copy
  59  * Function: io_setbufmode
  60  * Function: io_get_inbufcount
  61  * Function: io_get_outbufcount
  62  *
  63  * The @code{io_*} functions replace the normal blocking C library
  64  * @code{f*} functions with equivalents which work on non-blocking
  65  * pseudothread file descriptors.
  66  *
  67  * All of the functions in the synopsis above work identically
  68  * to the C library equivalents, except where documented below.
  69  *
  70  * @code{io_fdopen} associates a socket @code{sock} with a
  71  * I/O handle. The association cannot be broken later (so use
  72  * @ref{dup(2)} if you wish to later take back control of the
  73  * underlying socket). If either the current thread exits
  74  * or @code{io_fclose} is called, the underlying socket is
  75  * closed (with @ref{close(2)}).
  76  *
  77  * @code{io_fclose} flushes all unwritten data out of the socket
  78  * and closes it.
  79  *
  80  * @code{io_fgets} operates similarly to the ordinary C library
  81  * function @ref{fgets(3)}, except that it contains a useful
  82  * fourth argument, @code{store_eol}. If this fourth argument is
  83  * false, then the end of line characters (@code{CR}, @code{CR LF}
  84  * or @code{LF}) are stripped from the string before it is stored.
  85  *
  86  * @code{io_copy} copies @code{len} bytes from @code{from_io}
  87  * to @code{to_io}. If @code{len} equals -1 then bytes are
  88  * copied from @code{from_io} until end of file is reached.
  89  * If @code{len} equals 0, then no bytes are copied. The
  90  * number of bytes actually copied is returned.
  91  *
  92  * @code{io_setbufmode} sets the output buffer mode, and works
  93  * completely differently to the ordinary C library function
  94  * @ref{setbufmode(3)}. The three mode arguments possible are:
  95  * @code{IO_MODE_LINE_BUFFERED}, @code{IO_MODE_UNBUFFERED} and
  96  * @code{IO_MODE_FULLY_BUFFERED}, and these correspond to line
  97  * buffering, no buffering and full (block) buffering.
  98  *
  99  * @code{io_get_inbufcount} and @code{io_get_outbufcount} return
 100  * the number of characters read and written on the socket since
 101  * the socket was associated with the I/O object.
 102  *
 103  * See also:
 104  * @ref{fgetc(3)},
 105  * @ref{fgets(3)},
 106  * @ref{ungetc(3)},
 107  * @ref{fread(3)},
 108  * @ref{fputc(3)},
 109  * @ref{fputs(3)},
 110  * @ref{fprintf(3)},
 111  * @ref{fwrite(3)},
 112  * @ref{fflush(3)},
 113  * @ref{fileno(3)},
 114  * @ref{popen(3)},
 115  * @ref{pclose(3)},
 116  * @ref{pth_exit(3)}.
 117  */
 118 extern io_handle io_fdopen (int sock);
 119 extern void io_fclose (io_handle);
 120 extern int io_fgetc (io_handle);
 121 extern char *io_fgets (char *s, int max_size, io_handle, int store_eol);
 122 extern int io_ungetc (int c, io_handle);
 123 extern size_t io_fread (void *ptr, size_t size, size_t nmemb, io_handle);
 124 extern int io_fputc (int c, io_handle);
 125 extern int io_fputs (const char *s, io_handle);
 126 extern int io_fprintf (io_handle, const char *fs, ...) __attribute__ ((format (printf, 2, 3)));
 127 extern size_t io_fwrite (const void *ptr, size_t size, size_t nmemb, io_handle);
 128 extern int io_fflush (io_handle);
 129 extern int io_fileno (io_handle);
 130 extern io_handle io_popen (const char *command, const char *mode);
 131 extern void io_pclose (io_handle);
 132 extern int io_copy (io_handle from_io, io_handle to_io, int len);
 133 extern void io_setbufmode (io_handle, int mode);
 134 extern int io_get_inbufcount (io_handle);
 135 extern int io_get_outbufcount (io_handle);
 136
 137 #endif /* PTHR_IOLIB_H */