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

Input and Output

Ports

[Concept of the port abstraction.]

Sequential input/output in Scheme is represented by operations on a port. Characters can be read from an input port and written to an output port. This chapter explains the operations that Guile provides for working with ports.

The formal definition of a port is very generic: an input port is simply "an object which can deliver characters on command," and an output port is "an object which can accept characters." Because this definition is so loose, it is easy to write functions that simulate ports in software. Soft ports and string ports are two interesting and powerful examples of this technique.

Scheme Procedure: input-port? x
C Function: scm_input_port_p (x): Return #t if x is an input port, otherwise return #f. Any object satisfying this predicate also satisfies port?.

Scheme Procedure: output-port? x
C Function: scm_output_port_p (x): Return #t if x is an output port, otherwise return #f. Any object satisfying this predicate also satisfies port?.

Scheme Procedure: port? x
C Function: scm_port_p (x): Return a boolean indicating whether x is a port. Equivalent to (or (input-port? x) (output-port? x)).

Reading

[Generic procedures for reading from ports.]

Scheme Procedure: eof-object? x
C Function: scm_eof_object_p (x): Return #t if x is an end-of-file object; otherwise return #f.

Scheme Procedure: char-ready? [port]
C Function: scm_char_ready_p (port): Return #t if a character is ready on input port and return #f otherwise. If char-ready? returns #t then the next read-char operation on port is guaranteed not to hang. If port is a file port at end of file then char-ready? returns #t. (11)

Scheme Procedure: read-char [port]
C Function: scm_read_char (port): Return the next character available from port, updating port to point to the following character. If no more characters are available, the end-of-file object is returned.

Scheme Procedure: peek-char [port]
C Function: scm_peek_char (port): Return the next character available from port, without updating port to point to the following character. If no more characters are available, the end-of-file object is returned.(12)

Scheme Procedure: unread-char cobj [port]
C Function: scm_unread_char (cobj, port): Place char in port so that it will be read by the next read operation. If called multiple times, the unread characters will be read again in last-in first-out order. If port is not supplied, the current input port is used.

Scheme Procedure: unread-string str port
C Function: scm_unread_string (str, port): Place the string str in port so that its characters will be read in subsequent read operations. If called multiple times, the unread characters will be read again in last-in first-out order. If port is not supplied, the current-input-port is used.

Scheme Procedure: drain-input port

C Function: scm_drain_input (port)

This procedure clears a port's input buffers, similar to the way that force-output clears the output buffer. The contents of the buffers are returned as a single string, e.g.,

(define p (open-input-file ...))
(drain-input p) => empty string, nothing buffered yet.
(unread-char (read-char p) p)
(drain-input p) => initial chars from p, up to the buffer size.

Draining the buffers may be useful for cleanly finishing buffered I/O so that the file descriptor can be used directly for further input.

Scheme Procedure: port-column port
Scheme Procedure: port-line port
C Function: scm_port_column (port)
C Function: scm_port_line (port): Return the current column number or line number of port, using the current input port if none is specified. If the number is unknown, the result is #f. Otherwise, the result is a 0-origin integer - i.e. the first character of the first line is line 0, column 0. (However, when you display a file position, for example in an error message, we recommend you add 1 to get 1-origin integers. This is because lines and column numbers traditionally start with 1, and that is what non-programmers will find most natural.)

Scheme Procedure: set-port-column! port column
Scheme Procedure: set-port-line! port line
C Function: scm_set_port_column_x (port, column)
C Function: scm_set_port_line_x (port, line): Set the current column or line number of port, using the current input port if none is specified.

Writing

[Generic procedures for writing to ports.]

Scheme Procedure: get-print-state port
C Function: scm_get_print_state (port): Return the print state of the port port. If port has no associated print state, #f is returned.

Scheme Procedure: display obj [port]: Send a representation of obj to current-output-port. Optional second arg port specifies an alternative output port. The representation is similar to that produced by write (REFFIXME), the differences being strings are not quoted (and their characters are not escaped), and characters are rendered as if with write-char.

Scheme Procedure: newline [port]
C Function: scm_newline (port): Send a newline to port. If port is omitted, send to the current output port.

Scheme Procedure: port-with-print-state port pstate
C Function: scm_port_with_print_state (port, pstate): Create a new port which behaves like port, but with an included print state pstate.

Scheme Procedure: print-options-interface [setting]
C Function: scm_print_options (setting): Option interface for the print options. Instead of using this procedure directly, use the procedures print-enable, print-disable, print-set! and print-options.

Scheme Procedure: simple-format destination message . args
C Function: scm_simple_format (destination, message, args): Write message to destination, defaulting to the current output port. message can contain ~A (was %s) and ~S (was %S) escapes. When printed, the escapes are replaced with corresponding members of ARGS: ~A formats using display and ~S formats using write. If destination is #t, then use the current output port, if destination is #f, then return a string containing the formatted text. Does not add a trailing newline.

Scheme Procedure: write-char chr [port]
C Function: scm_write_char (chr, port): Send character chr to port.

Scheme Procedure: force-output [port]
C Function: scm_force_output (port): Flush the specified output port, or the current output port if port is omitted. The current output buffer contents are passed to the underlying port implementation (e.g., in the case of fports, the data will be written to the file and the output buffer will be cleared.) It has no effect on an unbuffered port.
The return value is unspecified.

Scheme Procedure: flush-all-ports
C Function: scm_flush_all_ports (): Equivalent to calling force-output on all open output ports. The return value is unspecified.

Closing

Scheme Procedure: close-port port
C Function: scm_close_port (port): Close the specified port object. Return #t if it successfully closes a port or #f if it was already closed. An exception may be raised if an error occurs, for example when flushing buffered output. See also section Ports and File Descriptors, for a procedure which can close file descriptors.

Scheme Procedure: close-input-port port
C Function: scm_close_input_port (port): Close the specified input port object. The routine has no effect if the file has already been closed. An exception may be raised if an error occurs. The value returned is unspecified.
See also section Ports and File Descriptors, for a procedure which can close file descriptors.

Scheme Procedure: close-output-port port
C Function: scm_close_output_port (port): Close the specified output port object. The routine has no effect if the file has already been closed. An exception may be raised if an error occurs. The value returned is unspecified.
See also section Ports and File Descriptors, for a procedure which can close file descriptors.

Scheme Procedure: port-closed? port
C Function: scm_port_closed_p (port): Return #t if port is closed or #f if it is open.

Random Access

Scheme Procedure: seek fd_port offset whence

C Function: scm_seek (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. port may be a string port.

The value returned is the new position in the file. This means that the current position of a port can be obtained using:

(seek port 0 SEEK_CUR)

Scheme Procedure: ftell fd_port

C Function: scm_ftell (fd_port)

Return an integer representing the current position of fd/port, measured from the beginning. Equivalent to:

(seek port 0 SEEK_CUR)

Scheme Procedure: truncate-file object [length]
C Function: scm_truncate_file (object, length): Truncates the object referred to by object to at most length bytes. object can be a string containing a file name or an integer file descriptor or a port. length may be omitted if object is not a file name, in which case the truncation occurs at the current port. position. The return value is unspecified.

Line Oriented and Delimited Text

The delimited-I/O module can be accessed with:

(use-modules (ice-9 rdelim))

It can be used to read or write lines of text, or read text delimited by a specified set of characters. It's similar to the (scsh rdelim) module from guile-scsh, but does not use multiple values or character sets and has an extra procedure write-line.

Scheme 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.

Scheme 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).

Scheme 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.

Scheme 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).

Scheme Procedure: write-line obj [port]

C Function: scm_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])

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

Scheme Procedure: %read-delimited! delims str gobble [port [start [end]]]
C Function: scm_read_delimited_x (delims, str, gobble, port, start, end): Read characters from port into str until one of the characters in the delims string is encountered. If gobble is true, discard the delimiter character; otherwise, leave it in the input stream for the next read. 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 str bounded by start and end (which default to the beginning and end of the string, 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 string was filled without encountering a delimiter, this value is #f.

Scheme Procedure: %read-line [port]
C Function: scm_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>).

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.

Default Ports for Input, Output and Errors

Scheme Procedure: current-input-port
C Function: scm_current_input_port (): Return the current input port. This is the default port used by many input procedures. Initially, current-input-port returns the standard input in Unix and C terminology.

Scheme Procedure: current-output-port
C Function: scm_current_output_port (): Return the current output port. This is the default port used by many output procedures. Initially, current-output-port returns the standard output in Unix and C terminology.

Scheme Procedure: current-error-port
C Function: scm_current_error_port (): Return the port to which errors and warnings should be sent (the standard error in Unix and C terminology).

Scheme Procedure: set-current-input-port port
Scheme Procedure: set-current-output-port port
Scheme Procedure: set-current-error-port port
C Function: scm_set_current_input_port (port)
C Function: scm_set_current_output_port (port)
C Function: scm_set_current_error_port (port): Change the ports returned by current-input-port, current-output-port and current-error-port, respectively, so that they use the supplied port for input or output.

Scheme Procedure: set-current-output-port port: Set the current default output port to PORT.

Scheme Procedure: set-current-error-port port: Set the current default error port to PORT.

Types of Port

[Types of port; how to make them.]

File Ports

The following procedures are used to open file ports. See also section Ports and File Descriptors, for an interface to the Unix open system call.

Scheme Procedure: open-file filename mode

C Function: scm_open_file (filename, mode)

Open the file whose name is filename, and return a port representing that file. The attributes of the port are determined by the mode string. The way in which this is interpreted is similar to C stdio. The first character must be one of the following:

`r': Open an existing file for input.
`w': Open a file for output, creating it if it doesn't already exist or removing its contents if it does.
`a': Open a file for output, creating it if it doesn't already exist. All writes to the port will go to the end of the file. The "append mode" can be turned off while the port is in use see section Ports and File Descriptors

The following additional characters can be appended:

`+': Open the port for both input and output. E.g., r+: open an existing file for both input and output.
`0': Create an "unbuffered" port. In this case input and output operations are passed directly to the underlying port implementation without additional buffering. This is likely to slow down I/O operations. The buffering mode can be changed while a port is in use see section Ports and File Descriptors
`l': Add line-buffering to the port. The port output buffer will be automatically flushed whenever a newline character is written.

In theory we could create read/write ports which were buffered in one direction only. However this isn't included in the current interfaces. If a file cannot be opened with the access requested, open-file throws an exception.

Scheme Procedure: open-input-file filename

Open filename for input. Equivalent to

(open-file filename "r")

Scheme Procedure: open-output-file filename

Open filename for output. Equivalent to

(open-file filename "w")

Scheme Procedure: call-with-input-file file proc: proc should be a procedure of one argument, and file should be a string naming a file. The file must already exist. These procedures call proc with one argument: the port obtained by opening the named file for input or output. If the file cannot be opened, an error is signalled. If the procedure returns, then the port is closed automatically and the value yielded by the procedure is returned. If the procedure does not return, then the port will not be closed automatically unless it is possible to prove that the port will never again be used for a read or write operation.

Scheme Procedure: call-with-output-file file proc: proc should be a procedure of one argument, and file should be a string naming a file. The behaviour is unspecified if the file already exists. These procedures call proc with one argument: the port obtained by opening the named file for input or output. If the file cannot be opened, an error is signalled. If the procedure returns, then the port is closed automatically and the value yielded by the procedure is returned. If the procedure does not return, then the port will not be closed automatically unless it is possible to prove that the port will never again be used for a read or write operation.

Scheme Procedure: with-input-from-file file thunk: thunk must be a procedure of no arguments, and file must be a string naming a file. The file must already exist. The file is opened for input, an input port connected to it is made the default value returned by current-input-port, and the thunk is called with no arguments. When the thunk returns, the port is closed and the previous default is restored. Returns the value yielded by thunk. If an escape procedure is used to escape from the continuation of these procedures, their behavior is implementation dependent.

Scheme Procedure: with-output-to-file file thunk: thunk must be a procedure of no arguments, and file must be a string naming a file. The effect is unspecified if the file already exists. The file is opened for output, an output port connected to it is made the default value returned by current-output-port, and the thunk is called with no arguments. When the thunk returns, the port is closed and the previous default is restored. Returns the value yielded by thunk. If an escape procedure is used to escape from the continuation of these procedures, their behavior is implementation dependent.

Scheme Procedure: with-error-to-file file thunk: thunk must be a procedure of no arguments, and file must be a string naming a file. The effect is unspecified if the file already exists. The file is opened for output, an output port connected to it is made the default value returned by current-error-port, and the thunk is called with no arguments. When the thunk returns, the port is closed and the previous default is restored. Returns the value yielded by thunk. If an escape procedure is used to escape from the continuation of these procedures, their behavior is implementation dependent.

Scheme Procedure: port-mode port
C Function: scm_port_mode (port): Return the port modes associated with the open port port. These will not necessarily be identical to the modes used when the port was opened, since modes such as "append" which are used only during port creation are not retained.

Scheme Procedure: port-filename port
C Function: scm_port_filename (port): Return the filename associated with port. This function returns the strings "standard input", "standard output" and "standard error" when called on the current input, output and error ports respectively.

Scheme Procedure: set-port-filename! port filename
C Function: scm_set_port_filename_x (port, filename): Change the filename associated with port, using the current input port if none is specified. Note that this does not change the port's source of data, but only the value that is returned by port-filename and reported in diagnostic output.

Scheme Procedure: file-port? obj
C Function: scm_file_port_p (obj): Determine whether obj is a port that is related to a file.

String Ports

The following allow string ports to be opened by analogy to R4R* file port facilities:

Scheme Procedure: call-with-output-string proc
C Function: scm_call_with_output_string (proc): Calls the one-argument procedure proc with a newly created output port. When the function returns, the string composed of the characters written into the port is returned.

Scheme Procedure: call-with-input-string string proc
C Function: scm_call_with_input_string (string, proc): Calls the one-argument procedure proc with a newly created input port from which string's contents may be read. The value yielded by the proc is returned.

Scheme Procedure: with-output-to-string thunk: Calls the zero-argument procedure thunk with the current output port set temporarily to a new string port. It returns a string composed of the characters written to the current output.

Scheme Procedure: with-input-from-string string thunk: Calls the zero-argument procedure thunk with the current input port set temporarily to a string port opened on the specified string. The value yielded by thunk is returned.

Scheme Procedure: open-input-string str
C Function: scm_open_input_string (str): Take a string and return an input port that delivers characters from the string. The port can be closed by close-input-port, though its storage will be reclaimed by the garbage collector if it becomes inaccessible.

Scheme Procedure: open-output-string
C Function: scm_open_output_string (): Return an output port that will accumulate characters for retrieval by get-output-string. The port can be closed by the procedure close-output-port, though its storage will be reclaimed by the garbage collector if it becomes inaccessible.

Scheme Procedure: get-output-string port
C Function: scm_get_output_string (port): Given an output port created by open-output-string, return a string consisting of the characters that have been output to the port so far.

A string port can be used in many procedures which accept a port but which are not dependent on implementation details of fports. E.g., seeking and truncating will work on a string port, but trying to extract the file descriptor number will fail.

Soft Ports

A soft-port is a port based on a vector of procedures capable of accepting or delivering characters. It allows emulation of I/O ports.

Scheme Procedure: make-soft-port pv modes

C Function: scm_make_soft_port (pv, modes)

Return a port capable of receiving or delivering characters as specified by the modes string (see section File Ports). pv must be a vector of length 5. Its components are as follows:

procedure accepting one character for output
procedure accepting a string for output
thunk for flushing output
thunk for getting one character
thunk for closing port (not by garbage collection)

For an output-only port only elements 0, 1, 2, and 4 need be procedures. For an input-only port only elements 3 and 4 need be procedures. Thunks 2 and 4 can instead be #f if there is no useful operation for them to perform.

If thunk 3 returns #f or an eof-object (see section `Input' in The Revised^5 Report on Scheme) it indicates that the port has reached end-of-file. For example:

(define stdout (current-output-port))
(define p (make-soft-port
           (vector
            (lambda (c) (write c stdout))
            (lambda (s) (display s stdout))
            (lambda () (display "." stdout))
            (lambda () (char-upcase (read-char)))
            (lambda () (display "@" stdout)))
           "rw"))

(write p p) => #<input-output: soft 8081e20>

Void Ports

This kind of port causes any data to be discarded when written to, and always returns the end-of-file object when read from.

Scheme Procedure: %make-void-port mode
C Function: scm_sys_make_void_port (mode): Create and return a new void port. A void port acts like `/dev/null'. The mode argument specifies the input/output modes for this port: see the documentation for open-file in section File Ports.

Using and Extending Ports in C

C Port Interface

This section describes how to use Scheme ports from C.

Port basics

There are two main data structures. A port type object (ptob) is of type scm_ptob_descriptor. A port instance is of type scm_port. Given an SCM variable which points to a port, the corresponding C port object can be obtained using the SCM_PTAB_ENTRY macro. The ptob can be obtained by using SCM_PTOBNUM to give an index into the scm_ptobs global array.

Port buffers

An input port always has a read buffer and an output port always has a write buffer. However the size of these buffers is not guaranteed to be more than one byte (e.g., the shortbuf field in scm_port which is used when no other buffer is allocated). The way in which the buffers are allocated depends on the implementation of the ptob. For example in the case of an fport, buffers may be allocated with malloc when the port is created, but in the case of an strport the underlying string is used as the buffer.

The `rw_random` flag

Special treatment is required for ports which can be seeked at random. Before various operations, such as seeking the port or changing from input to output on a bidirectional port or vice versa, the port implementation must be given a chance to update its state. The write buffer is updated by calling the flush ptob procedure and the input buffer is updated by calling the end_input ptob procedure. In the case of an fport, flush causes buffered output to be written to the file descriptor, while end_input causes the descriptor position to be adjusted to account for buffered input which was never read.

The special treatment must be performed if the rw_random flag in the port is non-zero.

The `rw_active` variable

The rw_active variable in the port is only used if rw_random is set. It's defined as an enum with the following values:

SCM_PORT_READ: the read buffer may have unread data.
SCM_PORT_WRITE: the write buffer may have unwritten data.
SCM_PORT_NEITHER: neither the write nor the read buffer has data.

Reading from a port.

To read from a port, it's possible to either call existing libguile procedures such as scm_getc and scm_read_line or to read data from the read buffer directly. Reading from the buffer involves the following steps:

Flush output on the port, if rw_active is SCM_PORT_WRITE.
Fill the read buffer, if it's empty, using scm_fill_input.
Read the data from the buffer and update the read position in the buffer. Steps 2) and 3) may be repeated as many times as required.
Set rw_active to SCM_PORT_READ if rw_random is set.
update the port's line and column counts.

Writing to a port.

To write data to a port, calling scm_lfwrite should be sufficient for most purposes. This takes care of the following steps:

End input on the port, if rw_active is SCM_PORT_READ.
Pass the data to the ptob implementation using the write ptob procedure. The advantage of using the ptob write instead of manipulating the write buffer directly is that it allows the data to be written in one operation even if the port is using the single-byte shortbuf.
Set rw_active to SCM_PORT_WRITE if rw_random is set.

Port Implementation

This section describes how to implement a new port type in C.

As described in the previous section, a port type object (ptob) is a structure of type scm_ptob_descriptor. A ptob is created by calling scm_make_port_type.

All of the elements of the ptob, apart from name, are procedures which collectively implement the port behaviour. Creating a new port type mostly involves writing these procedures.

scm_make_port_type initializes three elements of the structure (name, fill_input and write) from its arguments. The remaining elements are initialized with default values and can be set later if required.

name

A pointer to a NUL terminated string: the name of the port type. This is the only element of scm_ptob_descriptor which is not a procedure. Set via the first argument to scm_make_port_type.

mark

Called during garbage collection to mark any SCM objects that a port object may contain. It doesn't need to be set unless the port has SCM components. Set using scm_set_port_mark.

free

Called when the port is collected during gc. It should free any resources used by the port. Set using scm_set_port_free.

print

Called when write is called on the port object, to print a port description. e.g., for an fport it may produce something like: #<input: /etc/passwd 3>. Set using scm_set_port_print.

equalp

Not used at present. Set using scm_set_port_equalp.

close

Called when the port is closed, unless it was collected during gc. It should free any resources used by the port. Set using scm_set_port_close.

write

Accept data which is to be written using the port. The port implementation may choose to buffer the data instead of processing it directly. Set via the third argument to scm_make_port_type.

flush

Complete the processing of buffered output data. Reset the value of rw_active to SCM_PORT_NEITHER. Set using scm_set_port_flush.

end_input

Perform any synchronization required when switching from input to output on the port. Reset the value of rw_active to SCM_PORT_NEITHER. Set using scm_set_port_end_input.

fill_input

Read new data into the read buffer and return the first character. It can be assumed that the read buffer is empty when this procedure is called. Set via the second argument to scm_make_port_type.

input_waiting

Return a lower bound on the number of bytes that could be read from the port without blocking. It can be assumed that the current state of rw_active is SCM_PORT_NEITHER. Set using scm_set_port_input_waiting.

seek

Set the current position of the port. The procedure can not make any assumptions about the value of rw_active when it's called. It can reset the buffers first if desired by using something like:

      if (pt->rw_active == SCM_PORT_READ)
	scm_end_input (object);
      else if (pt->rw_active == SCM_PORT_WRITE)
	ptob->flush (object);

However note that this will have the side effect of discarding any data in the unread-char buffer, in addition to any side effects from the end_input and flush ptob procedures. This is undesirable when seek is called to measure the current position of the port, i.e., (seek p 0 SEEK_CUR). The libguile fport and string port implementations take care to avoid this problem. The procedure is set using scm_set_port_seek.

truncate

Truncate the port data to be specified length. It can be assumed that the current state of rw_active is SCM_PORT_NEITHER. Set using scm_set_port_truncate.

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