iobuf: Rename IOBUF_TEMP to IOBUF_OUTPUT_TEMP.
[gnupg.git] / common / iobuf.h
1 /* iobuf.h - I/O buffer
2  * Copyright (C) 1998, 1999, 2000, 2001, 2003,
3  *               2010 Free Software Foundation, Inc.
4  *
5  * This file is part of GnuPG.
6  *
7  * This file is free software; you can redistribute it and/or modify
8  * it under the terms of either
9  *
10  *   - the GNU Lesser General Public License as published by the Free
11  *     Software Foundation; either version 3 of the License, or (at
12  *     your option) any later version.
13  *
14  * or
15  *
16  *   - the GNU General Public License as published by the Free
17  *     Software Foundation; either version 2 of the License, or (at
18  *     your option) any later version.
19  *
20  * or both in parallel, as here.
21  *
22  * This file is distributed in the hope that it will be useful,
23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
25  * GNU General Public License for more details.
26  *
27  * You should have received a copy of the GNU General Public License
28  * along with this program; if not, see <http://www.gnu.org/licenses/>.
29  */
30
31 #ifndef GNUPG_COMMON_IOBUF_H
32 #define GNUPG_COMMON_IOBUF_H
33
34 /* An iobuf is basically a filter in a pipeline.
35
36    Consider the following command, which consists of three filters
37    that are chained together:
38
39      $ cat file | base64 --decode | gunzip
40
41    The first filter reads the file from the file system and sends that
42    data to the second filter.  The second filter decodes
43    base64-encoded data and sends the data to the third and last
44    filter.  The last filter decompresses the data and the result is
45    displayed on the terminal.  The iobuf system works in the same way
46    where each iobuf is a filter and the individual iobufs can be
47    chained together.
48
49    There are number of predefined filters.  iobuf_open(), for
50    instance, creates a filter that reads from a specified file.  And,
51    iobuf_temp_with_content() creates a filter that returns some
52    specified contents.  There are also filters for writing content.
53    iobuf_openrw opens a file for writing.  iobuf_temp creates a filter
54    that writes data to a fixed-sized buffer.
55
56    To chain filters together, you use the iobuf_push_filter()
57    function.  The filters are chained together using the chain field
58    in the iobuf_t.
59
60    A pipeline can only be used for reading (IOBUF_INPUT) or for
61    writing (IOBUF_OUTPUT / IOBUF_OUTPUT_TEMP).  When reading, data
62    flows from the last filter towards the first.  That is, the user
63    calls iobuf_read(), the module reads from the first filter, which
64    gets its input from the second filter, etc.  When writing, data
65    flows from the first filter towards the last.  In this case, when
66    the user calls iobuf_write(), the data is written to the first
67    filter, which writes the transformed data to the second filter,
68    etc.
69
70    An iobuf_t contains some state about the filter.  For instance, it
71    indicates if the filter has already returned EOF (filter_eof) and
72    the next filter in the pipeline, if any (chain).  It also contains
73    a function pointer, filter.  This is a generic function.  It is
74    called when input is needed or output is available.  In this case
75    it is passed a pointer to some filter-specific persistent state
76    (filter_ov), the actual operation, the next filter in the chain, if
77    any, and a buffer that either contains the contents to write, if
78    the pipeline is setup to write data, or is the place to store data,
79    if the pipeline is setup to read data.
80
81
82    Unlike a Unix pipeline, an IOBUF pipeline can return EOF multiple
83    times.  This is similar to the following:
84
85      { cat file1; cat file2; } | grep foo
86
87    However, instead of grep seeing a single stream, grep would see
88    each byte stream followed by an EOF marker.  (When a filter returns
89    EOF, the EOF is returned to the user exactly once and then the
90    filter is removed from the pipeline.)  */
91
92 /* For estream_t.  */
93 #include <gpg-error.h>
94
95 #include "../common/types.h"
96 #include "../common/sysutils.h"
97
98 #define DBG_IOBUF   iobuf_debug_mode
99
100 /* Filter control modes.  */
101 enum
102   {
103     IOBUFCTRL_INIT      = 1,
104     IOBUFCTRL_FREE      = 2,
105     IOBUFCTRL_UNDERFLOW = 3,
106     IOBUFCTRL_FLUSH     = 4,
107     IOBUFCTRL_DESC      = 5,
108     IOBUFCTRL_CANCEL    = 6,
109     IOBUFCTRL_USER      = 16
110   };
111
112
113 /* Command codes for iobuf_ioctl.  */
114 typedef enum
115   {
116     IOBUF_IOCTL_KEEP_OPEN        = 1, /* Uses intval.  */
117     IOBUF_IOCTL_INVALIDATE_CACHE = 2, /* Uses ptrval.  */
118     IOBUF_IOCTL_NO_CACHE         = 3, /* Uses intval.  */
119     IOBUF_IOCTL_FSYNC            = 4  /* Uses ptrval.  */
120   } iobuf_ioctl_t;
121
122 enum iobuf_use
123   {
124     /* Pipeline is in input mode.  The data flows from the end to the
125        beginning.  That is, when reading from the pipeline, the first
126        filter gets its input from the second filter, etc.  */
127     IOBUF_INPUT=1,
128     /* Pipeline is in output mode.  The data flows from the beginning
129        to the end.  That is, when writing to the pipeline, the user
130        writes to the first filter, which transforms the data and sends
131        it to the second filter, etc.  */
132     IOBUF_OUTPUT=2,
133     /* Pipeline is in output mode.  The last filter in the pipeline is
134        a temporary buffer that grows as necessary.  */
135     IOBUF_OUTPUT_TEMP
136   };
137
138
139 typedef struct iobuf_struct *iobuf_t;
140 typedef struct iobuf_struct *IOBUF;  /* Compatibility with gpg 1.4. */
141
142 /* fixme: we should hide most of this stuff */
143 struct iobuf_struct
144 {
145   /* The type of filter.  Either IOBUF_INPUT, IOBUF_OUTPUT or
146      IOBUF_OUTPUT_TEMP.  */
147   enum iobuf_use use;
148
149   /* nlimit can be changed using iobuf_set_limit.  If non-zero, it is
150      the number of additional bytes that can be read from the filter
151      before EOF is forcefully returned.  */
152   off_t nlimit;
153   /* nbytes if the number of bytes that have been read (using
154      iobuf_get / iobuf_readbyte / iobuf_read) since the last call to
155      iobuf_set_limit.  */
156   off_t nbytes;
157
158   /* The number of bytes read prior to the last call to
159      iobuf_set_limit.  Thus, the total bytes read (i.e., the position
160      of stream) is ntotal + nbytes. */
161   off_t ntotal;
162
163   /* Whether we need to read from the filter one byte at a time or
164      whether we can do bulk reads.  We need to read one byte at a time
165      if a limit (set via iobuf_set_limit) is active.  */
166   int nofast;
167
168   /* A buffer for unread/unwritten data.
169
170      For an output pipeline (IOBUF_OUTPUT), this is the data that has
171      not yet been written to the filter.  Consider a simple pipeline
172      consisting of a single stage, which writes to a file.  When you
173      write to the pipeline (iobuf_writebyte or iobuf_write), the data
174      is first stored in this buffer.  Only when the buffer is full or
175      you call iobuf_flush() is FILTER actually called and the data
176      written to the file.
177
178      For an input pipeline (IOBUF_INPUT), this is the data that has
179      been read from this filter, but not yet been read from the
180      preceding filter (or the user, if this filter is the head of the
181      pipeline).  Again, consider a simple pipeline consisting of a
182      single stage.  This stage reads from a file.  If you read a
183      single byte (iobuf_get) and the buffer is empty, then FILTER is
184      called to fill the buffer.  In this case, a single byte is not
185      requested, but the whole buffer is filled (if possible).  */
186   struct
187   {
188     /* Size of the buffer.  */
189     size_t size;
190     /* Number of bytes at the beginning of the buffer that have
191        already been consumed.  (In other words: the index of the first
192        byte that hasn't been consumed.)  This is only non-zero for
193        input filters.  */
194     size_t start;
195     /* The number of bytes in the buffer including any bytes that have
196        been consumed.  */
197     size_t len;
198     /* The buffer itself.  */
199     byte *buf;
200   } d;
201
202   /* When FILTER is called to read some data, it may read some data
203      and then return EOF.  We can't return the EOF immediately.
204      Instead, we note that we observed the EOF and when the buffer is
205      finally empty, we return the EOF.  */
206   int filter_eof;
207   /* Like filter_eof, when FILTER is called to read some data, it may
208      read some data and then return an error.  We can't return the
209      error (in the form of an EOF) immediately.  Instead, we note that
210      we observed the error and when the buffer is finally empty, we
211      return the EOF.  */
212   int error;
213
214   /* The callback function to read data from the filter, etc.  See
215      iobuf_filter_push for details.  */
216   int (*filter) (void *opaque, int control,
217                  iobuf_t chain, byte * buf, size_t * len);
218   /* An opaque pointer that can be used for local filter state.  This
219      is passed as the first parameter to FILTER.  */
220   void *filter_ov;
221   /* Whether the iobuf code should free(filter_ov) when destroying the
222      filter.  */
223   int filter_ov_owner;
224
225   /* When using iobuf_open, iobuf_create, iobuf_openrw to open a file,
226      the file's name is saved here.  This is used to delete the file
227      when an output pipeline (IOBUF_OUPUT) is canceled
228      (iobuf_cancel).  */
229   char *real_fname;
230
231   /* The next filter in the pipeline.  */
232   iobuf_t chain;
233
234   /* This field is for debugging.  Each time a filter is allocated
235      (via iobuf_alloc()), a monotonically increasing counter is
236      incremented and this field is set to the new value.  This field
237      should only be accessed via the iobuf_io macro.  */
238   int no;
239
240   /* The number of filters in the pipeline following (not including)
241      this one.  When you call iobuf_push_filter or iobuf_push_filter2,
242      this value is used to check the length of the pipeline if the
243      pipeline already contains 65 stages then these functions fail.
244      This amount of nesting typically indicates corrupted data or an
245      active denial of service attack.  */
246   int subno;
247 };
248
249 #ifndef EXTERN_UNLESS_MAIN_MODULE
250 #if defined (__riscos__) && !defined (INCLUDED_BY_MAIN_MODULE)
251 #define EXTERN_UNLESS_MAIN_MODULE extern
252 #else
253 #define EXTERN_UNLESS_MAIN_MODULE
254 #endif
255 #endif
256 EXTERN_UNLESS_MAIN_MODULE int iobuf_debug_mode;
257
258 /* Whether iobuf_open, iobuf_create and iobuf_is_pipefilename
259    recognize special filenames.  Special filenames are of the form
260    "-&nnnn" where n is a positive integer.  The integer corresponds to
261    a file descriptor.  Note: these functions always recognize the
262    special filename '-', which corresponds to standard input.  */
263 void iobuf_enable_special_filenames (int yes);
264
265 /* Returns whether the specified filename corresponds to a pipe.  In
266    particular, this function checks if FNAME is "-" and, if special
267    filenames are enabled (see iobuf_enable_special_filenames), whether
268    FNAME is a special filename.  */
269 int  iobuf_is_pipe_filename (const char *fname);
270
271 /* Allocate a new filter.  This filter doesn't have a function
272    assigned to it.  Thus you need to manually set IOBUF->FILTER and
273    IOBUF->FILTER_OV, if required.  This function is intended to help
274    create a new primary source or primary sink, i.e., the last filter
275    in the pipeline.
276
277    USE is IOBUF_INPUT, IOBUF_OUTPUT or IOBUF_OUTPUT_TEMP.
278
279    BUFSIZE is the desired internal buffer size (that is, the size of
280    the typical read / write request).  */
281 iobuf_t iobuf_alloc (int use, size_t bufsize);
282
283 /* Create an output filter that simply buffers data written to it.
284    This is useful for collecting data for later processing.  The
285    buffer can be written to in the usual way (iobuf_write, etc.).  The
286    data can later be extracted using iobuf_write_temp() or
287    iobuf_temp_to_buffer().  */
288 iobuf_t iobuf_temp (void);
289
290 /* Create an input filter that contains some data for reading.  */
291 iobuf_t iobuf_temp_with_content (const char *buffer, size_t length);
292
293 /* Create an input file filter that reads from a file.  If FNAME is
294    '-', reads from stdin.  If special filenames are enabled
295    (iobuf_enable_special_filenames), then interprets special
296    filenames.  */
297 iobuf_t iobuf_open (const char *fname);
298
299 /* Create an output file filter that writes to a file.  If FNAME is
300    NULL or '-', writes to stdout.  If special filenames are enabled
301    (iobuf_enable_special_filenames), then interprets special
302    filenames.  If FNAME is not NULL, '-' or a special filename, the
303    file is opened for writing.  If the file exists, it is truncated.
304    If MODE700 is TRUE, the file is created with mode 600.  Otherwise,
305    mode 666 is used.  */
306 iobuf_t iobuf_create (const char *fname, int mode700);
307
308 /* Create an output file filter that writes to a specified file.
309    Neither '-' nor special file names are recognized.  */
310 iobuf_t iobuf_openrw (const char *fname);
311
312 /* Create a file filter using an existing file descriptor.  If MODE
313    contains the letter 'w', creates an output filter.  Otherwise,
314    creates an input filter.  Note: MODE must reflect the file
315    descriptors actual mode!  When the filter is destroyed, the file
316    descriptor is closed.  */
317 iobuf_t iobuf_fdopen (int fd, const char *mode);
318
319 /* Like iobuf_fdopen, but doesn't close the file descriptor when the
320    filter is destroyed.  */
321 iobuf_t iobuf_fdopen_nc (int fd, const char *mode);
322
323 /* Create a filter using an existing estream.  If MODE contains the
324    letter 'w', creates an output filter.  Otherwise, creates an input
325    filter.  If KEEP_OPEN is TRUE, then the stream is not closed when
326    the filter is destroyed.  Otherwise, the stream is closed when the
327    filter is destroyed.  */
328 iobuf_t iobuf_esopen (estream_t estream, const char *mode, int keep_open);
329
330 /* Create a filter using an existing socket.  On Windows creates a
331    special socket filter.  On non-Windows systems simply, this simply
332    calls iobuf_fdopen.  */
333 iobuf_t iobuf_sockopen (int fd, const char *mode);
334
335 /* Set various options / perform different actions on a PIPELINE.  See
336    the IOBUF_IOCTL_* macros above.  */
337 int iobuf_ioctl (iobuf_t a, iobuf_ioctl_t cmd, int intval, void *ptrval);
338
339 /* Close a pipeline.  The filters in the pipeline are first flushed
340    using iobuf_flush, if they are output filters, and then
341    IOBUFCTRL_FREE is called on each filter.
342
343    If any filter returns a non-zero value in response to the
344    IOBUFCTRL_FREE, that first such non-zero value is returned.  Note:
345    processing is not aborted in this case.  If all filters are freed
346    successfully, 0 is returned.  */
347 int iobuf_close (iobuf_t iobuf);
348
349 /* Calls IOBUFCTRL_CANCEL on each filter in the pipeline.  Then calls
350    io_close() on the pipeline.  Finally, if the pipeline is an output
351    pipeline, deletes the file.  Returns the result of calling
352    iobuf_close on the pipeline.  */
353 int iobuf_cancel (iobuf_t iobuf);
354
355 /* Add a new filter to the front of a pipeline.  A is the head of the
356    pipeline.  F is the filter implementation.  OV is an opaque pointer
357    that is passed to F and is normally used to hold any internal
358    state, such as a file pointer.
359
360    Note: you may only maintain a reference to an iobuf_t as a
361    reference to the head of the pipeline.  That is, don't think about
362    setting a pointer in OV to point to the filter's iobuf_t.  This is
363    because when we add a new filter to a pipeline, we memcpy the state
364    in A into new buffer.  This has the advantage that there is no need
365    to update any references to the pipeline when a filter is added or
366    removed, but it also means that a filter's state moves around in
367    memory.
368
369    The behavior of the filter function is determined by the value of
370    the control parameter:
371
372      IOBUFCTRL_INIT: Called this value just before the filter is
373        linked into the pipeline. This can be used to initialize
374        internal data structures.
375
376      IOBUFCTRL_FREE: Called with this value just before the filter is
377        removed from the pipeline.  Normally used to release internal
378        data structures, close a file handle, etc.
379
380      IOBUFCTRL_UNDERFLOW: Called with this value to fill the passed
381        buffer with more data. *LEN is the size of the buffer.  Before
382        returning, it should be set to the number of bytes which were
383        written into the buffer.  The function must return 0 to
384        indicate success, -1 on EOF and a GPG_ERR_xxxxx code for any
385        error.
386
387        Note: this function may both return data and indicate an error
388        or EOF.  In this case, it simply writes the data to BUF, sets
389        *LEN and returns the appropriate return code.  The implication
390        is that if an error occurs and no data has yet been written, it
391        is essential that *LEN be set to 0!
392
393      IOBUFCTRL_FLUSH: Called with this value to write out any
394        collected data.  *LEN is the number of bytes in BUF that need
395        to be written out.  Returns 0 on success and a GPG_ERR_* code
396        otherwise.  *LEN must be set to the number of bytes that were
397        written out.
398
399      IOBUFCTRL_CANCEL: Called with this value when iobuf_cancel() is
400        called on the pipeline.
401
402      IOBUFCTRL_DESC: Called with this value to get a human-readable
403        description of the filter.  * (char **) BUF should set to the
404        NUL-terminated string.  Note: you need to keep track of this
405        value and, if necessary, free it when the filter function is
406        called with control set to IOBUFCTRL_FREE.
407   */
408 int iobuf_push_filter (iobuf_t a, int (*f) (void *opaque, int control,
409                                             iobuf_t chain, byte * buf,
410                                             size_t * len), void *ov);
411 /* This variant of iobuf_push_filter allows the called to indicate
412    that OV should be freed when this filter is freed.  That is, if
413    REL_OV is TRUE, then when the filter is popped or freed OV will be
414    freed after the filter function is called with control set to
415    IOBUFCTRL_FREE.  */
416 int iobuf_push_filter2 (iobuf_t a,
417                         int (*f) (void *opaque, int control, iobuf_t chain,
418                                   byte * buf, size_t * len), void *ov,
419                         int rel_ov);
420
421 /* Used for debugging.  Prints out the chain using log_debug if
422    IOBUF_DEBUG_MODE is not 0.  */
423 int iobuf_print_chain (iobuf_t a);
424
425 /* Indicate that some error occured on the specified filter.  */
426 #define iobuf_set_error(a)    do { (a)->error = 1; } while(0)
427
428 /* Return any pending error on filter A.  */
429 #define iobuf_error(a)        ((a)->error)
430
431 /* Limit the amount of additional data that may be read from the
432    filter.  That is, if you've already read 100 bytes from A and you
433    set the limit to 50, then you can read up to an additional 50 bytes
434    (i.e., a total of 150 bytes) before EOF is forcefully returned.
435    Setting NLIMIT to 0 removes any active limit.
436
437    Note: using iobuf_seek removes any currently enforced limit!  */
438 void iobuf_set_limit (iobuf_t a, off_t nlimit);
439
440 /* Returns the number of bytes that have been read from the pipeline.
441    Note: the result is undefined for IOBUF_OUTPUT and IOBUF_OUTPUT_TEMP
442    pipelines!  */
443 off_t iobuf_tell (iobuf_t a);
444
445 /* There are two cases:
446
447    - If A is an INPUT or OUTPUT pipeline, then the last filter in the
448      pipeline is found.  If that is not a file filter, -1 is returned.
449      Otherwise, an fseek(..., SEEK_SET) is performed on the file
450      descriptor.
451
452    - If A is a TEMP pipeline and the *first* (and thus only filter) is
453      a TEMP filter, then the "file position" is effectively unchanged.
454      That is, data is appended to the buffer and the seek does not
455      cause the size of the buffer to grow.
456
457    If no error occured, then any limit previous set by
458    iobuf_set_limit() is cleared.  Further, any error on the filter
459    (the file filter or the temp filter) is cleared.
460
461    Returns 0 on success and -1 if an error occurs.  */
462 int iobuf_seek (iobuf_t a, off_t newpos);
463
464 /* Read a single byte.  If a filter has no more data, returns -1 to
465    indicate the EOF.  Generally, you don't want to use this function,
466    but instead prefer the iobuf_get macro, which is faster if there is
467    data in the internal buffer.  */
468 int iobuf_readbyte (iobuf_t a);
469
470 /* Get a byte from the iobuf; must check for eof prior to this
471    function.  This function returns values in the range 0 .. 255 or -1
472    to indicate EOF.  iobuf_get_noeof() does not return -1 to indicate
473    EOF, but masks the returned value to be in the range 0 .. 255.  */
474 #define iobuf_get(a)  \
475      (  ((a)->nofast || (a)->d.start >= (a)->d.len )?  \
476         iobuf_readbyte((a)) : ( (a)->nbytes++, (a)->d.buf[(a)->d.start++] ) )
477 #define iobuf_get_noeof(a)    (iobuf_get((a))&0xff)
478
479 /* Fill BUF with up to BUFLEN bytes.  If a filter has no more data,
480    returns -1 to indicate the EOF.  Otherwise returns the number of
481    bytes read.  */
482 int iobuf_read (iobuf_t a, void *buf, unsigned buflen);
483
484 /* Read a line of input (including the '\n') from the pipeline.
485
486    The semantics are the same as for fgets(), but if the buffer is too
487    short a larger one will be allocated up to *MAX_LENGTH and the end
488    of the line except the trailing '\n' discarded.  (Thus,
489    *ADDR_OF_BUFFER must be allocated using malloc().)  If the buffer
490    is enlarged, then *LENGTH_OF_BUFFER will be updated to reflect the
491    new size.  If the line is truncated, then *MAX_LENGTH will be set
492    to 0.  If *ADDR_OF_BUFFER is NULL, a buffer is allocated using
493    malloc().
494
495    A line is considered a byte stream ending in a '\n'.  Returns the
496    number of characters written to the buffer (i.e., excluding any
497    discarded characters due to truncation).  Thus, use this instead of
498    strlen(buffer) to determine the length of the string as this is
499    unreliable if the input contains NUL characters.
500
501    EOF is indicated by a line of length zero.
502
503    The last LF may be missing due to an EOF.  */
504 unsigned iobuf_read_line (iobuf_t a, byte ** addr_of_buffer,
505                           unsigned *length_of_buffer, unsigned *max_length);
506
507 /* Read up to BUFLEN bytes from pipeline A.  Note: this function can't
508    return more than the pipeline's internal buffer size.  The return
509    value is the number of bytes actually written to BUF.  If the
510    filter returns EOF, then this function returns -1.
511
512    This function does not clear any pending EOF.  That is, if the
513    pipeline consists of two filters and the first one returns EOF
514    during the peek, then the subsequent iobuf_read* will still return
515    EOF before returning the data from the second filter.  */
516 int iobuf_peek (iobuf_t a, byte * buf, unsigned buflen);
517
518 /* Write a byte to the pipeline.  Returns 0 on success and an error
519    code otherwise.  */
520 int iobuf_writebyte (iobuf_t a, unsigned c);
521
522 /* Alias for iobuf_writebyte.  */
523 #define iobuf_put(a,c)  iobuf_writebyte(a,c)
524
525 /* Write a sequence of bytes to the pipeline.  Returns 0 on success
526    and an error code otherwise.  */
527 int iobuf_write (iobuf_t a, const void *buf, unsigned buflen);
528
529 /* Write a string (not including the NUL terminator) to the pipeline.
530    Returns 0 on success and an error code otherwise.  */
531 int iobuf_writestr (iobuf_t a, const char *buf);
532
533 /* Flushes the pipeline removing all filters but the sink (the last
534    filter) in the process.  */
535 void iobuf_flush_temp (iobuf_t temp);
536
537 /* Flushes the pipeline SOURCE removing all filters but the sink (the
538    last filter) in the process (i.e., it calls
539    iobuf_flush_temp(source)) and then writes the data to the pipeline
540    DEST.  Note: this doesn't free (iobuf_close()) SOURCE.  Both SOURCE
541    and DEST must be output pipelines.  */
542 int iobuf_write_temp (iobuf_t dest, iobuf_t source);
543
544 /* Flushes each filter in the pipeline (i.e., sends any buffered data
545    to the filter by calling IOBUFCTRL_FLUSH).  Then, copies up to the
546    first BUFLEN bytes from the last filter's internal buffer (which
547    will only be non-empty if it is a temp filter) to the buffer
548    BUFFER.  Returns the number of bytes actually copied.  */
549 size_t iobuf_temp_to_buffer (iobuf_t a, byte * buffer, size_t buflen);
550
551 /* Return the size of any underlying file.  This only works with
552    file_filter based pipelines.
553
554    On Win32, it is sometimes not possible to determine the size of
555    files larger than 4GB.  In this case, *OVERFLOW (if not NULL) is
556    set to 1.  Otherwise, *OVERFLOW is set to 0.  */
557 off_t iobuf_get_filelength (iobuf_t a, int *overflow);
558 #define IOBUF_FILELENGTH_LIMIT 0xffffffff
559
560 /* Return the file descriptor designating the underlying file.  This
561    only works with file_filter based pipelines.  */
562 int  iobuf_get_fd (iobuf_t a);
563
564 /* Return the real filename, if available.  This only supports
565    pipelines that end in file filters.  Returns NULL if not
566    available.  */
567 const char *iobuf_get_real_fname (iobuf_t a);
568
569 /* Return the filename or a description thereof.  For instance, for
570    iobuf_open("-"), this will return "[stdin]".  This only supports
571    pipelines that end in file filters.  Returns NULL if not
572    available.  */
573 const char *iobuf_get_fname (iobuf_t a);
574
575 /* Like iobuf_getfname, but instead of returning NULL if no
576    description is available, return "[?]".  */
577 const char *iobuf_get_fname_nonnull (iobuf_t a);
578
579 /* Pushes a filter on the pipeline that interprets the datastream as
580    an OpenPGP data block whose length is encoded using partial body
581    length headers (see Section 4.2.2.4 of RFC 4880).  Concretely, it
582    just returns / writes the data and finishes the packet with an
583    EOF.  */
584 void iobuf_set_partial_block_mode (iobuf_t a, size_t len);
585
586 /* If PARTIAL is set, then read from the pipeline until the first EOF
587    is returned.
588
589    If PARTIAL is 0, then read up to N bytes or until the first EOF is
590    returned.
591
592    Recall: a filter can return EOF.  In this case, it and all
593    preceding filters are popped from the pipeline and the next read is
594    from the following filter (which may or may not return EOF).  */
595 void iobuf_skip_rest (iobuf_t a, unsigned long n, int partial);
596
597 #define iobuf_where(a)  "[don't know]"
598
599 /* Each time a filter is allocated (via iobuf_alloc()), a
600    monotonically increasing counter is incremented and this field is
601    set to the new value.  This macro returns that number.  */
602 #define iobuf_id(a)     ((a)->no)
603
604 #define iobuf_get_temp_buffer(a) ( (a)->d.buf )
605 #define iobuf_get_temp_length(a) ( (a)->d.len )
606
607 /* Whether the filter uses an in-memory buffer.  */
608 #define iobuf_is_temp(a)         ( (a)->use == IOBUF_OUTPUT_TEMP )
609
610 #endif /*GNUPG_COMMON_IOBUF_H*/