13.1.3 Port Buffers and Positions

► |  | The Racket Reference

1 | Language Model
2 | Notation for Documentation
3 | Syntactic Forms
4 | Datatypes
5 | Structures
6 | Classes and Objects
7 | Units
8 | Contracts
9 | Pattern Matching
10 | Control Flow
11 | Concurrency and Parallelism
12 | Macros
13 | Input and Output
14 | Reflection and Security
15 | Operating System
16 | Memory Management
17 | Unsafe Operations
18 | Running Racket
| Bibliography
| Index

► | 13 | Input and Output

13.1 | Ports
13.2 | Byte and String Input
13.3 | Byte and String Output
13.4 | Reading
13.5 | Writing
13.6 | Pretty Printing
13.7 | Reader Extension
13.8 | Printer Extension
13.9 | Serialization
13.10 | Fast-Load Serialization
13.11 | Cryptographic Hashing

▼ | 13.1 | Ports

13.1.1 | Encodings and Locales
13.1.2 | Managing Ports
13.1.3 | Port Buffers and Positions
13.1.4 | Counting Positions, Lines, and Columns
13.1.5 | File Ports
13.1.6 | String Ports
13.1.7 | Pipes
13.1.8 | Structures as Ports
13.1.9 | Custom Ports
13.1.10 | More Port Constructors, Procedures, and Events

On this page:

flush-output
file-stream-buffer-mode
file-position
file-position*
file-truncate

top contents ← prev up next →

#### 13.1.3 Port Buffers and Positions🔗ℹ

Some ports—especially those that read from and write to files—are internally buffered:

- An input port is typically block-buffered by default, which means that on any read, the buffer is filled with immediately-available bytes to speed up future reads. Thus, if a file is modified between a pair of reads to the file, the second read can produce stale data. Calling file-position to set an input port’s file position flushes its buffer.

- An output port is typically block-buffered by default, though a terminal output port is line-buffered, and the initial error output port is unbuffered. An output buffer is filled with a sequence of written bytes to be committed as a group, either when the buffer is full (in block mode), when a newline is written (in line mode), when the port is closed via close-output-port, or when a flush is explicitly requested via a procedure like flush-output.

If a port supports buffering, its buffer mode can be changed via file-stream-buffer-mode (even if the port is not a file-stream port).

For an input port, peeking always places peeked bytes into the port’s buffer, even when the port’s buffer mode is 'none; furthermore, on some platforms, testing the port for input (via char-ready? or sync) may be implemented with a peek. If an input port’s buffer mode is 'none, then at most one byte is read for read-bytes-avail!*, read-bytes-avail!, peek-bytes-avail!*, or peek-bytes-avail!; if any bytes are buffered in the port (e.g., to satisfy a previous peek), the procedures may access multiple buffered bytes, but no further bytes are read.

In addition, the initial current output and error ports are automatically flushed when they are terminal ports (see terminal-port?) and when read, read-line, read-bytes, read-string, etc., are performed on the initial standard input port. (More precisely, instead of read, flushing is performed by the default port read handler; see port-read-handler.)

> procedure (flush-output [out]) → void?
> out : output-port? = (current-output-port)

Forces all buffered data in the given output port to be physically written. Only file-stream ports, TCP ports, and custom ports (see Custom Ports) use buffers; when called on a port without a buffer, flush-output has no effect.

If flushing a file-stream port or TCP port encounters an error when writing, then all buffered bytes in the port are discarded. Consequently, a further attempt to flush or close the port will not fail.

Changed in version 7.4.0.10 of package base: Consistently, discard buffered bytes on error, including in a TCP output port.

> procedure (file-stream-buffer-mode port) → (or/c 'none 'line 'block #f)
> port : port?
> (file-stream-buffer-mode port mode) → void?
> port : port?
> mode : (or/c 'none 'line 'block)

Gets or sets the buffer mode for port, if possible. File-stream ports support setting the buffer mode, TCP ports (see Networking) support setting and getting the buffer mode, and custom ports (see Custom Ports) may support getting and setting buffer modes.

If mode is provided, it must be one of 'none, 'line (output only), or 'block, and the port’s buffering is set accordingly. If the port does not support setting the mode, the exn:fail exception is raised.

If mode is not provided, the current mode is returned, or #f is returned if the mode cannot be determined. If port is an input port and mode is 'line, the exn:fail:contract exception is raised.

> procedure (file-position port) → exact-nonnegative-integer?
> port : port?
> (file-position port pos) → void?
> port : port?
> pos : (or/c exact-nonnegative-integer? eof-object?)

Returns or sets the current read/write position of port.

Calling file-position without a position on a port other than a file-stream port or string port returns the number of bytes that have been read from that port if the position is known (see Counting Positions, Lines, and Columns), otherwise the exn:fail:filesystem exception is raised.

For file-stream ports and string ports, the position-setting variant sets the read/write position to pos relative to the beginning of the file or (byte) string if pos is a number, or to the current end of the file or (byte) string if pos is eof. In position-setting mode, file-position raises the exn:fail:contract exception for port kinds other than file-stream ports and string ports. Furthermore, not all file-stream ports support setting the position; if file-position is called with a position argument on such a file-stream port, the exn:fail:filesystem exception is raised.

When file-position sets the position pos beyond the current size of an output file or (byte) string, the file/string is enlarged to size pos and the new region is filled with 0 bytes; in the case of a file. In the case of a file output port, the file might not be enlarged until more data is written to the file; in that case, beware that writing to a file opened in 'append mode on Unix and Mac OS will reset the file pointer to the end of a file before each write, which defeats file enlargement via file-position. If pos is beyond the end of an input file or (byte) string, then reading thereafter returns eof without changing the port’s position.

When changing the file position for an output port, the port is first flushed if its buffer is not empty. Similarly, setting the position for an input port clears the port’s buffer (even if the new position is the same as the old position). However, although input and output ports produced by open-input-output-file share the file position, setting the position via one port does not flush the other port’s buffer.

> procedure (file-position* port) → (or/c exact-nonnegative-integer? #f)
> port : port?

Like file-position on a single argument, but returns #f if the position is not known.

> procedure (file-truncate port size) → void?
> port : (and/c output-port? file-stream-port?)
> size : exact-nonnegative-integer?

Sets the size of the file written by port to size, assuming that the port is associated to a file whose size can be set.

The new file size can be either larger or smaller than its current size, but “truncate” in this function’s name reflects that it is normally used to decrease the size of a file, since writing to a file or using file-position can extend a file’s size.

top contents ← prev up next →