6.14.7 Block reading and writing

The Block-string-I/O module can be accessed with:

(use-modules (ice-9 rw))

It currently contains procedures that help to implement the (scsh rw) module in guile-scsh.

Scheme Procedure: read-string!/partial str [port_or_fdes [start [end]]]

C Function: scm_read_string_x_partial (str, port_or_fdes, start, end)

Read characters from a port or file descriptor into a string str. A port must have an underlying file descriptor — a so-called fport. This procedure is scsh-compatible and can efficiently read large strings. It will:

• attempt to fill the entire string, unless the start and/or end arguments are supplied. i.e., start defaults to 0 and end defaults to (string-length str)
• use the current input port if port_or_fdes is not supplied.
• return fewer than the requested number of characters in some cases, e.g., on end of file, if interrupted by a signal, or if not all the characters are immediately available.
• wait indefinitely for some input if no characters are currently available, unless the port is in non-blocking mode.
• read characters from the port’s input buffers if available, instead from the underlying file descriptor.
• return #f if end-of-file is encountered before reading any characters, otherwise return the number of characters read.
• return 0 if the port is in non-blocking mode and no characters are immediately available.
• return 0 if the request is for 0 bytes, with no end-of-file check.

Scheme Procedure: write-string/partial str [port_or_fdes [start [end]]]

C Function: scm_write_string_partial (str, port_or_fdes, start, end)

Write characters from a string str to a port or file descriptor. A port must have an underlying file descriptor — a so-called fport. This procedure is scsh-compatible and can efficiently write large strings. It will:

• attempt to write the entire string, unless the start and/or end arguments are supplied. i.e., start defaults to 0 and end defaults to (string-length str)
• use the current output port if port_of_fdes is not supplied.
• in the case of a buffered port, store the characters in the port’s output buffer, if all will fit. If they will not fit then any existing buffered characters will be flushed before attempting to write the new characters directly to the underlying file descriptor. If the port is in non-blocking mode and buffered characters can not be flushed immediately, then an EAGAIN system-error exception will be raised (Note: scsh does not support the use of non-blocking buffered ports.)
• write fewer than the requested number of characters in some cases, e.g., if interrupted by a signal or if not all of the output can be accepted immediately.
• wait indefinitely for at least one character from str to be accepted by the port, unless the port is in non-blocking mode.
• return the number of characters accepted by the port.
• return 0 if the port is in non-blocking mode and can not accept at least one character from str immediately
• return 0 immediately if the request size is 0 bytes.

This document was generated on April 20, 2013 using texi2html 5.0.