1 #ifndef ISTREAM_H
2 #define ISTREAM_H
3
4 /* Note that some systems (Solaris) may use a macro to redefine struct stat */
5 #include <sys/stat.h>
6
7 struct ioloop;
8
9 struct istream {
10 uoff_t v_offset;
11
12 /* Commonly used errors:
13
14 ENOENT - File/object doesn't exist.
15 EPIPE - Stream ended unexpectedly (or i_stream_close() was called).
16 ESPIPE - i_stream_seek() was used on a stream that can't be seeked.
17 ENOBUFS - i_stream_read_next_line() was used for a too long line.
18 EIO - Internal error. Retrying may work, but it may also be
19 because of a misconfiguration.
20 EINVAL - Stream is corrupted.
21
22 If stream_errno != 0, eof==TRUE as well.
23 */
24 int stream_errno;
25
26 bool mmaped:1; /* be careful when copying data */
27 bool blocking:1; /* read() shouldn't return 0 */
28 bool closed:1;
29 bool readable_fd:1; /* fd can be read directly if necessary
30 (for sendfile()) */
31 bool seekable:1; /* we can seek() backwards */
32 /* read() has reached to end of file (but there may still be data
33 available in buffer) or stream_errno != 0 */
34 bool eof:1;
35
36 struct istream_private *real_stream;
37 };
38
39 typedef void istream_callback_t(void *context);
40
41 struct istream *i_stream_create_fd(int fd, size_t max_buffer_size);
42 /* The fd is set to -1 immediately to avoid accidentally closing it twice. */
43 struct istream *i_stream_create_fd_autoclose(int *fd, size_t max_buffer_size);
44 /* Open the given path only when something is actually tried to be read from
45 the stream. */
46 struct istream *i_stream_create_file(const char *path, size_t max_buffer_size);
47 /* Create an input stream using the provided data block. That data block must
48 remain allocated during the full lifetime of the stream. */
49 struct istream *i_stream_create_from_data(const void *data, size_t size);
50 #define i_stream_create_from_buffer(buf) \
51 i_stream_create_from_data((buf)->data, (buf)->used)
52 #define i_stream_create_from_string(str) \
53 i_stream_create_from_data(str_data(str), str_len(str))
54 /* Create an input stream using a copy of the provided data block. The
55 provided data block may be freed at any time. The copy is freed when the
56 stream is destroyed. */
57 struct istream *
58 i_stream_create_copy_from_data(const void *data, size_t size);
59 #define i_stream_create_copy_from_buffer(buf) \
60 i_stream_create_copy_from_data((buf)->data, (buf)->used)
61 #define i_stream_create_copy_from_string(str) \
62 i_stream_create_copy_from_data(str_data(str), str_len(str))
63 struct istream *i_stream_create_limit(struct istream *input, uoff_t v_size);
64 struct istream *i_stream_create_range(struct istream *input,
65 uoff_t v_offset, uoff_t v_size);
66 struct istream *i_stream_create_error(int stream_errno);
67 struct istream *
68 i_stream_create_error_str(int stream_errno, const char *fmt, ...)
69 ATTR_FORMAT(2, 3);
70
71 /* Set name (e.g. path) for input stream. */
72 void i_stream_set_name(struct istream *stream, const char *name);
73 /* Get input stream's name. If stream itself doesn't have a name,
74 it looks up further into stream's parents until one of them has a name.
75 Returns "" if stream has no name. */
76 const char *i_stream_get_name(struct istream *stream);
77
78 /* Close this stream (but not its parents) and unreference it. */
79 void i_stream_destroy(struct istream **stream);
80
81 /* Reference counting. References start from 1, so calling i_stream_unref()
82 destroys the stream if i_stream_ref() is never used. */
83 void i_stream_ref(struct istream *stream);
84 /* Unreferences the stream and sets stream pointer to NULL. */
85 void i_stream_unref(struct istream **stream);
86 /* Call the given callback function when stream is destroyed. */
87 void i_stream_add_destroy_callback(struct istream *stream,
88 istream_callback_t *callback, void *context)
89 ATTR_NULL(3);
90 #define i_stream_add_destroy_callback(stream, callback, context) \
91 i_stream_add_destroy_callback(stream - \
92 CALLBACK_TYPECHECK(callback, void (*)(typeof(context))), \
93 (istream_callback_t *)callback, context)
94 /* Remove the destroy callback. */
95 void i_stream_remove_destroy_callback(struct istream *stream,
96 void (*callback)());
97
98 /* Return file descriptor for stream, or -1 if none is available. */
99 int i_stream_get_fd(struct istream *stream);
100 /* Copy the file descriptor from source istream to destination istream.
101 The readable_fd is preserved. Assert-crashes if source doesn't have a
102 file descriptor. */
103 void i_stream_copy_fd(struct istream *dest, struct istream *source);
104 /* Returns error string for the last error. It also returns "EOF" in case there
105 is no error, but eof is set. Otherwise it returns "<no error>". */
106 const char *i_stream_get_error(struct istream *stream);
107 /* Returns human-readable reason for why istream was disconnected.
108 The output is either "Connection closed" for clean disconnections or
109 "Connection closed: <error>" for unclean disconnections. This is an
110 alternative to i_stream_get_error(), which is preferred to be used when
111 logging errors about client connections. */
112 const char *i_stream_get_disconnect_reason(struct istream *stream);
113
114 /* Mark the stream and all of its parent streams closed. Any reads after this
115 will return -1. The data already read can still be used. */
116 void i_stream_close(struct istream *stream);
117 /* Sync the stream with the underlying backend, ie. if a file has been
118 modified, flush any cached data. */
119 void i_stream_sync(struct istream *stream);
120
121 /* Change the initial size for stream's input buffer. This basically just
122 grows the read buffer size from the default. This function has no effect
123 unless it's called before reading anything. */
124 void i_stream_set_init_buffer_size(struct istream *stream, size_t size);
125 /* Change the maximum size for stream's input buffer to grow. Useful only
126 for buffered streams (currently only file). This changes also all the
127 parent streams' max buffer size. */
128 void i_stream_set_max_buffer_size(struct istream *stream, size_t max_size);
129 /* Returns the current max. buffer size for the stream. This function also
130 goes through all of the parent streams and returns the highest seen max
131 buffer size. This is needed because some streams (e.g. istream-chain) change
132 their max buffer size dynamically. */
133 size_t i_stream_get_max_buffer_size(struct istream *stream);
134 /* Enable/disable i_stream[_read]_next_line() returning the last line if it
135 doesn't end with LF. */
136 void i_stream_set_return_partial_line(struct istream *stream, bool set);
137 /* Change whether buffers are allocated persistently (default=TRUE). When not,
138 the memory usage is minimized by freeing the stream's buffers whenever they
139 become empty. */
140 void i_stream_set_persistent_buffers(struct istream *stream, bool set);
141 /* Set the istream blocking or nonblocking, including its parent streams.
142 If any of the istreams have an fd, its O_NONBLOCK flag is changed. */
143 void i_stream_set_blocking(struct istream *stream, bool blocking);
144
145 /* Returns number of bytes read if read was ok, 0 if stream is non-blocking and
146 no more data is available, -1 if EOF or error, -2 if the input buffer is
147 full. If <=0 is returned, pointers to existing data returned by the previous
148 i_stream_get_data() will stay valid, although calling it again may return
149 a different pointer. The pointers to old data are invalidated again when
150 return value is >0. */
151 ssize_t i_stream_read(struct istream *stream);
152 /* Skip forward a number of bytes. Never fails, the next read tells if it
153 was successful. */
154 void i_stream_skip(struct istream *stream, uoff_t count);
155 /* Seek to specified position from beginning of file. Never fails, the next
156 read tells if it was successful. This works only for files, others will
157 set stream_errno=ESPIPE. */
158 void i_stream_seek(struct istream *stream, uoff_t v_offset);
159 /* Like i_stream_seek(), but also giving a hint that after reading some data
160 we could be seeking back to this mark or somewhere after it. If input
161 stream's implementation is slow in seeking backwards, it can use this hint
162 to cache some of the data in memory. */
163 void i_stream_seek_mark(struct istream *stream, uoff_t v_offset);
164 /* Returns 0 if ok, -1 if error. As the underlying stream may not be
165 a file, only some of the fields might be set, others would be zero.
166 st_size is always set, and if it's not known, it's -1.
167
168 If exact=FALSE, the stream may not return exactly correct values, but the
169 returned values can be compared to see if anything had changed (eg. in
170 compressed stream st_size could be compressed size) */
171 int i_stream_stat(struct istream *stream, bool exact, const struct stat **st_r);
172 /* Similar to i_stream_stat() call. Returns 1 if size was successfully
173 set, 0 if size is unknown, -1 if error. */
174 int i_stream_get_size(struct istream *stream, bool exact, uoff_t *size_r);
175 /* Returns TRUE if there are any bytes left to be read or in buffer. */
176 bool i_stream_have_bytes_left(struct istream *stream);
177 /* Returns TRUE if there are no bytes currently buffered and i_stream_read()
178 returns EOF/error. Usually it's enough to check for stream->eof instead of
179 calling this function. Note that if the stream isn't at EOF, this function
180 has now read data into the stream buffer. */
181 bool i_stream_read_eof(struct istream *stream);
182 /* Returns the absolute offset of the stream. This is the stream's current
183 v_offset + the parent's absolute offset when the stream was created. */
184 uoff_t i_stream_get_absolute_offset(struct istream *stream);
185
186 /* Gets the next line from stream and returns it, or NULL if more data is
187 needed to make a full line. i_stream_set_return_partial_line() specifies
188 if the last line should be returned if it doesn't end with LF. */
189 char *i_stream_next_line(struct istream *stream);
190 /* Like i_stream_next_line(), but reads for more data if needed. Returns NULL
191 if more data is needed or error occurred. If the input buffer gets full,
192 stream_errno is set to ENOBUFS. */
193 char *i_stream_read_next_line(struct istream *stream);
194 /* Returns TRUE if the last line read with i_stream_next_line() ended with
195 CRLF (instead of LF). */
196 bool i_stream_last_line_crlf(struct istream *stream);
197
198 /* Returns pointer to beginning of read data. */
199 const unsigned char *i_stream_get_data(struct istream *stream, size_t *size_r);
200 size_t i_stream_get_data_size(struct istream *stream);
201 /* Like i_stream_get_data(), but returns non-const data. This only works with
202 buffered streams (currently only file), others return NULL. */
203 unsigned char *i_stream_get_modifiable_data(struct istream *stream,
204 size_t *size_r);
205 /* Like i_stream_get_data(), but read more when needed. Returns 1 if more
206 than threshold bytes are available, 0 if as much or less, -1 if error or
207 EOF with no bytes read that weren't already in buffer, or -2 if stream's
208 input buffer is full. */
209 int i_stream_read_data(struct istream *stream, const unsigned char **data_r,
210 size_t *size_r, size_t threshold);
211 /* Like i_stream_get_data(), but read more when needed. Returns 1 if at least
212 the wanted number of bytes are available, 0 if less, -1 if error or
213 EOF with no bytes read that weren't already in buffer, or -2 if stream's
214 input buffer is full. */
215 static inline int
i_stream_read_bytes(struct istream * stream,const unsigned char ** data_r,size_t * size_r,size_t wanted)216 i_stream_read_bytes(struct istream *stream, const unsigned char **data_r,
217 size_t *size_r, size_t wanted)
218 {
219 i_assert(wanted > 0);
220 return i_stream_read_data(stream, data_r, size_r, wanted - 1);
221 }
222 /* Short-hand for just requesting more data (i.e. even one byte) */
223 static inline int
i_stream_read_more(struct istream * stream,const unsigned char ** data_r,size_t * size_r)224 i_stream_read_more(struct istream *stream, const unsigned char **data_r,
225 size_t *size_r)
226 {
227 int ret = i_stream_read_bytes(stream, data_r, size_r, 1);
228 i_assert(ret != -2); /* stream must have space for at least 1 byte */
229 return ret;
230 }
231 /* Return the timestamp when istream last successfully read something.
232 The timestamp is 0 if nothing has ever been read. */
233 void i_stream_get_last_read_time(struct istream *stream, struct timeval *tv_r);
234
235 /* Append external data to input stream. Returns TRUE if successful, FALSE if
236 there is not enough space in the stream. */
237 bool i_stream_add_data(struct istream *stream, const unsigned char *data,
238 size_t size);
239
240 void i_stream_set_input_pending(struct istream *stream, bool pending);
241
242 /* If there are any I/O loop items associated with the stream, move all of
243 them to provided/current ioloop. */
244 void i_stream_switch_ioloop_to(struct istream *stream, struct ioloop *ioloop);
245 void i_stream_switch_ioloop(struct istream *stream);
246
247 #endif
248