common/estream.h

   1 /* estream.h - Extended stream I/O Library
   2  * Copyright (C) 2004, 2005, 2006, 2007 g10 Code GmbH
   3  *
   4  * This file is part of Libestream.
   5  *
   6  * Libestream is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published
   8  * by the Free Software Foundation; either version 2 of the License,
   9  * or (at your option) any later version.
  10  *
  11  * Libestream is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with Libestream; if not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 #ifndef ESTREAM_H
  21 #define ESTREAM_H
  22
  23 #include <sys/types.h>
  24 #include <stdarg.h>
  25 #include <stdio.h>
  26
  27 /* To use this file with libraries the following macro is useful:
  28
  29      #define _ESTREAM_EXT_SYM_PREFIX _foo_
  30
  31        This prefixes all external symbols with "_foo_".
  32
  33  */
  34
  35
  36 #ifdef _ESTREAM_EXT_SYM_PREFIX
  37 #ifndef _ESTREAM_PREFIX
  38 #define _ESTREAM_PREFIX1(x,y)  x ## y
  39 #define _ESTREAM_PREFIX2(x,y) _ESTREAM_PREFIX1(x,y)
  40 #define _ESTREAM_PREFIX(x)    _ESTREAM_PREFIX2(_ESTREAM_EXT_SYM_PREFIX,x)
  41 #endif /*_ESTREAM_PREFIX*/
  42 #define es_fopen              _ESTREAM_PREFIX(es_fopen)
  43 #define es_mopen              _ESTREAM_PREFIX(es_mopen)
  44 #define es_fopenmem           _ESTREAM_PREFIX(es_fopenmem)
  45 #define es_fdopen             _ESTREAM_PREFIX(es_fdopen)
  46 #define es_fdopen_nc          _ESTREAM_PREFIX(es_fdopen_nc)
  47 #define es_fpopen             _ESTREAM_PREFIX(es_fpopen)
  48 #define es_fpopen_nc          _ESTREAM_PREFIX(es_fpopen_nc)
  49 #define es_freopen            _ESTREAM_PREFIX(es_freopen)
  50 #define es_fopencookie        _ESTREAM_PREFIX(es_fopencookie)
  51 #define es_fclose             _ESTREAM_PREFIX(es_fclose)
  52 #define es_fileno             _ESTREAM_PREFIX(es_fileno)
  53 #define es_fileno_unlocked    _ESTREAM_PREFIX(es_fileno_unlocked)
  54 #define es_flockfile          _ESTREAM_PREFIX(es_flockfile)
  55 #define es_ftrylockfile       _ESTREAM_PREFIX(es_ftrylockfile)
  56 #define es_funlockfile        _ESTREAM_PREFIX(es_funlockfile)
  57 #define es_feof               _ESTREAM_PREFIX(es_feof)
  58 #define es_feof_unlocked      _ESTREAM_PREFIX(es_feof_unlocked)
  59 #define es_ferror             _ESTREAM_PREFIX(es_ferror)
  60 #define es_ferror_unlocked    _ESTREAM_PREFIX(es_ferror_unlocked)
  61 #define es_clearerr           _ESTREAM_PREFIX(es_clearerr)
  62 #define es_clearerr_unlocked  _ESTREAM_PREFIX(es_clearerr_unlocked)
  63 #define es_fflush             _ESTREAM_PREFIX(es_fflush)
  64 #define es_fseek              _ESTREAM_PREFIX(es_fseek)
  65 #define es_fseeko             _ESTREAM_PREFIX(es_fseeko)
  66 #define es_ftell              _ESTREAM_PREFIX(es_ftell)
  67 #define es_ftello             _ESTREAM_PREFIX(es_ftello)
  68 #define es_rewind             _ESTREAM_PREFIX(es_rewind)
  69 #define es_fgetc              _ESTREAM_PREFIX(es_fgetc)
  70 #define es_fputc              _ESTREAM_PREFIX(es_fputc)
  71 #define _es_getc_underflow    _ESTREAM_PREFIX(_es_getc_underflow)
  72 #define _es_putc_overflow     _ESTREAM_PREFIX(_es_putc_overflow)
  73 #define es_ungetc             _ESTREAM_PREFIX(es_ungetc)
  74 #define es_read               _ESTREAM_PREFIX(es_read)
  75 #define es_write              _ESTREAM_PREFIX(es_write)
  76 #define es_write_sanitized    _ESTREAM_PREFIX(es_write_sanitized)
  77 #define es_write_hexstring    _ESTREAM_PREFIX(es_write_hexstring)
  78 #define es_fread              _ESTREAM_PREFIX(es_fread)
  79 #define es_fwrite             _ESTREAM_PREFIX(es_fwrite)
  80 #define es_fgets              _ESTREAM_PREFIX(es_fgets)
  81 #define es_fputs              _ESTREAM_PREFIX(es_fputs)
  82 #define es_getline            _ESTREAM_PREFIX(es_getline)
  83 #define es_read_line          _ESTREAM_PREFIX(es_read_line)
  84 #define es_free               _ESTREAM_PREFIX(es_free)
  85 #define es_fprf               _ESTREAM_PREFIX(es_fprf)
  86 #define es_vfprf              _ESTREAM_PREFIX(es_vfprf)
  87 #define es_setvbuf            _ESTREAM_PREFIX(es_setvbuf)
  88 #define es_setbuf             _ESTREAM_PREFIX(es_setbuf)
  89 #define es_tmpfile            _ESTREAM_PREFIX(es_tmpfile)
  90 #define es_opaque_set         _ESTREAM_PREFIX(es_opaque_set)
  91 #define es_opaque_get         _ESTREAM_PREFIX(es_opaque_get)
  92 #define es_write_sanitized_utf8_buffer  \
  93               _ESTREAM_PREFIX(es_write_sanitized_utf8_buffer)
  94 #endif /*_ESTREAM_EXT_SYM_PREFIX*/
  95
  96
  97 #ifdef __cplusplus
  98 extern "C"
  99 {
 100 #if 0
 101 }
 102 #endif
 103 #endif
 104
 105
 106 /* Forward declaration for the (opaque) internal type.  */
 107 struct estream_internal;
 108
 109 /* The definition of this struct is entirely private.  You must not
 110    use it for anything.  It is only here so some functions can be
 111    implemented as macros.  */
 112 struct es__stream
 113 {
 114   /* The layout of this struct must never change.  It may be grown,
 115      but only if all functions which access the new members are
 116      versioned.  */
 117
 118   /* A pointer to the stream buffer.  */
 119   unsigned char *buffer;
 120
 121   /* The size of the buffer in bytes.  */
 122   size_t buffer_size;
 123
 124   /* The length of the usable data in the buffer, only valid when in
 125      read mode (see flags).  */
 126   size_t data_len;
 127
 128   /* The current position of the offset pointer, valid in read and
 129      write mode.  */
 130   size_t data_offset;
 131
 132   size_t data_flushed;
 133   unsigned char *unread_buffer;
 134   size_t unread_buffer_size;
 135
 136   /* The number of unread bytes.  */
 137   size_t unread_data_len;
 138
 139   /* Various flags.  */
 140   struct {
 141     unsigned int writing: 1;
 142     unsigned int reserved: 7;
 143   } flags;
 144
 145   /* A pointer to our internal data for this stream.  */
 146   struct estream_internal *intern;
 147 };
 148
 149 /* The opaque type for an estream.  */
 150 typedef struct es__stream *estream_t;
 151
 152 \f
 153 typedef ssize_t (*es_cookie_read_function_t) (void *cookie,
 154                                               void *buffer, size_t size);
 155 typedef ssize_t (*es_cookie_write_function_t) (void *cookie,
 156                                                const void *buffer,
 157                                                size_t size);
 158 typedef int (*es_cookie_seek_function_t) (void *cookie,
 159                                           off_t *pos, int whence);
 160 typedef int (*es_cookie_close_function_t) (void *cookie);
 161
 162 typedef struct es_cookie_io_functions
 163 {
 164   es_cookie_read_function_t func_read;
 165   es_cookie_write_function_t func_write;
 166   es_cookie_seek_function_t func_seek;
 167   es_cookie_close_function_t func_close;
 168 } es_cookie_io_functions_t;
 169
 170 \f
 171 #ifndef _ESTREAM_GCC_A_PRINTF
 172 #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 5 )
 173 # define _ESTREAM_GCC_A_PRINTF( f, a )  __attribute__ ((format (printf,f,a)))
 174 #else
 175 # define _ESTREAM_GCC_A_PRINTF( f, a )
 176 #endif
 177 #endif /*_ESTREAM_GCC_A_PRINTF*/
 178
 179
 180 #ifndef ES__RESTRICT
 181 #  if defined __GNUC__ && defined __GNUC_MINOR__
 182 #    if  (__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 92))
 183 #      define ES__RESTRICT __restrict__
 184 #    endif
 185 #  endif
 186 #endif
 187 #ifndef ES__RESTRICT
 188 #  define ES__RESTRICT
 189 #endif
 190
 191 int es_init (void);
 192
 193 estream_t es_fopen (const char *ES__RESTRICT path,
 194                     const char *ES__RESTRICT mode);
 195 estream_t es_mopen (unsigned char *ES__RESTRICT data,
 196                     size_t data_n, size_t data_len,
 197                     unsigned int grow,
 198                     void *(*func_realloc) (void *mem, size_t size),
 199                     void (*func_free) (void *mem),
 200                     const char *ES__RESTRICT mode);
 201 estream_t es_fopenmem (size_t memlimit, const char *ES__RESTRICT mode);
 202 estream_t es_fdopen (int filedes, const char *mode);
 203 estream_t es_fdopen_nc (int filedes, const char *mode);
 204 estream_t es_fpopen (FILE *fp, const char *mode);
 205 estream_t es_fpopen_nc (FILE *fp, const char *mode);
 206 estream_t es_freopen (const char *ES__RESTRICT path,
 207                       const char *ES__RESTRICT mode,
 208                       estream_t ES__RESTRICT stream);
 209 estream_t es_fopencookie (void *ES__RESTRICT cookie,
 210                           const char *ES__RESTRICT mode,
 211                           es_cookie_io_functions_t functions);
 212 int es_fclose (estream_t stream);
 213 int es_fileno (estream_t stream);
 214 int es_fileno_unlocked (estream_t stream);
 215
 216 void es_flockfile (estream_t stream);
 217 int es_ftrylockfile (estream_t stream);
 218 void es_funlockfile (estream_t stream);
 219
 220 int es_feof (estream_t stream);
 221 int es_feof_unlocked (estream_t stream);
 222 int es_ferror (estream_t stream);
 223 int es_ferror_unlocked (estream_t stream);
 224 void es_clearerr (estream_t stream);
 225 void es_clearerr_unlocked (estream_t stream);
 226
 227 int es_fflush (estream_t stream);
 228 int es_fseek (estream_t stream, long int offset, int whence);
 229 int es_fseeko (estream_t stream, off_t offset, int whence);
 230 long int es_ftell (estream_t stream);
 231 off_t es_ftello (estream_t stream);
 232 void es_rewind (estream_t stream);
 233
 234 int es_fgetc (estream_t stream);
 235 int es_fputc (int c, estream_t stream);
 236
 237 int _es_getc_underflow (estream_t stream);
 238 int _es_putc_overflow (int c, estream_t stream);
 239
 240 #define es_getc_unlocked(stream)                                \
 241   (((!(stream)->flags.writing)                                  \
 242     && ((stream)->data_offset < (stream)->data_len)             \
 243     && (! (stream)->unread_data_len))                           \
 244   ? ((int) (stream)->buffer[((stream)->data_offset)++])         \
 245   : _es_getc_underflow ((stream)))
 246
 247 #define es_putc_unlocked(c, stream)                             \
 248   (((stream)->flags.writing                                     \
 249     && ((stream)->data_offset < (stream)->buffer_size)          \
 250     && (c != '\n'))                                             \
 251   ? ((int) ((stream)->buffer[((stream)->data_offset)++] = (c))) \
 252   : _es_putc_overflow ((c), (stream)))
 253
 254 #define es_getc(stream)    es_fgetc (stream)
 255 #define es_putc(c, stream) es_fputc (c, stream)
 256
 257 int es_ungetc (int c, estream_t stream);
 258
 259 int es_read (estream_t ES__RESTRICT stream,
 260              void *ES__RESTRICT buffer, size_t bytes_to_read,
 261              size_t *ES__RESTRICT bytes_read);
 262 int es_write (estream_t ES__RESTRICT stream,
 263               const void *ES__RESTRICT buffer, size_t bytes_to_write,
 264               size_t *ES__RESTRICT bytes_written);
 265 int es_write_sanitized (estream_t ES__RESTRICT stream,
 266                         const void *ES__RESTRICT buffer, size_t length,
 267                         const char *delimiters,
 268                         size_t *ES__RESTRICT bytes_written);
 269 int es_write_hexstring (estream_t ES__RESTRICT stream,
 270                         const void *ES__RESTRICT buffer, size_t length,
 271                         int reserved, size_t *ES__RESTRICT bytes_written);
 272
 273 size_t es_fread (void *ES__RESTRICT ptr, size_t size, size_t nitems,
 274                  estream_t ES__RESTRICT stream);
 275 size_t es_fwrite (const void *ES__RESTRICT ptr, size_t size, size_t memb,
 276                   estream_t ES__RESTRICT stream);
 277
 278 char *es_fgets (char *ES__RESTRICT s, int n, estream_t ES__RESTRICT stream);
 279 int es_fputs (const char *ES__RESTRICT s, estream_t ES__RESTRICT stream);
 280
 281 ssize_t es_getline (char *ES__RESTRICT *ES__RESTRICT lineptr,
 282                     size_t *ES__RESTRICT n,
 283                     estream_t stream);
 284 ssize_t es_read_line (estream_t stream,
 285                       char **addr_of_buffer, size_t *length_of_buffer,
 286                       size_t *max_length);
 287 void es_free (void *a);
 288
 289 int es_fprintf (estream_t ES__RESTRICT stream,
 290                 const char *ES__RESTRICT format, ...)
 291      _ESTREAM_GCC_A_PRINTF(2,3);
 292 int es_vfprintf (estream_t ES__RESTRICT stream,
 293                  const char *ES__RESTRICT format, va_list ap)
 294      _ESTREAM_GCC_A_PRINTF(2,0);
 295 int es_setvbuf (estream_t ES__RESTRICT stream,
 296                 char *ES__RESTRICT buf, int mode, size_t size);
 297 void es_setbuf (estream_t ES__RESTRICT stream, char *ES__RESTRICT buf);
 298
 299 estream_t es_tmpfile (void);
 300
 301 void es_opaque_set (estream_t ES__RESTRICT stream, void *ES__RESTRICT opaque);
 302 void *es_opaque_get (estream_t stream);
 303
 304
 305 #ifdef GNUPG_MAJOR_VERSION
 306 int es_write_sanitized_utf8_buffer (estream_t stream,
 307                                     const void *buffer, size_t length,
 308                                     const char *delimiters,
 309                                     size_t *bytes_written);
 310 #endif /*GNUPG_MAJOR_VERSION*/
 311
 312
 313 #ifdef __cplusplus
 314 }
 315 #endif
 316 #endif /*ESTREAM_H*/