Register DCO for Stefan Tomanek.
[gnupg.git] / common / estream.h
1 /* estream.h - Extended stream I/O Library
2  * Copyright (C) 2004, 2005, 2006, 2007, 2010, 2011 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  * ALTERNATIVELY, Libestream may be distributed under the terms of the
20  * following license, in which case the provisions of this license are
21  * required INSTEAD OF the GNU General Public License. If you wish to
22  * allow use of your version of this file only under the terms of the
23  * GNU General Public License, and not to allow others to use your
24  * version of this file under the terms of the following license,
25  * indicate your decision by deleting this paragraph and the license
26  * below.
27  *
28  * Redistribution and use in source and binary forms, with or without
29  * modification, are permitted provided that the following conditions
30  * are met:
31  * 1. Redistributions of source code must retain the above copyright
32  *    notice, and the entire permission notice in its entirety,
33  *    including the disclaimer of warranties.
34  * 2. Redistributions in binary form must reproduce the above copyright
35  *    notice, this list of conditions and the following disclaimer in the
36  *    documentation and/or other materials provided with the distribution.
37  * 3. The name of the author may not be used to endorse or promote
38  *    products derived from this software without specific prior
39  *    written permission.
40  *
41  * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
42  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
43  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
44  * DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
45  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
46  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
47  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
49  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
50  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
51  * OF THE POSSIBILITY OF SUCH DAMAGE.
52  */
53
54 #ifndef ESTREAM_H
55 #define ESTREAM_H
56
57 #include <sys/types.h>
58 #include <stdarg.h>
59 #include <stdio.h>
60
61 /* To use this file with libraries the following macro is useful:
62
63      #define _ESTREAM_EXT_SYM_PREFIX _foo_
64
65        This prefixes all external symbols with "_foo_".
66
67  */
68
69
70 #ifdef _ESTREAM_EXT_SYM_PREFIX
71 #ifndef _ESTREAM_PREFIX
72 #define _ESTREAM_PREFIX1(x,y)  x ## y
73 #define _ESTREAM_PREFIX2(x,y) _ESTREAM_PREFIX1(x,y)
74 #define _ESTREAM_PREFIX(x)    _ESTREAM_PREFIX2(_ESTREAM_EXT_SYM_PREFIX,x)
75 #endif /*_ESTREAM_PREFIX*/
76 #define es_fopen              _ESTREAM_PREFIX(es_fopen)
77 #define es_mopen              _ESTREAM_PREFIX(es_mopen)
78 #define es_fopenmem           _ESTREAM_PREFIX(es_fopenmem)
79 #define es_fopenmem_init      _ESTREAM_PREFIX(es_fopenmem_init)
80 #define es_fdopen             _ESTREAM_PREFIX(es_fdopen)
81 #define es_fdopen_nc          _ESTREAM_PREFIX(es_fdopen_nc)
82 #define es_sysopen            _ESTREAM_PREFIX(es_sysopen)
83 #define es_sysopen_nc         _ESTREAM_PREFIX(es_sysopen_nc)
84 #define es_fpopen             _ESTREAM_PREFIX(es_fpopen)
85 #define es_fpopen_nc          _ESTREAM_PREFIX(es_fpopen_nc)
86 #define _es_set_std_fd        _ESTREAM_PREFIX(_es_set_std_fd)
87 #define _es_get_std_stream    _ESTREAM_PREFIX(_es_get_std_stream)
88 #define es_freopen            _ESTREAM_PREFIX(es_freopen)
89 #define es_fopencookie        _ESTREAM_PREFIX(es_fopencookie)
90 #define es_fclose             _ESTREAM_PREFIX(es_fclose)
91 #define es_fclose_snatch      _ESTREAM_PREFIX(es_fclose_snatch)
92 #define es_onclose            _ESTREAM_PREFIX(es_onclose)
93 #define es_fileno             _ESTREAM_PREFIX(es_fileno)
94 #define es_fileno_unlocked    _ESTREAM_PREFIX(es_fileno_unlocked)
95 #define es_flockfile          _ESTREAM_PREFIX(es_flockfile)
96 #define es_ftrylockfile       _ESTREAM_PREFIX(es_ftrylockfile)
97 #define es_funlockfile        _ESTREAM_PREFIX(es_funlockfile)
98 #define es_feof               _ESTREAM_PREFIX(es_feof)
99 #define es_feof_unlocked      _ESTREAM_PREFIX(es_feof_unlocked)
100 #define es_ferror             _ESTREAM_PREFIX(es_ferror)
101 #define es_ferror_unlocked    _ESTREAM_PREFIX(es_ferror_unlocked)
102 #define es_clearerr           _ESTREAM_PREFIX(es_clearerr)
103 #define es_clearerr_unlocked  _ESTREAM_PREFIX(es_clearerr_unlocked)
104 #define es_fflush             _ESTREAM_PREFIX(es_fflush)
105 #define es_fseek              _ESTREAM_PREFIX(es_fseek)
106 #define es_fseeko             _ESTREAM_PREFIX(es_fseeko)
107 #define es_ftell              _ESTREAM_PREFIX(es_ftell)
108 #define es_ftello             _ESTREAM_PREFIX(es_ftello)
109 #define es_rewind             _ESTREAM_PREFIX(es_rewind)
110 #define es_fgetc              _ESTREAM_PREFIX(es_fgetc)
111 #define es_fputc              _ESTREAM_PREFIX(es_fputc)
112 #define _es_getc_underflow    _ESTREAM_PREFIX(_es_getc_underflow)
113 #define _es_putc_overflow     _ESTREAM_PREFIX(_es_putc_overflow)
114 #define es_ungetc             _ESTREAM_PREFIX(es_ungetc)
115 #define es_read               _ESTREAM_PREFIX(es_read)
116 #define es_write              _ESTREAM_PREFIX(es_write)
117 #define es_write_sanitized    _ESTREAM_PREFIX(es_write_sanitized)
118 #define es_write_hexstring    _ESTREAM_PREFIX(es_write_hexstring)
119 #define es_fread              _ESTREAM_PREFIX(es_fread)
120 #define es_fwrite             _ESTREAM_PREFIX(es_fwrite)
121 #define es_fgets              _ESTREAM_PREFIX(es_fgets)
122 #define es_fputs              _ESTREAM_PREFIX(es_fputs)
123 #define es_fputs_unlocked     _ESTREAM_PREFIX(es_fputs_unlocked)
124 #define es_getline            _ESTREAM_PREFIX(es_getline)
125 #define es_read_line          _ESTREAM_PREFIX(es_read_line)
126 #define es_free               _ESTREAM_PREFIX(es_free)
127 #define es_fprintf            _ESTREAM_PREFIX(es_fprintf)
128 #define es_fprintf_unlocked   _ESTREAM_PREFIX(es_fprintf_unlocked)
129 #define es_printf             _ESTREAM_PREFIX(es_printf)
130 #define es_printf_unlocked    _ESTREAM_PREFIX(es_printf_unlocked)
131 #define es_vfprintf           _ESTREAM_PREFIX(es_vfprint)
132 #define es_vfprintf_unlocked  _ESTREAM_PREFIX(es_vfprint_unlocked)
133 #define es_setvbuf            _ESTREAM_PREFIX(es_setvbuf)
134 #define es_setbuf             _ESTREAM_PREFIX(es_setbuf)
135 #define es_set_binary         _ESTREAM_PREFIX(es_set_binary)
136 #define es_tmpfile            _ESTREAM_PREFIX(es_tmpfile)
137 #define es_opaque_set         _ESTREAM_PREFIX(es_opaque_set)
138 #define es_opaque_get         _ESTREAM_PREFIX(es_opaque_get)
139 #define es_fname_set          _ESTREAM_PREFIX(es_fname_set)
140 #define es_fname_get          _ESTREAM_PREFIX(es_fname_get)
141 #define es_write_sanitized_utf8_buffer  \
142               _ESTREAM_PREFIX(es_write_sanitized_utf8_buffer)
143 #endif /*_ESTREAM_EXT_SYM_PREFIX*/
144
145
146 #ifdef __cplusplus
147 extern "C"
148 {
149 #if 0
150 }
151 #endif
152 #endif
153
154
155 /* Forward declaration for the (opaque) internal type.  */
156 struct estream_internal;
157
158 /* The definition of this struct is entirely private.  You must not
159    use it for anything.  It is only here so some functions can be
160    implemented as macros.  */
161 struct es__stream
162 {
163   /* The layout of this struct must never change.  It may be grown,
164      but only if all functions which access the new members are
165      versioned.  */
166
167   /* A pointer to the stream buffer.  */
168   unsigned char *buffer;
169
170   /* The size of the buffer in bytes.  */
171   size_t buffer_size;
172
173   /* The length of the usable data in the buffer, only valid when in
174      read mode (see flags).  */
175   size_t data_len;
176
177   /* The current position of the offset pointer, valid in read and
178      write mode.  */
179   size_t data_offset;
180
181   size_t data_flushed;
182   unsigned char *unread_buffer;
183   size_t unread_buffer_size;
184
185   /* The number of unread bytes.  */
186   size_t unread_data_len;
187
188   /* Various flags.  */
189   struct {
190     unsigned int writing: 1;
191     unsigned int reserved: 7;
192   } flags;
193
194   /* A pointer to our internal data for this stream.  */
195   struct estream_internal *intern;
196 };
197
198 /* The opaque type for an estream.  */
199 typedef struct es__stream *estream_t;
200
201 \f
202 typedef ssize_t (*es_cookie_read_function_t) (void *cookie,
203                                               void *buffer, size_t size);
204 typedef ssize_t (*es_cookie_write_function_t) (void *cookie,
205                                                const void *buffer,
206                                                size_t size);
207 typedef int (*es_cookie_seek_function_t) (void *cookie,
208                                           off_t *pos, int whence);
209 typedef int (*es_cookie_close_function_t) (void *cookie);
210
211 typedef struct es_cookie_io_functions
212 {
213   es_cookie_read_function_t func_read;
214   es_cookie_write_function_t func_write;
215   es_cookie_seek_function_t func_seek;
216   es_cookie_close_function_t func_close;
217 } es_cookie_io_functions_t;
218
219
220 enum es_syshd_types
221   {
222     ES_SYSHD_NONE,  /* No system handle available.  */
223     ES_SYSHD_FD,    /* A file descriptor as returned by open().  */
224     ES_SYSHD_SOCK,  /* A socket as returned by socket().        */
225     ES_SYSHD_RVID,  /* A rendevous id (see libassuan's gpgcedev.c).  */
226     ES_SYSHD_HANDLE /* A HANDLE object (Windows).  */
227   };
228
229 typedef struct
230 {
231   enum es_syshd_types type;
232   union {
233     int fd;
234     int sock;
235     int rvid;
236     void *handle;
237   } u;
238 } es_syshd_t;
239
240
241
242 \f
243 #ifndef _ESTREAM_GCC_A_PRINTF
244 # if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 4 )
245 #  define _ESTREAM_GCC_A_PRINTF( f, a ) \
246                                __attribute__ ((format (__gnu_printf__,f,a)))
247 # elif __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 5 )
248 #  define _ESTREAM_GCC_A_PRINTF( f, a ) \
249                                __attribute__ ((format (printf,f,a)))
250 # else
251 #  define _ESTREAM_GCC_A_PRINTF( f, a )
252 # endif
253 #endif /*_ESTREAM_GCC_A_PRINTF*/
254
255
256 #ifndef ES__RESTRICT
257 #  if defined __GNUC__ && defined __GNUC_MINOR__
258 #    if  (__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 92))
259 #      define ES__RESTRICT __restrict__
260 #    endif
261 #  endif
262 #endif
263 #ifndef ES__RESTRICT
264 #  define ES__RESTRICT
265 #endif
266
267 int es_init (void);
268
269 estream_t es_fopen (const char *ES__RESTRICT path,
270                     const char *ES__RESTRICT mode);
271 estream_t es_mopen (void *ES__RESTRICT data,
272                     size_t data_n, size_t data_len,
273                     unsigned int grow,
274                     void *(*func_realloc) (void *mem, size_t size),
275                     void (*func_free) (void *mem),
276                     const char *ES__RESTRICT mode);
277 estream_t es_fopenmem (size_t memlimit, const char *ES__RESTRICT mode);
278 estream_t es_fopenmem_init (size_t memlimit, const char *ES__RESTRICT mode,
279                             const void *data, size_t datalen);
280 estream_t es_fdopen (int filedes, const char *mode);
281 estream_t es_fdopen_nc (int filedes, const char *mode);
282 estream_t es_sysopen (es_syshd_t *syshd, const char *mode);
283 estream_t es_sysopen_nc (es_syshd_t *syshd, const char *mode);
284 estream_t es_fpopen (FILE *fp, const char *mode);
285 estream_t es_fpopen_nc (FILE *fp, const char *mode);
286 estream_t es_freopen (const char *ES__RESTRICT path,
287                       const char *ES__RESTRICT mode,
288                       estream_t ES__RESTRICT stream);
289 estream_t es_fopencookie (void *ES__RESTRICT cookie,
290                           const char *ES__RESTRICT mode,
291                           es_cookie_io_functions_t functions);
292 int es_fclose (estream_t stream);
293 int es_fclose_snatch (estream_t stream, void **r_buffer, size_t *r_buflen);
294 int es_onclose (estream_t stream, int mode,
295                 void (*fnc) (estream_t, void*), void *fnc_value);
296 int es_fileno (estream_t stream);
297 int es_fileno_unlocked (estream_t stream);
298 int es_syshd (estream_t stream, es_syshd_t *syshd);
299 int es_syshd_unlocked (estream_t stream, es_syshd_t *syshd);
300
301 void _es_set_std_fd (int no, int fd);
302 estream_t _es_get_std_stream (int fd);
303
304 #define es_stdin  _es_get_std_stream (0)
305 #define es_stdout _es_get_std_stream (1)
306 #define es_stderr _es_get_std_stream (2)
307
308
309 void es_flockfile (estream_t stream);
310 int es_ftrylockfile (estream_t stream);
311 void es_funlockfile (estream_t stream);
312
313 int es_feof (estream_t stream);
314 int es_feof_unlocked (estream_t stream);
315 int es_ferror (estream_t stream);
316 int es_ferror_unlocked (estream_t stream);
317 void es_clearerr (estream_t stream);
318 void es_clearerr_unlocked (estream_t stream);
319
320 int es_fflush (estream_t stream);
321 int es_fseek (estream_t stream, long int offset, int whence);
322 int es_fseeko (estream_t stream, off_t offset, int whence);
323 long int es_ftell (estream_t stream);
324 off_t es_ftello (estream_t stream);
325 void es_rewind (estream_t stream);
326
327 int es_fgetc (estream_t stream);
328 int es_fputc (int c, estream_t stream);
329
330 int _es_getc_underflow (estream_t stream);
331 int _es_putc_overflow (int c, estream_t stream);
332
333 #define es_getc_unlocked(stream)                                \
334   (((!(stream)->flags.writing)                                  \
335     && ((stream)->data_offset < (stream)->data_len)             \
336     && (! (stream)->unread_data_len))                           \
337   ? ((int) (stream)->buffer[((stream)->data_offset)++])         \
338   : _es_getc_underflow ((stream)))
339
340 #define es_putc_unlocked(c, stream)                             \
341   (((stream)->flags.writing                                     \
342     && ((stream)->data_offset < (stream)->buffer_size)          \
343     && (c != '\n'))                                             \
344   ? ((int) ((stream)->buffer[((stream)->data_offset)++] = (c))) \
345   : _es_putc_overflow ((c), (stream)))
346
347 #define es_getc(stream)    es_fgetc (stream)
348 #define es_putc(c, stream) es_fputc (c, stream)
349
350 int es_ungetc (int c, estream_t stream);
351
352 int es_read (estream_t ES__RESTRICT stream,
353              void *ES__RESTRICT buffer, size_t bytes_to_read,
354              size_t *ES__RESTRICT bytes_read);
355 int es_write (estream_t ES__RESTRICT stream,
356               const void *ES__RESTRICT buffer, size_t bytes_to_write,
357               size_t *ES__RESTRICT bytes_written);
358 int es_write_sanitized (estream_t ES__RESTRICT stream,
359                         const void *ES__RESTRICT buffer, size_t length,
360                         const char *delimiters,
361                         size_t *ES__RESTRICT bytes_written);
362 int es_write_hexstring (estream_t ES__RESTRICT stream,
363                         const void *ES__RESTRICT buffer, size_t length,
364                         int reserved, size_t *ES__RESTRICT bytes_written);
365
366 size_t es_fread (void *ES__RESTRICT ptr, size_t size, size_t nitems,
367                  estream_t ES__RESTRICT stream);
368 size_t es_fwrite (const void *ES__RESTRICT ptr, size_t size, size_t memb,
369                   estream_t ES__RESTRICT stream);
370
371 char *es_fgets (char *ES__RESTRICT s, int n, estream_t ES__RESTRICT stream);
372 int es_fputs (const char *ES__RESTRICT s, estream_t ES__RESTRICT stream);
373 int es_fputs_unlocked (const char *ES__RESTRICT s,
374                        estream_t ES__RESTRICT stream);
375
376 ssize_t es_getline (char *ES__RESTRICT *ES__RESTRICT lineptr,
377                     size_t *ES__RESTRICT n,
378                     estream_t stream);
379 ssize_t es_read_line (estream_t stream,
380                       char **addr_of_buffer, size_t *length_of_buffer,
381                       size_t *max_length);
382 void es_free (void *a);
383
384 int es_fprintf (estream_t ES__RESTRICT stream,
385                 const char *ES__RESTRICT format, ...)
386      _ESTREAM_GCC_A_PRINTF(2,3);
387 int es_fprintf_unlocked (estream_t ES__RESTRICT stream,
388                          const char *ES__RESTRICT format, ...)
389      _ESTREAM_GCC_A_PRINTF(2,3);
390
391 int es_printf (const char *ES__RESTRICT format, ...)
392      _ESTREAM_GCC_A_PRINTF(1,2);
393 int es_printf_unlocked (const char *ES__RESTRICT format, ...)
394      _ESTREAM_GCC_A_PRINTF(1,2);
395
396 int es_vfprintf (estream_t ES__RESTRICT stream,
397                  const char *ES__RESTRICT format, va_list ap)
398      _ESTREAM_GCC_A_PRINTF(2,0);
399 int es_vfprintf_unlocked (estream_t ES__RESTRICT stream,
400                           const char *ES__RESTRICT format, va_list ap)
401      _ESTREAM_GCC_A_PRINTF(2,0);
402
403 char *es_asprintf (const char *ES__RESTRICT format, ...)
404      _ESTREAM_GCC_A_PRINTF(1,2);
405 char *es_vasprintf (const char *ES__RESTRICT format, va_list ap)
406      _ESTREAM_GCC_A_PRINTF(1,0);
407
408 int es_setvbuf (estream_t ES__RESTRICT stream,
409                 char *ES__RESTRICT buf, int mode, size_t size);
410 void es_setbuf (estream_t ES__RESTRICT stream, char *ES__RESTRICT buf);
411
412 void es_set_binary (estream_t stream);
413
414
415 estream_t es_tmpfile (void);
416
417 void es_opaque_set (estream_t ES__RESTRICT stream, void *ES__RESTRICT opaque);
418 void *es_opaque_get (estream_t stream);
419
420 void es_fname_set (estream_t stream, const char *fname);
421 const char *es_fname_get (estream_t stream);
422
423
424 #ifdef GNUPG_MAJOR_VERSION
425 int es_write_sanitized_utf8_buffer (estream_t stream,
426                                     const void *buffer, size_t length,
427                                     const char *delimiters,
428                                     size_t *bytes_written);
429 #endif /*GNUPG_MAJOR_VERSION*/
430
431 #ifdef __cplusplus
432 }
433 #endif
434 #endif /*ESTREAM_H*/