12.1 Ports

► |  | The Racket Reference

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

► | 12 | Input and Output

12.1 | Ports
12.2 | Byte and String Input
12.3 | Byte and String Output
12.4 | Reading
12.5 | Writing
12.6 | Pretty Printing
12.7 | Reader Extension
12.8 | Printer Extension
12.9 | Serialization
12.10 | Fast-Load Serialization

▼ | 12.1 | Ports

12.1.1 | Encodings and Locales
12.1.2 | Managing Ports
12.1.3 | Port Buffers and Positions
12.1.4 | Counting Positions, Lines, and Columns
12.1.5 | File Ports
12.1.6 | String Ports
12.1.7 | Pipes
12.1.8 | Structures as Ports
12.1.9 | Custom Ports
12.1.10 | More Port Constructors, Procedures, and Events

top ← prev up next →

#### 12.1`` Ports

Ports produce and/or consume bytes. An input port produces bytes, while an output port produces bytes (and some ports are both input ports and output ports). When an input port is provided to a character-based operation, the bytes are decoded to a character, and character-based output operations similarly encode the character to bytes; see Encodings and Locales. In addition to bytes and characters encoded as bytes, some ports can produce and/or consume arbitrary values as special results.

When a port corresponds to a file, network connection, or some other system resource, it must be explicitly closed via close-input-port or close-output-port (or indirectly via custodian-shutdown-all) to release low-level resources associated with the port. For any kind of port, after it is closed, attempting to read from or write to the port raises exn:fail.

Data produced by a input port can be read or peeked. When data is read, it is considered consumed and removed from the port’s stream. When data is peeked, it remains in the port’s stream to be returned again by the next read or peek. Previously peeked data can be committed, which causes the data to be removed from the port as for a read in a way that can be synchronized with other attempts to peek or read through a synchronizable event. Both read and peek operations are normally blocking, in the sense that the read or peek operation does not complete until data is available from the port; non-blocking variants of read and peek operations are also available.

The global variable eof is bound to the end-of-file value, and eof-object? returns #t only when applied to this value. Reading from a port produces an end-of-file result when the port has no more data, but some ports may also return end-of-file mid-stream. For example, a port connected to a Unix terminal returns an end-of-file when the user types control-D; if the user provides more input, the port returns additional bytes after the end-of-file.

Every port has a name, as reported by object-name. The name can be any value, and it is used mostly for error-reporting purposes. The read-syntax procedure uses the name of an input port as the default source location for the syntax objects that it produces.

A port can be used as a synchronizable event. An input port is ready for synchronization when read-byte would not block, and an output port is ready for synchronization when write-bytes-avail would not block or when the port contains buffered characters and write-bytes-avail* can flush part of the buffer (although write-bytes-avail might block). A value that can act as both an input port and an output port acts as an input port for a synchronizable event. The synchronization result of a port is the port itself.

12.1.1 Encodings and Locales
12.1.2 Managing Ports
12.1.3 Port Buffers and Positions
12.1.4 Counting Positions, Lines, and Columns
12.1.5 File Ports
12.1.6 String Ports
12.1.7 Pipes
12.1.8 Structures as Ports
12.1.9 Custom Ports
12.1.10 More Port Constructors, Procedures, and Events
12.1.10.1 Port String and List Conversions
12.1.10.2 Creating Ports
12.1.10.3 Port Events
12.1.10.4 Copying Streams

top ← prev up next →