Mercurial > dovecot > core-2.2

annotate src/lib/istream.h @ 22664:fea53c2725c0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
director: Fix director_max_parallel_moves/kicks type Should be uint, not time.
author Timo Sirainen <timo.sirainen@dovecot.fi>
date Thu, 09 Nov 2017 12:24:16 +0200
parents 9f7806638fa3
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6410
e4eb71ae8e96 Changed .h ifdef/defines to use <NAME>_H format.
Timo Sirainen <tss@iki.fi>
parents: 6162
diff changeset
1 #ifndef ISTREAM_H
e4eb71ae8e96 Changed .h ifdef/defines to use <NAME>_H format.
Timo Sirainen <tss@iki.fi>
parents: 6162
diff changeset
2 #define ISTREAM_H
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
3
4292
5f1069459a07 Include <sys/stat.h> before using struct stat, because some systems may use
Timo Sirainen <tss@iki.fi>
parents: 4070
diff changeset
4 /* Note that some systems (Solaris) may use a macro to redefine struct stat */
5f1069459a07 Include <sys/stat.h> before using struct stat, because some systems may use
Timo Sirainen <tss@iki.fi>
parents: 4070
diff changeset
5 #include <sys/stat.h>
5f1069459a07 Include <sys/stat.h> before using struct stat, because some systems may use
Timo Sirainen <tss@iki.fi>
parents: 4070
diff changeset
6
903
fd8888f6f037 Naming style changes, finally got tired of most of the typedefs. Also the
Timo Sirainen <tss@iki.fi>
parents: 898
diff changeset
7 struct istream {
1870
c972ea085643 istream rewrite. instead of directly setting any limits to stream, you now
Timo Sirainen <tss@iki.fi>
parents: 1861
diff changeset
8 uoff_t v_offset;
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
9
20502
b6ae3fe5def8 lib: Updated istream's stream_errno comments.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20244
diff changeset
10 /* Commonly used errors:
b6ae3fe5def8 lib: Updated istream's stream_errno comments.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20244
diff changeset
11
b6ae3fe5def8 lib: Updated istream's stream_errno comments.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20244
diff changeset
12 ENOENT - File/object doesn't exist.
b6ae3fe5def8 lib: Updated istream's stream_errno comments.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20244
diff changeset
13 EPIPE - Stream ended unexpectedly (or i_stream_close() was called).
b6ae3fe5def8 lib: Updated istream's stream_errno comments.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20244
diff changeset
14 ESPIPE - i_stream_seek() was used on a stream that can't be seeked.
b6ae3fe5def8 lib: Updated istream's stream_errno comments.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20244
diff changeset
15 ENOBUFS - i_stream_read_next_line() was used for a too long line.
b6ae3fe5def8 lib: Updated istream's stream_errno comments.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20244
diff changeset
16 EIO - Internal error. Retrying may work, but it may also be
b6ae3fe5def8 lib: Updated istream's stream_errno comments.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20244
diff changeset
17 because of a misconfiguration.
b6ae3fe5def8 lib: Updated istream's stream_errno comments.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20244
diff changeset
18 EINVAL - Stream is corrupted.
b6ae3fe5def8 lib: Updated istream's stream_errno comments.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20244
diff changeset
19 */
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
20 int stream_errno;
20502
b6ae3fe5def8 lib: Updated istream's stream_errno comments.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20244
diff changeset
21
1197
e86f259048cf o_stream_send_istream() is now safe to use for moving data within file.
Timo Sirainen <tss@iki.fi>
parents: 1027
diff changeset
22 unsigned int mmaped:1; /* be careful when copying data */
5106
81394e71f92a Added istream->blocking setting. It's now used to assert-crash early if a
Timo Sirainen <tss@iki.fi>
parents: 4451
diff changeset
23 unsigned int blocking:1; /* read() shouldn't return 0 */
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
24 unsigned int closed:1;
9540
622509c562e8 Added struct istream.readable_fd, which is used to determine if sendfile() can be used.
Timo Sirainen <tss@iki.fi>
parents: 8969
diff changeset
25 unsigned int readable_fd:1; /* fd can be read directly if necessary
622509c562e8 Added struct istream.readable_fd, which is used to determine if sendfile() can be used.
Timo Sirainen <tss@iki.fi>
parents: 8969
diff changeset
26 (for sendfile()) */
3239
904a268921af Added seekable variable to struct istream.
Timo Sirainen <tss@iki.fi>
parents: 2788
diff changeset
27 unsigned int seekable:1; /* we can seek() backwards */
2788
f322b24da429 Added i_stream_have_bytes_left().
Timo Sirainen <tss@iki.fi>
parents: 2626
diff changeset
28 unsigned int eof:1; /* read() has reached to end of file
f322b24da429 Added i_stream_have_bytes_left().
Timo Sirainen <tss@iki.fi>
parents: 2626
diff changeset
29 (but may still be data available in buffer) */
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
30
6415
b0096861c390 Renamed struct _[io]stream to struct [io]stream_private. Also removed _
Timo Sirainen <tss@iki.fi>
parents: 6410
diff changeset
31 struct istream_private *real_stream;
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
32 };
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
33
7023
56a5a00e490c Added i_stream_set_destroy_callback().
Timo Sirainen <tss@iki.fi>
parents: 6415
diff changeset
34 typedef void istream_callback_t(void *context);
56a5a00e490c Added i_stream_set_destroy_callback().
Timo Sirainen <tss@iki.fi>
parents: 6415
diff changeset
35
6162
896cc473c1f0 Renamed i_stream_create_file() to i_stream_create_fd().
Timo Sirainen <tss@iki.fi>
parents: 6142
diff changeset
36 struct istream *i_stream_create_fd(int fd, size_t max_buffer_size,
896cc473c1f0 Renamed i_stream_create_file() to i_stream_create_fd().
Timo Sirainen <tss@iki.fi>
parents: 6142
diff changeset
37 bool autoclose_fd);
17479
0bcb43692d91 lib: Added [io]_stream_create_fd_*autoclose()
Timo Sirainen <tss@iki.fi>
parents: 17188
diff changeset
38 /* The fd is set to -1 immediately to avoid accidentally closing it twice. */
0bcb43692d91 lib: Added [io]_stream_create_fd_*autoclose()
Timo Sirainen <tss@iki.fi>
parents: 17188
diff changeset
39 struct istream *i_stream_create_fd_autoclose(int *fd, size_t max_buffer_size);
11829
b7d98c5db865 Added i_stream_create_file() for creating istream from lazily opened file.
Timo Sirainen <tss@iki.fi>
parents: 10847
diff changeset
40 /* Open the given path only when something is actually tried to be read from
b7d98c5db865 Added i_stream_create_file() for creating istream from lazily opened file.
Timo Sirainen <tss@iki.fi>
parents: 10847
diff changeset
41 the stream. */
b7d98c5db865 Added i_stream_create_file() for creating istream from lazily opened file.
Timo Sirainen <tss@iki.fi>
parents: 10847
diff changeset
42 struct istream *i_stream_create_file(const char *path, size_t max_buffer_size);
6142
6c0bfc35af03 Removed memory pool parameter from iostreams. Default pool was almost always
Timo Sirainen <tss@iki.fi>
parents: 5106
diff changeset
43 struct istream *i_stream_create_mmap(int fd, size_t block_size,
903
fd8888f6f037 Naming style changes, finally got tired of most of the typedefs. Also the
Timo Sirainen <tss@iki.fi>
parents: 898
diff changeset
44 uoff_t start_offset, uoff_t v_size,
3863
55df57c028d4 Added "bool" type and changed all ints that were used as booleans to bool.
Timo Sirainen <tss@iki.fi>
parents: 3710
diff changeset
45 bool autoclose_fd);
20640
9f7806638fa3 lib: Implemented i_stream_create_copy_from_data().
Stephan Bosch <stephan@rename-it.nl>
parents: 20502
diff changeset
46 /* Create an input stream using the provided data block. That data block must
9f7806638fa3 lib: Implemented i_stream_create_copy_from_data().
Stephan Bosch <stephan@rename-it.nl>
parents: 20502
diff changeset
47 remain allocated during the full lifetime of the stream. */
6142
6c0bfc35af03 Removed memory pool parameter from iostreams. Default pool was almost always
Timo Sirainen <tss@iki.fi>
parents: 5106
diff changeset
48 struct istream *i_stream_create_from_data(const void *data, size_t size);
18238
43a61a8bf9c5 lib: istream create helpers for common cases
Phil Carmody <phil@dovecot.fi>
parents: 17511
diff changeset
49 #define i_stream_create_from_buffer(buf) \
43a61a8bf9c5 lib: istream create helpers for common cases
Phil Carmody <phil@dovecot.fi>
parents: 17511
diff changeset
50 i_stream_create_from_data((buf)->data, (buf)->used)
43a61a8bf9c5 lib: istream create helpers for common cases
Phil Carmody <phil@dovecot.fi>
parents: 17511
diff changeset
51 #define i_stream_create_from_string(str) \
43a61a8bf9c5 lib: istream create helpers for common cases
Phil Carmody <phil@dovecot.fi>
parents: 17511
diff changeset
52 i_stream_create_from_data(str_data(str), str_len(str))
20640
9f7806638fa3 lib: Implemented i_stream_create_copy_from_data().
Stephan Bosch <stephan@rename-it.nl>
parents: 20502
diff changeset
53 /* Create an input stream using a copy of the provided data block. The
9f7806638fa3 lib: Implemented i_stream_create_copy_from_data().
Stephan Bosch <stephan@rename-it.nl>
parents: 20502
diff changeset
54 provided data block may be freed at any time. The copy is freed when the
9f7806638fa3 lib: Implemented i_stream_create_copy_from_data().
Stephan Bosch <stephan@rename-it.nl>
parents: 20502
diff changeset
55 stream is destroyed. */
9f7806638fa3 lib: Implemented i_stream_create_copy_from_data().
Stephan Bosch <stephan@rename-it.nl>
parents: 20502
diff changeset
56 struct istream *
9f7806638fa3 lib: Implemented i_stream_create_copy_from_data().
Stephan Bosch <stephan@rename-it.nl>
parents: 20502
diff changeset
57 i_stream_create_copy_from_data(const void *data, size_t size);
9f7806638fa3 lib: Implemented i_stream_create_copy_from_data().
Stephan Bosch <stephan@rename-it.nl>
parents: 20502
diff changeset
58 #define i_stream_create_copy_from_buffer(buf) \
9f7806638fa3 lib: Implemented i_stream_create_copy_from_data().
Stephan Bosch <stephan@rename-it.nl>
parents: 20502
diff changeset
59 i_stream_create_copy_from_data((buf)->data, (buf)->used)
9f7806638fa3 lib: Implemented i_stream_create_copy_from_data().
Stephan Bosch <stephan@rename-it.nl>
parents: 20502
diff changeset
60 #define i_stream_create_copy_from_string(str) \
9f7806638fa3 lib: Implemented i_stream_create_copy_from_data().
Stephan Bosch <stephan@rename-it.nl>
parents: 20502
diff changeset
61 i_stream_create_copy_from_data(str_data(str), str_len(str))
7031
4b51ee73ed51 Removed v_start_offset parameter from i_stream_create_limit(). We'll always
Timo Sirainen <tss@iki.fi>
parents: 7023
diff changeset
62 struct istream *i_stream_create_limit(struct istream *input, uoff_t v_size);
14943
34e4c04ae679 Added i_stream_create_range()
Timo Sirainen <tss@iki.fi>
parents: 14921
diff changeset
63 struct istream *i_stream_create_range(struct istream *input,
34e4c04ae679 Added i_stream_create_range()
Timo Sirainen <tss@iki.fi>
parents: 14921
diff changeset
64 uoff_t v_offset, uoff_t v_size);
15174
f860cdf156cf Added [io]_stream_create_error() for creating streams that always fail reads/writes.
Timo Sirainen <tss@iki.fi>
parents: 14964
diff changeset
65 struct istream *i_stream_create_error(int stream_errno);
16813
a919c43ab91b lib: Added [io]_stream_create_error_str()
Timo Sirainen <tss@iki.fi>
parents: 16772
diff changeset
66 struct istream *
a919c43ab91b lib: Added [io]_stream_create_error_str()
Timo Sirainen <tss@iki.fi>
parents: 16772
diff changeset
67 i_stream_create_error_str(int stream_errno, const char *fmt, ...)
a919c43ab91b lib: Added [io]_stream_create_error_str()
Timo Sirainen <tss@iki.fi>
parents: 16772
diff changeset
68 ATTR_FORMAT(2, 3);
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
69
10847
5f16e488e7f6 i/ostreams can now have a name (e.g. file path).
Timo Sirainen <tss@iki.fi>
parents: 9777
diff changeset
70 /* Set name (e.g. path) for input stream. */
5f16e488e7f6 i/ostreams can now have a name (e.g. file path).
Timo Sirainen <tss@iki.fi>
parents: 9777
diff changeset
71 void i_stream_set_name(struct istream *stream, const char *name);
5f16e488e7f6 i/ostreams can now have a name (e.g. file path).
Timo Sirainen <tss@iki.fi>
parents: 9777
diff changeset
72 /* Get input stream's name. If stream itself doesn't have a name,
5f16e488e7f6 i/ostreams can now have a name (e.g. file path).
Timo Sirainen <tss@iki.fi>
parents: 9777
diff changeset
73 it looks up further into stream's parents until one of them has a name.
5f16e488e7f6 i/ostreams can now have a name (e.g. file path).
Timo Sirainen <tss@iki.fi>
parents: 9777
diff changeset
74 Returns "" if stream has no name. */
5f16e488e7f6 i/ostreams can now have a name (e.g. file path).
Timo Sirainen <tss@iki.fi>
parents: 9777
diff changeset
75 const char *i_stream_get_name(struct istream *stream);
5f16e488e7f6 i/ostreams can now have a name (e.g. file path).
Timo Sirainen <tss@iki.fi>
parents: 9777
diff changeset
76
16020
6cabb95d32ec iostreams: Added close_parent flag to close() handler and clarified close/destroy APIs.
Timo Sirainen <tss@iki.fi>
parents: 15640
diff changeset
77 /* Close this stream (but not its parents) and unreference it. */
4070
71b8faa84ec6 Added i_stream_destroy() and o_stream_destroy() and used them instead of
Timo Sirainen <tss@iki.fi>
parents: 3879
diff changeset
78 void i_stream_destroy(struct istream **stream);
71b8faa84ec6 Added i_stream_destroy() and o_stream_destroy() and used them instead of
Timo Sirainen <tss@iki.fi>
parents: 3879
diff changeset
79
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
80 /* Reference counting. References start from 1, so calling i_stream_unref()
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
81 destroys the stream if i_stream_ref() is never used. */
903
fd8888f6f037 Naming style changes, finally got tired of most of the typedefs. Also the
Timo Sirainen <tss@iki.fi>
parents: 898
diff changeset
82 void i_stream_ref(struct istream *stream);
3879
928229f8b3e6 deinit, unref, destroy, close, free, etc. functions now take a pointer to
Timo Sirainen <tss@iki.fi>
parents: 3863
diff changeset
83 /* Unreferences the stream and sets stream pointer to NULL. */
928229f8b3e6 deinit, unref, destroy, close, free, etc. functions now take a pointer to
Timo Sirainen <tss@iki.fi>
parents: 3863
diff changeset
84 void i_stream_unref(struct istream **stream);
7023
56a5a00e490c Added i_stream_set_destroy_callback().
Timo Sirainen <tss@iki.fi>
parents: 6415
diff changeset
85 /* Call the given callback function when stream is destroyed. */
16236
81d87e43e167 istream API change: Added support for multiple destroy callbacks.
Timo Sirainen <tss@iki.fi>
parents: 16020
diff changeset
86 void i_stream_add_destroy_callback(struct istream *stream,
14629
c93ca5e46a8a Marked functions parameters that are allowed to be NULL. Some APIs were also changed.
Timo Sirainen <tss@iki.fi>
parents: 13861
diff changeset
87 istream_callback_t *callback, void *context)
c93ca5e46a8a Marked functions parameters that are allowed to be NULL. Some APIs were also changed.
Timo Sirainen <tss@iki.fi>
parents: 13861
diff changeset
88 ATTR_NULL(3);
16236
81d87e43e167 istream API change: Added support for multiple destroy callbacks.
Timo Sirainen <tss@iki.fi>
parents: 16020
diff changeset
89 #define i_stream_add_destroy_callback(stream, callback, context) \
81d87e43e167 istream API change: Added support for multiple destroy callbacks.
Timo Sirainen <tss@iki.fi>
parents: 16020
diff changeset
90 i_stream_add_destroy_callback(stream + \
14921
d3db2ba15d00 Removed CONTEXT_TYPE_SAFETY macro and reimplemented its functionality better.
Timo Sirainen <tss@iki.fi>
parents: 14875
diff changeset
91 CALLBACK_TYPECHECK(callback, void (*)(typeof(context))), \
d3db2ba15d00 Removed CONTEXT_TYPE_SAFETY macro and reimplemented its functionality better.
Timo Sirainen <tss@iki.fi>
parents: 14875
diff changeset
92 (istream_callback_t *)callback, context)
13861
46a1f211ef84 Added i_stream_unset_destroy_callback()
Timo Sirainen <tss@iki.fi>
parents: 12225
diff changeset
93 /* Remove the destroy callback. */
16236
81d87e43e167 istream API change: Added support for multiple destroy callbacks.
Timo Sirainen <tss@iki.fi>
parents: 16020
diff changeset
94 void i_stream_remove_destroy_callback(struct istream *stream,
81d87e43e167 istream API change: Added support for multiple destroy callbacks.
Timo Sirainen <tss@iki.fi>
parents: 16020
diff changeset
95 void (*callback)());
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
96
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
97 /* Return file descriptor for stream, or -1 if none is available. */
903
fd8888f6f037 Naming style changes, finally got tired of most of the typedefs. Also the
Timo Sirainen <tss@iki.fi>
parents: 898
diff changeset
98 int i_stream_get_fd(struct istream *stream);
19549
dd68e15cdc22 lib: i_stream_get_error() now returns "EOF" if stream_errno==0 and eof==TRUE.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 18238
diff changeset
99 /* Returns error string for the last error. It also returns "EOF" in case there
dd68e15cdc22 lib: i_stream_get_error() now returns "EOF" if stream_errno==0 and eof==TRUE.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 18238
diff changeset
100 is no error, but eof is set. Otherwise it returns "<no error>". */
16772
e35be66003e2 iostream: Added ability to set/get error strings for streams.
Timo Sirainen <tss@iki.fi>
parents: 16236
diff changeset
101 const char *i_stream_get_error(struct istream *stream);
20145
f2fba1ef02c4 lib: Added i_stream_get_disconnect_reason()
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 19751
diff changeset
102 /* Returns human-readable reason for why istream was disconnected. This can be
f2fba1ef02c4 lib: Added i_stream_get_disconnect_reason()
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 19751
diff changeset
103 called to log the error when i_stream_read() returns -1. If there's an error
f2fba1ef02c4 lib: Added i_stream_get_disconnect_reason()
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 19751
diff changeset
104 the output is identical to i_stream_get_error(). */
f2fba1ef02c4 lib: Added i_stream_get_disconnect_reason()
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 19751
diff changeset
105 const char *i_stream_get_disconnect_reason(struct istream *stream);
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
106
16020
6cabb95d32ec iostreams: Added close_parent flag to close() handler and clarified close/destroy APIs.
Timo Sirainen <tss@iki.fi>
parents: 15640
diff changeset
107 /* Mark the stream and all of its parent streams closed. Any reads after this
6cabb95d32ec iostreams: Added close_parent flag to close() handler and clarified close/destroy APIs.
Timo Sirainen <tss@iki.fi>
parents: 15640
diff changeset
108 will return -1. The data already read can still be used. */
903
fd8888f6f037 Naming style changes, finally got tired of most of the typedefs. Also the
Timo Sirainen <tss@iki.fi>
parents: 898
diff changeset
109 void i_stream_close(struct istream *stream);
3241
b79853b4b005 Replaced i_stream_get_size() with i_stream_stat(). Added i_stream_sync().
Timo Sirainen <tss@iki.fi>
parents: 3240
diff changeset
110 /* Sync the stream with the underlying backend, ie. if a file has been
b79853b4b005 Replaced i_stream_get_size() with i_stream_stat(). Added i_stream_sync().
Timo Sirainen <tss@iki.fi>
parents: 3240
diff changeset
111 modified, flush any cached data. */
b79853b4b005 Replaced i_stream_get_size() with i_stream_stat(). Added i_stream_sync().
Timo Sirainen <tss@iki.fi>
parents: 3240
diff changeset
112 void i_stream_sync(struct istream *stream);
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
113
9777
85abd99007c3 Added i_stream_set_init_buffer_size().
Timo Sirainen <tss@iki.fi>
parents: 9540
diff changeset
114 /* Change the initial size for stream's input buffer. This basically just
85abd99007c3 Added i_stream_set_init_buffer_size().
Timo Sirainen <tss@iki.fi>
parents: 9540
diff changeset
115 grows the read buffer size from the default. This function has no effect
85abd99007c3 Added i_stream_set_init_buffer_size().
Timo Sirainen <tss@iki.fi>
parents: 9540
diff changeset
116 unless it's called before reading anything. */
85abd99007c3 Added i_stream_set_init_buffer_size().
Timo Sirainen <tss@iki.fi>
parents: 9540
diff changeset
117 void i_stream_set_init_buffer_size(struct istream *stream, size_t size);
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
118 /* Change the maximum size for stream's input buffer to grow. Useful only
20244
fd39559c4533 lib: i_stream_get_max_buffer_size() checks also parents' max sizes
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20179
diff changeset
119 for buffered streams (currently only file). This changes also all the
fd39559c4533 lib: i_stream_get_max_buffer_size() checks also parents' max sizes
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20179
diff changeset
120 parent streams' max buffer size. */
903
fd8888f6f037 Naming style changes, finally got tired of most of the typedefs. Also the
Timo Sirainen <tss@iki.fi>
parents: 898
diff changeset
121 void i_stream_set_max_buffer_size(struct istream *stream, size_t max_size);
20244
fd39559c4533 lib: i_stream_get_max_buffer_size() checks also parents' max sizes
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20179
diff changeset
122 /* Returns the current max. buffer size for the stream. This function also
fd39559c4533 lib: i_stream_get_max_buffer_size() checks also parents' max sizes
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20179
diff changeset
123 goesthrough all of the parent streams and returns the highest seen max
fd39559c4533 lib: i_stream_get_max_buffer_size() checks also parents' max sizes
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20179
diff changeset
124 buffer size. This is needed because some streams (e.g. istream-chain) change
fd39559c4533 lib: i_stream_get_max_buffer_size() checks also parents' max sizes
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20179
diff changeset
125 their max buffer size dynamically. */
11992
136ce9b2e039 Added i_stream_get_max_buffer_size().
Timo Sirainen <tss@iki.fi>
parents: 11829
diff changeset
126 size_t i_stream_get_max_buffer_size(struct istream *stream);
8438
1baa595093f5 Added i_stream_set_return_partial_line().
Timo Sirainen <tss@iki.fi>
parents: 7978
diff changeset
127 /* Enable/disable i_stream[_read]_next_line() returning the last line if it
1baa595093f5 Added i_stream_set_return_partial_line().
Timo Sirainen <tss@iki.fi>
parents: 7978
diff changeset
128 doesn't end with LF. */
1baa595093f5 Added i_stream_set_return_partial_line().
Timo Sirainen <tss@iki.fi>
parents: 7978
diff changeset
129 void i_stream_set_return_partial_line(struct istream *stream, bool set);
19751
1e0cfc3dc89a lib: Added i_stream_set_persistent_buffers()
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 19549
diff changeset
130 /* Change whether buffers are allocated persistently (default=TRUE). When not,
1e0cfc3dc89a lib: Added i_stream_set_persistent_buffers()
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 19549
diff changeset
131 the memory usage is minimized by freeing the stream's buffers whenever they
1e0cfc3dc89a lib: Added i_stream_set_persistent_buffers()
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 19549
diff changeset
132 become empty. */
1e0cfc3dc89a lib: Added i_stream_set_persistent_buffers()
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 19549
diff changeset
133 void i_stream_set_persistent_buffers(struct istream *stream, bool set);
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
134
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
135 /* Returns number of bytes read if read was ok, -1 if EOF or error, -2 if the
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
136 input buffer is full. */
903
fd8888f6f037 Naming style changes, finally got tired of most of the typedefs. Also the
Timo Sirainen <tss@iki.fi>
parents: 898
diff changeset
137 ssize_t i_stream_read(struct istream *stream);
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
138 /* Skip forward a number of bytes. Never fails, the next read tells if it
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
139 was successful. */
903
fd8888f6f037 Naming style changes, finally got tired of most of the typedefs. Also the
Timo Sirainen <tss@iki.fi>
parents: 898
diff changeset
140 void i_stream_skip(struct istream *stream, uoff_t count);
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
141 /* Seek to specified position from beginning of file. Never fails, the next
20502
b6ae3fe5def8 lib: Updated istream's stream_errno comments.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20244
diff changeset
142 read tells if it was successful. This works only for files, others will
b6ae3fe5def8 lib: Updated istream's stream_errno comments.
Timo Sirainen <timo.sirainen@dovecot.fi>
parents: 20244
diff changeset
143 set stream_errno=ESPIPE. */
903
fd8888f6f037 Naming style changes, finally got tired of most of the typedefs. Also the
Timo Sirainen <tss@iki.fi>
parents: 898
diff changeset
144 void i_stream_seek(struct istream *stream, uoff_t v_offset);
3629
e05a1af4bbc7 Added i_stream_seek_mark() and used it
Timo Sirainen <tss@iki.fi>
parents: 3520
diff changeset
145 /* Like i_stream_seek(), but also giving a hint that after reading some data
e05a1af4bbc7 Added i_stream_seek_mark() and used it
Timo Sirainen <tss@iki.fi>
parents: 3520
diff changeset
146 we could be seeking back to this mark or somewhere after it. If input
e05a1af4bbc7 Added i_stream_seek_mark() and used it
Timo Sirainen <tss@iki.fi>
parents: 3520
diff changeset
147 stream's implementation is slow in seeking backwards, it can use this hint
e05a1af4bbc7 Added i_stream_seek_mark() and used it
Timo Sirainen <tss@iki.fi>
parents: 3520
diff changeset
148 to cache some of the data in memory. */
e05a1af4bbc7 Added i_stream_seek_mark() and used it
Timo Sirainen <tss@iki.fi>
parents: 3520
diff changeset
149 void i_stream_seek_mark(struct istream *stream, uoff_t v_offset);
14964
6d2be8d8891c i_stream_stat() API changed.
Timo Sirainen <tss@iki.fi>
parents: 14943
diff changeset
150 /* Returns 0 if ok, -1 if error. As the underlying stream may not be
3241
b79853b4b005 Replaced i_stream_get_size() with i_stream_stat(). Added i_stream_sync().
Timo Sirainen <tss@iki.fi>
parents: 3240
diff changeset
151 a file, only some of the fields might be set, others would be zero.
3647
7af5162d934c Added exact parameter to i_stream_stat()
Timo Sirainen <tss@iki.fi>
parents: 3629
diff changeset
152 st_size is always set, and if it's not known, it's -1.
7af5162d934c Added exact parameter to i_stream_stat()
Timo Sirainen <tss@iki.fi>
parents: 3629
diff changeset
153
7af5162d934c Added exact parameter to i_stream_stat()
Timo Sirainen <tss@iki.fi>
parents: 3629
diff changeset
154 If exact=FALSE, the stream may not return exactly correct values, but the
7af5162d934c Added exact parameter to i_stream_stat()
Timo Sirainen <tss@iki.fi>
parents: 3629
diff changeset
155 returned values can be compared to see if anything had changed (eg. in
7af5162d934c Added exact parameter to i_stream_stat()
Timo Sirainen <tss@iki.fi>
parents: 3629
diff changeset
156 compressed stream st_size could be compressed size) */
14964
6d2be8d8891c i_stream_stat() API changed.
Timo Sirainen <tss@iki.fi>
parents: 14943
diff changeset
157 int i_stream_stat(struct istream *stream, bool exact, const struct stat **st_r);
8922
5106852f552a Added i_stream_get_size(). Use it instead of i_stream_stat() where possible.
Timo Sirainen <tss@iki.fi>
parents: 8438
diff changeset
158 /* Similar to i_stream_stat() call. Returns 1 if size was successfully
5106852f552a Added i_stream_get_size(). Use it instead of i_stream_stat() where possible.
Timo Sirainen <tss@iki.fi>
parents: 8438
diff changeset
159 set, 0 if size is unknown, -1 if error. */
5106852f552a Added i_stream_get_size(). Use it instead of i_stream_stat() where possible.
Timo Sirainen <tss@iki.fi>
parents: 8438
diff changeset
160 int i_stream_get_size(struct istream *stream, bool exact, uoff_t *size_r);
2788
f322b24da429 Added i_stream_have_bytes_left().
Timo Sirainen <tss@iki.fi>
parents: 2626
diff changeset
161 /* Returns TRUE if there are any bytes left to be read or in buffer. */
17511
0d072ade062d lib: i_stream_get_data() should also reset eof=FALSE if it truncates the output.
Timo Sirainen <tss@iki.fi>
parents: 17479
diff changeset
162 bool i_stream_have_bytes_left(struct istream *stream);
8969
5deb3ee1d655 Added i_stream_is_eof().
Timo Sirainen <tss@iki.fi>
parents: 8922
diff changeset
163 /* Returns TRUE if there are no bytes buffered and read() returns EOF. */
5deb3ee1d655 Added i_stream_is_eof().
Timo Sirainen <tss@iki.fi>
parents: 8922
diff changeset
164 bool i_stream_is_eof(struct istream *stream);
12225
0c82fe7ce578 Added i_stream_get_absolute_offset().
Timo Sirainen <tss@iki.fi>
parents: 11992
diff changeset
165 /* Returns the absolute offset of the stream. This is the stream's current
0c82fe7ce578 Added i_stream_get_absolute_offset().
Timo Sirainen <tss@iki.fi>
parents: 11992
diff changeset
166 v_offset + the parent's absolute offset when the stream was created. */
0c82fe7ce578 Added i_stream_get_absolute_offset().
Timo Sirainen <tss@iki.fi>
parents: 11992
diff changeset
167 uoff_t i_stream_get_absolute_offset(struct istream *stream);
2788
f322b24da429 Added i_stream_have_bytes_left().
Timo Sirainen <tss@iki.fi>
parents: 2626
diff changeset
168
1293
2f2c6335ed6d Added i_stream_read_next_line()
Timo Sirainen <tss@iki.fi>
parents: 1197
diff changeset
169 /* Gets the next line from stream and returns it, or NULL if more data is
8438
1baa595093f5 Added i_stream_set_return_partial_line().
Timo Sirainen <tss@iki.fi>
parents: 7978
diff changeset
170 needed to make a full line. i_stream_set_return_partial_line() specifies
1baa595093f5 Added i_stream_set_return_partial_line().
Timo Sirainen <tss@iki.fi>
parents: 7978
diff changeset
171 if the last line should be returned if it doesn't end with LF. */
903
fd8888f6f037 Naming style changes, finally got tired of most of the typedefs. Also the
Timo Sirainen <tss@iki.fi>
parents: 898
diff changeset
172 char *i_stream_next_line(struct istream *stream);
1293
2f2c6335ed6d Added i_stream_read_next_line()
Timo Sirainen <tss@iki.fi>
parents: 1197
diff changeset
173 /* Like i_stream_next_line(), but reads for more data if needed. Returns NULL
15640
20a545f932e3 i_stream_read_next_line() now sets stream_errno=ENOBUFS if input buffer gets full.
Timo Sirainen <tss@iki.fi>
parents: 15174
diff changeset
174 if more data is needed or error occurred. If the input buffer gets full,
20a545f932e3 i_stream_read_next_line() now sets stream_errno=ENOBUFS if input buffer gets full.
Timo Sirainen <tss@iki.fi>
parents: 15174
diff changeset
175 stream_errno is set to ENOBUFS. */
1293
2f2c6335ed6d Added i_stream_read_next_line()
Timo Sirainen <tss@iki.fi>
parents: 1197
diff changeset
176 char *i_stream_read_next_line(struct istream *stream);
14875
2e88cfd8b595 Added i_stream_last_line_crlf()
Timo Sirainen <tss@iki.fi>
parents: 14683
diff changeset
177 /* Returns TRUE if the last line read with i_stream_next_line() ended with
2e88cfd8b595 Added i_stream_last_line_crlf()
Timo Sirainen <tss@iki.fi>
parents: 14683
diff changeset
178 CRLF (instead of LF). */
2e88cfd8b595 Added i_stream_last_line_crlf()
Timo Sirainen <tss@iki.fi>
parents: 14683
diff changeset
179 bool i_stream_last_line_crlf(struct istream *stream);
2788
f322b24da429 Added i_stream_have_bytes_left().
Timo Sirainen <tss@iki.fi>
parents: 2626
diff changeset
180
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
181 /* Returns pointer to beginning of read data, or NULL if there's no data
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
182 buffered. */
17511
0d072ade062d lib: i_stream_get_data() should also reset eof=FALSE if it truncates the output.
Timo Sirainen <tss@iki.fi>
parents: 17479
diff changeset
183 const unsigned char *i_stream_get_data(struct istream *stream, size_t *size_r);
0d072ade062d lib: i_stream_get_data() should also reset eof=FALSE if it truncates the output.
Timo Sirainen <tss@iki.fi>
parents: 17479
diff changeset
184 size_t i_stream_get_data_size(struct istream *stream);
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
185 /* Like i_stream_get_data(), but returns non-const data. This only works with
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
186 buffered streams (currently only file), others return NULL. */
17511
0d072ade062d lib: i_stream_get_data() should also reset eof=FALSE if it truncates the output.
Timo Sirainen <tss@iki.fi>
parents: 17479
diff changeset
187 unsigned char *i_stream_get_modifiable_data(struct istream *stream,
5106
81394e71f92a Added istream->blocking setting. It's now used to assert-crash early if a
Timo Sirainen <tss@iki.fi>
parents: 4451
diff changeset
188 size_t *size_r);
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
189 /* Like i_stream_get_data(), but read more when needed. Returns 1 if more
7978
6f47263b947b i_stream_read_data() comment update.
Timo Sirainen <tss@iki.fi>
parents: 7925
diff changeset
190 than threshold bytes are available, 0 if as much or less, -1 if error or
6f47263b947b i_stream_read_data() comment update.
Timo Sirainen <tss@iki.fi>
parents: 7925
diff changeset
191 EOF with no bytes read that weren't already in buffer, or -2 if stream's
6f47263b947b i_stream_read_data() comment update.
Timo Sirainen <tss@iki.fi>
parents: 7925
diff changeset
192 input buffer is full. */
5106
81394e71f92a Added istream->blocking setting. It's now used to assert-crash early if a
Timo Sirainen <tss@iki.fi>
parents: 4451
diff changeset
193 int i_stream_read_data(struct istream *stream, const unsigned char **data_r,
81394e71f92a Added istream->blocking setting. It's now used to assert-crash early if a
Timo Sirainen <tss@iki.fi>
parents: 4451
diff changeset
194 size_t *size_r, size_t threshold);
20179
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
195 /* Like i_stream_get_data(), but read more when needed. Returns 1 if at least
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
196 the wanted number of bytes are available, 0 if less, -1 if error or
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
197 EOF with no bytes read that weren't already in buffer, or -2 if stream's
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
198 input buffer is full. */
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
199 static inline int
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
200 i_stream_read_bytes(struct istream *stream, const unsigned char **data_r,
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
201 size_t *size_r, size_t wanted)
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
202 {
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
203 i_assert(wanted > 0);
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
204 return i_stream_read_data(stream, data_r, size_r, wanted - 1);
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
205 }
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
206 /* Short-hand for just requesting more data (i.e. even one byte) */
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
207 static inline int
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
208 i_stream_read_more(struct istream *stream, const unsigned char **data_r,
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
209 size_t *size_r)
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
210 {
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
211 return i_stream_read_bytes(stream, data_r, size_r, 1);
f5a86453b6ac lib: istream - provide alternatives to i_stream_read_data()
Phil Carmody <phil@dovecot.fi>
parents: 20145
diff changeset
212 }
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
213
7925
4a166ccec256 Added i_stream_add_data().
Timo Sirainen <tss@iki.fi>
parents: 7912
diff changeset
214 /* Append external data to input stream. Returns TRUE if successful, FALSE if
4a166ccec256 Added i_stream_add_data().
Timo Sirainen <tss@iki.fi>
parents: 7912
diff changeset
215 there is not enough space in the stream. */
4a166ccec256 Added i_stream_add_data().
Timo Sirainen <tss@iki.fi>
parents: 7912
diff changeset
216 bool i_stream_add_data(struct istream *stream, const unsigned char *data,
4a166ccec256 Added i_stream_add_data().
Timo Sirainen <tss@iki.fi>
parents: 7912
diff changeset
217 size_t size);
4a166ccec256 Added i_stream_add_data().
Timo Sirainen <tss@iki.fi>
parents: 7912
diff changeset
218
17188
fd186eff7325 Added io_add_istream() and related functionality for combining the ioloop/istream.
Timo Sirainen <tss@iki.fi>
parents: 16813
diff changeset
219 void i_stream_set_input_pending(struct istream *stream, bool pending);
fd186eff7325 Added io_add_istream() and related functionality for combining the ioloop/istream.
Timo Sirainen <tss@iki.fi>
parents: 16813
diff changeset
220
fd186eff7325 Added io_add_istream() and related functionality for combining the ioloop/istream.
Timo Sirainen <tss@iki.fi>
parents: 16813
diff changeset
221 /* If there are any I/O loop items associated with the stream, move all of
fd186eff7325 Added io_add_istream() and related functionality for combining the ioloop/istream.
Timo Sirainen <tss@iki.fi>
parents: 16813
diff changeset
222 them to current_ioloop. */
fd186eff7325 Added io_add_istream() and related functionality for combining the ioloop/istream.
Timo Sirainen <tss@iki.fi>
parents: 16813
diff changeset
223 void i_stream_switch_ioloop(struct istream *stream);
fd186eff7325 Added io_add_istream() and related functionality for combining the ioloop/istream.
Timo Sirainen <tss@iki.fi>
parents: 16813
diff changeset
224
764
f57c52738f90 Renamed IBuffer and OBuffer to IStream and OStream which describes their
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
225 #endif