1 /* iobuf.h - I/O buffer
2 * Copyright (C) 1998, 1999, 2000, 2001, 2003,
3 * 2010 Free Software Foundation, Inc.
5 * This file is part of GnuPG.
7 * This file is free software; you can redistribute it and/or modify
8 * it under the terms of either
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.
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.
20 * or both in parallel, as here.
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.
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/>.
31 #ifndef GNUPG_COMMON_IOBUF_H
32 #define GNUPG_COMMON_IOBUF_H
34 /* An iobuf is basically a filter in a pipeline.
36 Consider the following command, which consists of three filters
37 that are chained together:
39 $ cat file | base64 --decode | gunzip
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
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.
56 To chain filters together, you use the iobuf_push_filter()
57 function. The filters are chained together using the chain field
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,
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.
82 Unlike a Unix pipeline, an IOBUF pipeline can return EOF multiple
83 times. This is similar to the following:
85 { cat file1; cat file2; } | grep foo
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.) */
93 #include <gpg-error.h>
95 #include "../common/types.h"
96 #include "../common/sysutils.h"
98 #define DBG_IOBUF iobuf_debug_mode
100 /* Filter control modes. */
105 IOBUFCTRL_UNDERFLOW = 3,
108 IOBUFCTRL_CANCEL = 6,
113 /* Command codes for iobuf_ioctl. */
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. */
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. */
128 /* Pipeline is in input mode. The last filter in the pipeline is
129 a temporary buffer from which the data is "read". */
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. */
136 /* Pipeline is in output mode. The last filter in the pipeline is
137 a temporary buffer that grows as necessary. */
142 typedef struct iobuf_struct *iobuf_t;
143 typedef struct iobuf_struct *IOBUF; /* Compatibility with gpg 1.4. */
145 /* fixme: we should hide most of this stuff */
148 /* The type of filter. Either IOBUF_INPUT, IOBUF_OUTPUT or
149 IOBUF_OUTPUT_TEMP. */
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. */
156 /* nbytes if the number of bytes that have been read (using
157 iobuf_get / iobuf_readbyte / iobuf_read) since the last call to
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. */
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. */
171 /* A buffer for unread/unwritten data.
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
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). */
191 /* Size of the buffer. */
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
198 /* The number of bytes in the buffer including any bytes that have
201 /* The buffer itself. */
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. */
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
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. */
224 /* Whether the iobuf code should free(filter_ov) when destroying the
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
234 /* The next filter in the pipeline. */
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. */
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. */
252 #ifndef EXTERN_UNLESS_MAIN_MODULE
253 #if defined (__riscos__) && !defined (INCLUDED_BY_MAIN_MODULE)
254 #define EXTERN_UNLESS_MAIN_MODULE extern
256 #define EXTERN_UNLESS_MAIN_MODULE
259 EXTERN_UNLESS_MAIN_MODULE int iobuf_debug_mode;
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);
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);
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
280 USE is IOBUF_INPUT, IOBUF_INPUT_TEMP, IOBUF_OUTPUT or
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);
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);
294 /* Create an input filter that contains some data for reading. */
295 iobuf_t iobuf_temp_with_content (const char *buffer, size_t length);
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
301 iobuf_t iobuf_open (const char *fname);
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,
310 iobuf_t iobuf_create (const char *fname, int mode700);
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);
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);
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);
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);
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);
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);
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.
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);
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);
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.
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
373 The behavior of the filter function is determined by the value of
374 the control parameter:
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.
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.
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
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!
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
403 IOBUFCTRL_CANCEL: Called with this value when iobuf_cancel() is
404 called on the pipeline.
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
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
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,
424 /* Used for debugging. Prints out the chain using log_debug if
425 IOBUF_DEBUG_MODE is not 0. */
426 int iobuf_print_chain (iobuf_t a);
428 /* Indicate that some error occurred on the specified filter. */
429 #define iobuf_set_error(a) do { (a)->error = 1; } while(0)
431 /* Return any pending error on filter A. */
432 #define iobuf_error(a) ((a)->error)
434 /* Limit the amount of additional data that may be read from the
435 filter. That is, if you've already read 100 bytes from A and you
436 set the limit to 50, then you can read up to an additional 50 bytes
437 (i.e., a total of 150 bytes) before EOF is forcefully returned.
438 Setting NLIMIT to 0 removes any active limit.
440 Note: using iobuf_seek removes any currently enforced limit! */
441 void iobuf_set_limit (iobuf_t a, off_t nlimit);
443 /* Returns the number of bytes that have been read from the pipeline.
444 Note: the result is undefined for IOBUF_OUTPUT and IOBUF_OUTPUT_TEMP
446 off_t iobuf_tell (iobuf_t a);
448 /* There are two cases:
450 - If A is an INPUT or OUTPUT pipeline, then the last filter in the
451 pipeline is found. If that is not a file filter, -1 is returned.
452 Otherwise, an fseek(..., SEEK_SET) is performed on the file
455 - If A is a TEMP pipeline and the *first* (and thus only filter) is
456 a TEMP filter, then the "file position" is effectively unchanged.
457 That is, data is appended to the buffer and the seek does not
458 cause the size of the buffer to grow.
460 If no error occurred, then any limit previous set by
461 iobuf_set_limit() is cleared. Further, any error on the filter
462 (the file filter or the temp filter) is cleared.
464 Returns 0 on success and -1 if an error occurs. */
465 int iobuf_seek (iobuf_t a, off_t newpos);
467 /* Read a single byte. If a filter has no more data, returns -1 to
468 indicate the EOF. Generally, you don't want to use this function,
469 but instead prefer the iobuf_get macro, which is faster if there is
470 data in the internal buffer. */
471 int iobuf_readbyte (iobuf_t a);
473 /* Get a byte from the iobuf; must check for eof prior to this
474 function. This function returns values in the range 0 .. 255 or -1
475 to indicate EOF. iobuf_get_noeof() does not return -1 to indicate
476 EOF, but masks the returned value to be in the range 0 .. 255. */
477 #define iobuf_get(a) \
478 ( ((a)->nofast || (a)->d.start >= (a)->d.len )? \
479 iobuf_readbyte((a)) : ( (a)->nbytes++, (a)->d.buf[(a)->d.start++] ) )
480 #define iobuf_get_noeof(a) (iobuf_get((a))&0xff)
482 /* Fill BUF with up to BUFLEN bytes. If a filter has no more data,
483 returns -1 to indicate the EOF. Otherwise returns the number of
485 int iobuf_read (iobuf_t a, void *buf, unsigned buflen);
487 /* Read a line of input (including the '\n') from the pipeline.
489 The semantics are the same as for fgets(), but if the buffer is too
490 short a larger one will be allocated up to *MAX_LENGTH and the end
491 of the line except the trailing '\n' discarded. (Thus,
492 *ADDR_OF_BUFFER must be allocated using malloc().) If the buffer
493 is enlarged, then *LENGTH_OF_BUFFER will be updated to reflect the
494 new size. If the line is truncated, then *MAX_LENGTH will be set
495 to 0. If *ADDR_OF_BUFFER is NULL, a buffer is allocated using
498 A line is considered a byte stream ending in a '\n'. Returns the
499 number of characters written to the buffer (i.e., excluding any
500 discarded characters due to truncation). Thus, use this instead of
501 strlen(buffer) to determine the length of the string as this is
502 unreliable if the input contains NUL characters.
504 EOF is indicated by a line of length zero.
506 The last LF may be missing due to an EOF. */
507 unsigned iobuf_read_line (iobuf_t a, byte ** addr_of_buffer,
508 unsigned *length_of_buffer, unsigned *max_length);
510 /* Read up to BUFLEN bytes from pipeline A. Note: this function can't
511 return more than the pipeline's internal buffer size. The return
512 value is the number of bytes actually written to BUF. If the
513 filter returns EOF, then this function returns -1.
515 This function does not clear any pending EOF. That is, if the
516 pipeline consists of two filters and the first one returns EOF
517 during the peek, then the subsequent iobuf_read* will still return
518 EOF before returning the data from the second filter. */
519 int iobuf_peek (iobuf_t a, byte * buf, unsigned buflen);
521 /* Write a byte to the pipeline. Returns 0 on success and an error
523 int iobuf_writebyte (iobuf_t a, unsigned c);
525 /* Alias for iobuf_writebyte. */
526 #define iobuf_put(a,c) iobuf_writebyte(a,c)
528 /* Write a sequence of bytes to the pipeline. Returns 0 on success
529 and an error code otherwise. */
530 int iobuf_write (iobuf_t a, const void *buf, unsigned buflen);
532 /* Write a string (not including the NUL terminator) to the pipeline.
533 Returns 0 on success and an error code otherwise. */
534 int iobuf_writestr (iobuf_t a, const char *buf);
536 /* Flushes the pipeline removing all filters but the sink (the last
537 filter) in the process. */
538 void iobuf_flush_temp (iobuf_t temp);
540 /* Flushes the pipeline SOURCE removing all filters but the sink (the
541 last filter) in the process (i.e., it calls
542 iobuf_flush_temp(source)) and then writes the data to the pipeline
543 DEST. Note: this doesn't free (iobuf_close()) SOURCE. Both SOURCE
544 and DEST must be output pipelines. */
545 int iobuf_write_temp (iobuf_t dest, iobuf_t source);
547 /* Flushes each filter in the pipeline (i.e., sends any buffered data
548 to the filter by calling IOBUFCTRL_FLUSH). Then, copies up to the
549 first BUFLEN bytes from the last filter's internal buffer (which
550 will only be non-empty if it is a temp filter) to the buffer
551 BUFFER. Returns the number of bytes actually copied. */
552 size_t iobuf_temp_to_buffer (iobuf_t a, byte * buffer, size_t buflen);
554 /* Copies the data from the input iobuf SOURCE to the output iobuf
555 DEST until either an error is encountered or EOF is reached.
556 Returns the number of bytes successfully written. If an error
557 occurred, then any buffered bytes are not returned to SOURCE and are
558 effectively lost. To check if an error occurred, use
560 size_t iobuf_copy (iobuf_t dest, iobuf_t source);
562 /* Return the size of any underlying file. This only works with
563 file_filter based pipelines.
565 On Win32, it is sometimes not possible to determine the size of
566 files larger than 4GB. In this case, *OVERFLOW (if not NULL) is
567 set to 1. Otherwise, *OVERFLOW is set to 0. */
568 off_t iobuf_get_filelength (iobuf_t a, int *overflow);
569 #define IOBUF_FILELENGTH_LIMIT 0xffffffff
571 /* Return the file descriptor designating the underlying file. This
572 only works with file_filter based pipelines. */
573 int iobuf_get_fd (iobuf_t a);
575 /* Return the real filename, if available. This only supports
576 pipelines that end in file filters. Returns NULL if not
578 const char *iobuf_get_real_fname (iobuf_t a);
580 /* Return the filename or a description thereof. For instance, for
581 iobuf_open("-"), this will return "[stdin]". This only supports
582 pipelines that end in file filters. Returns NULL if not
584 const char *iobuf_get_fname (iobuf_t a);
586 /* Like iobuf_getfname, but instead of returning NULL if no
587 description is available, return "[?]". */
588 const char *iobuf_get_fname_nonnull (iobuf_t a);
590 /* Pushes a filter on the pipeline that interprets the datastream as
591 an OpenPGP data block whose length is encoded using partial body
592 length headers (see Section 4.2.2.4 of RFC 4880). Concretely, it
593 just returns / writes the data and finishes the packet with an
595 void iobuf_set_partial_block_mode (iobuf_t a, size_t len);
597 /* If PARTIAL is set, then read from the pipeline until the first EOF
600 If PARTIAL is 0, then read up to N bytes or until the first EOF is
603 Recall: a filter can return EOF. In this case, it and all
604 preceding filters are popped from the pipeline and the next read is
605 from the following filter (which may or may not return EOF). */
606 void iobuf_skip_rest (iobuf_t a, unsigned long n, int partial);
608 #define iobuf_where(a) "[don't know]"
610 /* Each time a filter is allocated (via iobuf_alloc()), a
611 monotonically increasing counter is incremented and this field is
612 set to the new value. This macro returns that number. */
613 #define iobuf_id(a) ((a)->no)
615 #define iobuf_get_temp_buffer(a) ( (a)->d.buf )
616 #define iobuf_get_temp_length(a) ( (a)->d.len )
618 /* Whether the filter uses an in-memory buffer. */
619 #define iobuf_is_temp(a) ( (a)->use == IOBUF_OUTPUT_TEMP )
621 #endif /*GNUPG_COMMON_IOBUF_H*/