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