1 /* Generic stream implementation -- header file.
2 Copyright (C) 1995 Free Software Foundation, Inc.
3 Copyright (C) 1996 Ben Wing.
4 Copyright (C) 2006-2008 Sebastian Freundt
6 This file is part of SXEmacs
8 SXEmacs is free software: you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation, either version 3 of the License, or
11 (at your option) any later version.
13 SXEmacs is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
18 You should have received a copy of the GNU General Public License
19 along with this program. If not, see <http://www.gnu.org/licenses/>. */
22 /* Synched up with: Not in FSF. */
24 /* Written by Ben Wing. */
26 #ifndef INCLUDED_lstream_h_
27 #define INCLUDED_lstream_h_
30 * \defgroup lstream Lstream
33 * \brief Dealing with I/O streams
38 /************************************************************************/
39 /* definition of Lstream object */
40 /************************************************************************/
42 DECLARE_LRECORD(lstream, struct lstream_s);
43 #define XLSTREAM(x) XRECORD (x, lstream, struct lstream_s)
44 #define XSETLSTREAM(x, p) XSETRECORD (x, p, lstream)
45 #define LSTREAMP(x) RECORDP (x, lstream)
51 /* Typedef specifying a count of bytes in a data block to be written
52 out or read in, using Lstream_read(), Lstream_write(), and related
53 functions. This MUST BE SIGNED, since it also is used in functions
54 that return the number of bytes actually read to or written from in
55 an operation, and these functions can return -1 to signal error.
57 Note that the standard Unix read() and write() functions define the
58 count going in as a size_t, which is UNSIGNED, and the count going
59 out as an ssize_t, which is SIGNED. This is a horrible design
60 flaw. Not only is it highly likely to lead to logic errors when a
61 -1 gets interpreted as a large positive number, but operations are
62 bound to fail in all sorts of horrible ways when a number in the
63 upper-half of the size_t range is passed in -- this number is
64 unrepresentable as an ssize_t, so code that checks to see how many
65 bytes are actually written (which is mandatory if you are dealing
66 with certain types of devices) will get completely screwed up.
69 typedef EMACS_INT Lstream_data_count;
71 typedef enum lstream_buffering {
74 /* Buffer until a '\n' character is reached. */
75 LSTREAM_LINE_BUFFERED,
76 /* Buffer in standard-size (i.e. 512-byte) blocks. */
77 LSTREAM_BLOCK_BUFFERED,
78 /* Buffer in blocks of a specified size. */
79 LSTREAM_BLOCKN_BUFFERED,
80 /* Buffer until the stream is closed (only applies to write-only
81 streams). Only one call to the stream writer will be made,
82 and that is when the stream is closed. */
86 /* Methods defining how this stream works. Some may be undefined. */
88 /* We do not implement the seek/tell paradigm. I tried to do that,
89 but getting the semantics right in the presence of buffering is
90 extremely tricky and very error-prone and basically not worth it.
91 This is especially the case with complicated streams like
92 decoding streams -- the seek pointer in this case can't be a single
93 integer but has to be a whole complicated structure that records
94 all of the stream's state at the time.
96 Rewind semantics are generally easy to implement, so we do provide
97 a rewind method. Even rewind() may not be available on a stream,
98 however -- e.g. on process output. */
100 typedef struct lstream_implementation {
102 Lstream_data_count size; /* Number of additional bytes to be
103 allocated with this stream. Access this
104 data using Lstream_data(). */
105 /* Read some data from the stream's end and store it into DATA, which
106 can hold SIZE bytes. Return the number of bytes read. A return
107 value of 0 means no bytes can be read at this time. This may
108 be because of an EOF, or because there is a granularity greater
109 than one byte that the stream imposes on the returned data, and
110 SIZE is less than this granularity. (This will happen frequently
111 for streams that need to return whole characters, because
112 Lstream_read() calls the reader function repeatedly until it
113 has the number of bytes it wants or until 0 is returned.)
114 The lstream functions do not treat a 0 return as EOF or do
115 anything special; however, the calling function will interpret
116 any 0 it gets back as EOF. This will normally not happen unless
117 the caller calls Lstream_read() with a very small size.
119 This function can be NULL if the stream is output-only. */
120 /* The omniscient mly, blinded by the irresistible thrall of Common
121 Lisp, thinks that it is bogus that the types and implementations
122 of input and output streams are the same. */
123 Lstream_data_count(*reader) (Lstream * stream, unsigned char *data,
124 Lstream_data_count size);
125 /* Send some data to the stream's end. Data to be sent is in DATA
126 and is SIZE bytes. Return the number of bytes sent. This
127 function can send and return fewer bytes than is passed in; in
128 that case, the function will just be called again until there is
129 no data left or 0 is returned. A return value of 0 means that no
130 more data can be currently stored, but there is no error; the
131 data will be squirrelled away until the writer can accept
132 data. (This is useful, e.g., of you're dealing with a
133 non-blocking file descriptor and are getting EWOULDBLOCK errors.)
134 This function can be NULL if the stream is input-only. */
135 Lstream_data_count(*writer) (Lstream * stream,
136 const unsigned char *data,
137 Lstream_data_count size);
138 /* Return non-zero if the last write operation on the stream resulted
139 in an attempt to block (EWOULDBLOCK). If this method does not
140 exists, the implementation returns 0 */
141 int (*was_blocked_p) (Lstream * stream);
142 /* Rewind the stream. If this is NULL, the stream is not seekable. */
143 int (*rewinder) (Lstream * stream);
144 /* Indicate whether this stream is seekable -- i.e. it can be rewound.
145 This method is ignored if the stream does not have a rewind
146 method. If this method is not present, the result is determined
147 by whether a rewind method is present. */
148 int (*seekable_p) (Lstream * stream);
149 /* Perform any additional operations necessary to flush the
150 data in this stream. */
151 int (*flusher) (Lstream * stream);
152 /* Perform any additional operations necessary to close this
153 stream down. May be NULL. This function is called when
154 Lstream_close() is called or when the stream is garbage-
155 collected. When this function is called, all pending data
156 in the stream will already have been written out. */
157 int (*closer) (Lstream * stream);
158 /* Return the underlying file descriptor if applicable, -1 otherwise */
159 int (*get_fd)(Lstream * stream);
161 /* Mark this object for garbage collection. Same semantics as
162 a standard Lisp_Object marker. This function can be NULL. */
163 Lisp_Object(*marker) (Lisp_Object lstream);
164 } Lstream_implementation;
166 #define DEFINE_LSTREAM_IMPLEMENTATION(name,c_name,size) \
167 Lstream_implementation c_name[1] = \
168 { { (name), (size) } }
170 #define LSTREAM_FL_IS_OPEN 1
171 #define LSTREAM_FL_READ 2
172 #define LSTREAM_FL_WRITE 4
173 #define LSTREAM_FL_NO_PARTIAL_CHARS 8
174 #define LSTREAM_FL_CLOSE_AT_DISKSAVE 16
177 * The lstream structure. */
179 struct lcrecord_header header;
180 const Lstream_implementation *imp; /* methods for this stream */
181 Lstream_buffering buffering; /* type of buffering in use */
182 Lstream_data_count buffering_size; /* number of bytes buffered */
184 unsigned char *in_buffer; /* holds characters read from stream end */
185 Lstream_data_count in_buffer_size; /* allocated size of buffer */
186 Lstream_data_count in_buffer_current; /* number of characters in buffer */
187 Lstream_data_count in_buffer_ind; /* pointer to next character to
190 unsigned char *out_buffer; /* holds characters to write to stream end */
191 Lstream_data_count out_buffer_size; /* allocated size of buffer */
192 Lstream_data_count out_buffer_ind; /* pointer to next buffer spot to
195 /* The unget buffer is more or less a stack -- things get pushed
196 onto the end and read back from the end. Lstream_read()
197 basically reads backwards from the end to get stuff; Lstream_unread()
198 similarly has to push the data on backwards. */
199 unsigned char *unget_buffer; /* holds characters pushed back onto input */
200 Lstream_data_count unget_buffer_size; /* allocated size of buffer */
201 Lstream_data_count unget_buffer_ind; /* pointer to next buffer spot
202 to write a character */
204 Lstream_data_count byte_count;
209 #define LSTREAM_TYPE_P(lstr, type) \
210 ((lstr)->imp == lstream_##type)
212 #ifdef ERROR_CHECK_TYPECHECK
213 static inline lstream_t
214 error_check_lstream_type(lstream_t stream, const Lstream_implementation *imp)
215 __attribute__((always_inline));
216 static inline lstream_t
217 error_check_lstream_type(lstream_t stream, const Lstream_implementation *imp)
219 assert(stream->imp == imp);
223 # define LSTREAM_TYPE_DATA(lstr, type) \
225 Lstream_data(error_check_lstream_type(lstr, lstream_##type)))
227 #else /* !ERROR_CHECK_TYPECHECK */
229 # define LSTREAM_TYPE_DATA(lstr, type) \
230 ((type##_stream_t)Lstream_data(lstr))
232 #endif /* ERROR_CHECK_TYPECHECK */
234 /* Declare that lstream-type TYPE has method M; used in
235 initialization routines */
236 #define LSTREAM_HAS_METHOD(type, m) \
237 (lstream_##type->m = type##_##m)
239 lstream_t Lstream_new(const Lstream_implementation *imp, const char *mode);
240 void Lstream_reopen(lstream_t lstr);
241 void Lstream_set_buffering(lstream_t lstr, Lstream_buffering buffering,
243 int Lstream_flush(lstream_t lstr);
244 int Lstream_flush_out(lstream_t lstr);
245 int Lstream_fputc(lstream_t lstr, int c);
246 int Lstream_fgetc(lstream_t lstr);
247 void Lstream_fungetc(lstream_t lstr, int c);
249 Lstream_read(lstream_t lstr, void *data, Lstream_data_count size);
251 Lstream_write(lstream_t lstr, const void *data, Lstream_data_count size);
252 int Lstream_was_blocked_p(lstream_t lstr);
253 void Lstream_unread(lstream_t lstr, const void *data, Lstream_data_count size);
254 int Lstream_rewind(lstream_t lstr);
255 int Lstream_seekable_p(lstream_t lstr);
256 int Lstream_close(lstream_t lstr);
257 void Lstream_delete(lstream_t lstr);
258 void Lstream_set_character_mode(lstream_t str);
259 int Lstream_get_fd(lstream_t lstr);
262 Lstream_putc(lstream_t stream, int c)
263 __attribute__((always_inline));
265 Lstream_getc(lstream_t stream)
266 __attribute__((always_inline));
268 Lstream_ungetc(lstream_t stream, int c)
269 __attribute__((always_inline));
272 #define Lstream_data(stream) ((void*)((stream)->data))
273 #define Lstream_byte_count(stream) ((stream)->byte_count)
276 /************************************************************************/
277 /* working with an Lstream as a stream of Emchars */
278 /************************************************************************/
283 #include "mule/mule-charset.h"
286 extern_inline Emchar Lstream_get_emchar(lstream_t stream);
287 extern_inline Emchar Lstream_get_emchar(lstream_t stream)
289 int c = Lstream_getc(stream);
290 return (c < 0x80 /* c == EOF || BYTE_ASCII_P (c) */
292 : Lstream_get_emchar_1(stream, c));
295 extern_inline int Lstream_put_emchar(lstream_t stream, Emchar ch);
296 extern_inline int Lstream_put_emchar(lstream_t stream, Emchar ch)
298 return CHAR_ASCII_P(ch)
299 ? Lstream_putc(stream, ch)
300 : Lstream_fput_emchar(stream, ch);
303 extern_inline void Lstream_unget_emchar(lstream_t stream, Emchar ch);
304 extern_inline void Lstream_unget_emchar(lstream_t stream, Emchar ch)
306 if (CHAR_ASCII_P(ch)) {
307 Lstream_ungetc(stream, ch);
309 Lstream_funget_emchar(stream, ch);
315 # define Lstream_get_emchar Lstream_getc
316 # define Lstream_put_emchar Lstream_putc
317 # define Lstream_unget_emchar Lstream_ungetc
319 #endif /* not MULE */
322 /************************************************************************/
323 /* Lstream implementations */
324 /************************************************************************/
326 /* Flags we can pass to the filedesc and stdio streams. */
328 /* If set, close the descriptor or FILE * when the stream is closed. */
329 #define LSTR_CLOSING 1
331 /* If set, allow quitting out of the actual I/O. */
332 #define LSTR_ALLOW_QUIT 2
334 /* If set and filedesc_stream_set_pty_flushing() has been called
335 on the stream, do not send more than pty_max_bytes on a single
336 line without flushing the data out using the eof_char. */
337 #define LSTR_PTY_FLUSHING 4
339 /* If set, an EWOULDBLOCK error is not treated as an error but
340 simply causes the write function to return 0 as the number
341 of bytes written out. */
342 #define LSTR_BLOCKED_OK 8
344 Lisp_Object make_stdio_input_stream(FILE * stream, int flags);
345 Lisp_Object make_stdio_output_stream(FILE * stream, int flags);
346 Lisp_Object make_filedesc_input_stream(int filedesc, int offset, int count,
348 Lisp_Object make_filedesc_output_stream(int filedesc, int offset, int count,
350 void filedesc_stream_set_pty_flushing(lstream_t stream,
351 int pty_max_bytes, Bufbyte eof_char);
352 Lisp_Object make_lisp_string_input_stream(Lisp_Object string,
353 Bytecount offset, Bytecount len);
354 Lisp_Object make_fixed_buffer_input_stream(const void *buf,
355 Lstream_data_count size);
356 Lisp_Object make_fixed_buffer_output_stream(void *buf, Lstream_data_count size);
357 const unsigned char *fixed_buffer_input_stream_ptr(lstream_t stream);
358 unsigned char *fixed_buffer_output_stream_ptr(lstream_t stream);
359 Lisp_Object make_resizing_buffer_output_stream(void);
360 unsigned char *resizing_buffer_stream_ptr(lstream_t stream);
361 Lisp_Object make_dynarr_output_stream(unsigned_char_dynarr * dyn);
362 #define LSTR_SELECTIVE 1
363 #define LSTR_IGNORE_ACCESSIBLE 2
364 Lisp_Object make_lisp_buffer_input_stream(struct buffer *buf, Bufpos start,
365 Bufpos end, int flags);
366 Lisp_Object make_lisp_buffer_output_stream(struct buffer *buf, Bufpos pos,
368 Bufpos lisp_buffer_stream_startpos(lstream_t stream);
373 * Call the function equivalent if the out buffer is full.
374 * Otherwise, add to the end of the out buffer and, if line buffering is called
375 * for and the character marks the end of a line, write out the buffer. */
377 Lstream_putc(lstream_t stream, int c)
379 if (LIKELY(stream->out_buffer_ind >= stream->out_buffer_size)) {
380 return Lstream_fputc(stream, c);
383 stream->out_buffer[stream->out_buffer_ind++] = (unsigned char)c;
384 stream->byte_count++;
385 if (stream->buffering == LSTREAM_LINE_BUFFERED &&
386 stream->out_buffer[stream->out_buffer_ind - 1] == '\n') {
387 return Lstream_flush_out(stream);
393 * Retrieve from unget buffer if there are any characters there;
394 * else retrieve from in buffer if there's anything there;
395 * else call the function equivalent */
397 Lstream_getc(lstream_t stream)
399 if (LIKELY(stream->unget_buffer_ind > 0)) {
400 stream->byte_count++;
401 return stream->unget_buffer[--stream->unget_buffer_ind];
402 } else if (stream->in_buffer_ind < stream->in_buffer_current) {
403 stream->byte_count++;
404 return stream->in_buffer[stream->in_buffer_ind++];
406 return Lstream_fgetc(stream);
411 * Add to the end if it won't overflow buffer; otherwise call the
412 * function equivalent */
414 Lstream_ungetc(lstream_t stream, int c)
416 if (LIKELY(stream->unget_buffer_ind >= stream->unget_buffer_size)) {
417 Lstream_fungetc(stream, c);
421 stream->byte_count--;
422 stream->unget_buffer[stream->unget_buffer_ind++] = (unsigned char)(c);
429 #endif /* INCLUDED_lstream_h_ */