13.1 Ports

► |  | 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

top ← prev up next →

#### 13.1`` Ports

Ports produce and/or consume bytes. An input port produces bytes, while an output port consumes 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.

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
13.1.10.1 Port String and List Conversions
13.1.10.2 Creating Ports
13.1.10.3 Port Events
13.1.10.4 Copying Streams

top ← prev up next →