Extended I/O (fseek and line read/write)

Extended I/O procedures are available which read or write lines of text, read text delimited by a specified set of characters, or report or set the current position of a port.

Interfaces to read/fread and write/fwrite are also available, as uniform-array-read! and uniform-array-write!, section Uniform Array.

procedure: read-line [port] [handle-delim]

Return a line of text from port if specified, otherwise from the value returned by (current-input-port). Under Unix, a line of text is terminated by the first end-of-line character or by end-of-file.

If handle-delim is specified, it should be one of the following symbols:

trim

Discard the terminating delimiter. This is the default, but it will be impossible to tell whether the read terminated with a delimiter or end-of-file.

concat

Append the terminating delimiter (if any) to the returned string.

peek

Push the terminating delimiter (if any) back on to the port.

split

Return a pair containing the string read from the port and the terminating delimiter or end-of-file object. NOTE: if the scsh module is loaded then multiple values are returned instead of a pair.

procedure: read-line! buf [port]

Read a line of text into the supplied string buf and return the number of characters added to buf. If buf is filled, then #f is returned. Read from port if specified, otherwise from the value returned by (current-input-port).

procedure: read-delimited delims [port] [handle-delim]

Read text until one of the characters in the string delims is found or end-of-file is reached. Read from port if supplied, otherwise from the value returned by (current-input-port). handle-delim takes the same values as described for read-line.

NOTE: if the scsh module is loaded then delims must be an scsh char-set, not a string.

procedure: read-delimited! delims buf [port] [handle-delim] [start] [end]

Read text into the supplied string buf and return the number of characters added to buf (subject to handle-delim, which takes the same values specified for read-line. If buf is filled, #f is returned for both the number of characters read and the delimiter. Also terminates if one of the characters in the string delims is found or end-of-file is reached. Read from port if supplied, otherwise from the value returned by (current-input-port).

NOTE: if the scsh module is loaded then delims must be an scsh char-set, not a string.

primitive: write-line obj [port]

Display obj and a newline character to port. If port is not specified, (current-output-port) is used. This function is equivalent to:

(display obj [port])
(newline [port])

primitive: ftell fd/port

Returns an integer representing the current position of fd/port, measured from the beginning. If fd/port is a file descriptor, the underlying system call is lseek.

primitive: fseek fd/port offset whence

Sets the current position of fd/port to the integer offset, which is interpreted according to the value of whence.

One of the following variables should be supplied for whence:

Variable: SEEK_SET

Seek from the beginning of the file.

Variable: SEEK_CUR

Seek from the current position.

Variable: SEEK_END

Seek from the end of the file.

If fd/port is a file descriptor the underlying system call is lseek. The return value is unspecified.

Some of the abovementioned I/O functions rely on the following C primitives. These will mainly be of interest to people hacking Guile internals.

primitive: %read-delimited! delims buf gobble? [port [start [end]]]

Read characters from port into buf until one of the characters in the delims string is encountered. If gobble? is true, store the delimiter character in buf as well; otherwise, discard it. If port is not specified, use the value of (current-input-port). If start or end are specified, store data only into the substring of buf bounded by start and end (which default to the beginning and end of the buffer, respectively).

Return a pair consisting of the delimiter that terminated the string and the number of characters read. If reading stopped at the end of file, the delimiter returned is the eof-object; if the buffer was filled without encountering a delimiter, this value is #f.

primitive: %read-line [port]

Read a newline-terminated line from port, allocating storage as necessary. The newline terminator (if any) is removed from the string, and a pair consisting of the line and its delimiter is returned. The delimiter may be either a newline or the eof-object; if %read-line is called at the end of file, it returns the pair (#<eof> . #<eof>).

Go to the first, previous, next, last section, table of contents.