20.4 Lstream Methods

Lstream Method: ssize_t reader (Lstream *stream, unsigned char *data, size_t size)

Read some data from the stream’s end and store it into data, which can hold size bytes. Return the number of bytes read. A return value of 0 means no bytes can be read at this time. This may be because of an EOF, or because there is a granularity greater than one byte that the stream imposes on the returned data, and size is less than this granularity. (This will happen frequently for streams that need to return whole characters, because Lstream_read() calls the reader function repeatedly until it has the number of bytes it wants or until 0 is returned.) The lstream functions do not treat a 0 return as EOF or do anything special; however, the calling function will interpret any 0 it gets back as EOF. This will normally not happen unless the caller calls Lstream_read() with a very small size.

This function can be NULL if the stream is output-only.

Lstream Method: ssize_t writer (Lstream *stream, const unsigned char *data, size_t size)

Send some data to the stream’s end. Data to be sent is in data and is size bytes. Return the number of bytes sent. This function can send and return fewer bytes than is passed in; in that case, the function will just be called again until there is no data left or 0 is returned. A return value of 0 means that no more data can be currently stored, but there is no error; the data will be squirreled away until the writer can accept data. (This is useful, e.g., if you’re dealing with a non-blocking file descriptor and are getting EWOULDBLOCK errors.) This function can be NULL if the stream is input-only.

Lstream Method: int rewinder (Lstream *stream)

Rewind the stream. If this is NULL, the stream is not seekable.

Lstream Method: int seekable_p (Lstream *stream)

Indicate whether this stream is seekable—i.e. it can be rewound. This method is ignored if the stream does not have a rewind method. If this method is not present, the result is determined by whether a rewind method is present.

Lstream Method: int flusher (Lstream *stream)

Perform any additional operations necessary to flush the data in this stream.

Lstream Method: int pseudo_closer (Lstream *stream)

Lstream Method: int closer (Lstream *stream)

Perform any additional operations necessary to close this stream down. May be NULL. This function is called when Lstream_close() is called or when the stream is garbage-collected. When this function is called, all pending data in the stream will already have been written out.

Lstream Method: Lisp_Object marker (Lisp_Object lstream, void (*markfun) (Lisp_Object))

Mark this object for garbage collection. Same semantics as a standard Lisp_Object marker. This function can be NULL.