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