5.12 Ports

► |  | The Racket Foreign Interface

1 | Overview
2 | Loading Foreign Libraries
3 | C Types
4 | Pointer Functions
5 | Derived Utilities
6 | Miscellaneous Support
7 | Unexported Primitive Functions
| Bibliography
| Index

▼ | 5 | Derived Utilities

5.1 | Safe Homogenous Vectors
5.2 | Safe C Vectors
5.3 | Tagged C Pointer Types
5.4 | Serializable C Struct Types
5.5 | Static Callout and Callback Cores
5.6 | Defining Bindings
5.7 | Allocation and Finalization
5.8 | Custodian Shutdown Registration
5.9 | Atomic Execution
5.10 | Speculatively Atomic Execution
5.11 | Thread Scheduling
5.12 | Ports
5.13 | Process-Wide and Place-Wide Registration
5.14 | Operating System Threads
5.15 | Garbage Collection Callbacks
5.16 | Objective-C FFI
5.17 | Cocoa Foundation
5.18 | COM (Common Object Model)
5.19 | File Security-Guard Checks
5.20 | Windows API Helpers
5.21 | Virtual Machine Primitives
5.22 | Declaring Foreign Libraries Needed at Run Time

On this page:

unsafe-file-descriptor->port
unsafe-socket->port
unsafe-port->file-descriptor
unsafe-port->socket
unsafe-file-descriptor->semaphore
unsafe-socket->semaphore
unsafe-fd->evt

Racket
top contents ← prev up next →

### 5.12 Ports🔗ℹ

(require ffi/unsafe/port) | package: base

The ffi/unsafe/port library provides functions for working with ports, file descriptors, and sockets. The library’s operations are unsafe, because no checking is performed on file descriptors and sockets, and misuse of file descriptors and sockets can break other objects.

Added in version 6.11.0.4 of package base.

> procedure (unsafe-file-descriptor->port fd name mode)
> → (or/c port? (values input-port? output-port?))
> fd : exact-integer?
> name : any/c
> mode : (listof (or/c 'read 'write 'text 'regular-file))
> > procedure
> > (unsafe-socket->port socket name mode) |  | → |  |
> > input-port? |  | output-port?
> socket : exact-integer?
> name : bytes?
> mode : (listof (or/c 'no-close))

Returns an input port and/or output port for the given file descriptor or socket. On Windows, a “file descriptor” corresponds to a file HANDLE, while a socket corresponds to a SOCKET. On Unix, a socket is a file descriptor, but using the socket-specific unsafe-socket->port may enable socket-specific functionality, such as address reporting via tcp-addresses.

The name argument determines the port’s name as reported by object-name. The name must be a UTF-8 encoding that is converted to a symbol for the socket name.

For a file descriptor, the mode list must include at least one of 'read or 'write, and two ports are returned if mode includes both 'read and 'write. The 'text mode affects only Windows ports. The 'regular-file mode indicates that the file descriptor corresponds to a regular file (which has the property, for example, that reading never blocks). Closing all returned file-descriptor ports closes the file descriptor.

For a socket, the mode list can include 'no-close, in which case closing both of the returned ports does not close the socket.

For any kind of result port, closing the resulting ports readies and unregisters any semaphores for the file descriptor or socket that were previously created with unsafe-file-descriptor->semaphore or unsafe-socket->semaphore.

> procedure (unsafe-port->file-descriptor p) → (or/c exact-integer? #f)
> p : port?
> procedure (unsafe-port->socket p) → (or/c exact-integer? #f)
> p : port?

Returns a file descriptor (which is a HANDLE value on Windows) of a socket for port if it has one, #f otherwise.

On Unix and Mac OS, the result of unsafe-port->file-descriptor can be #f if it corresponds to a port that is waiting for its peer as reported by port-waiting-peer?, such as the write end of a fifo where no reader is connected. Wait until such is ready by using sync).

Changed in version 7.4.0.5 of package base: Accommodate a fifo write end blocked on a reader by returning #f.

> procedure (unsafe-file-descriptor->semaphore fd mode)
> → (or/c semaphore? #f)
> fd : exact-integer?
> mode : (or/c 'read 'write 'check-read 'check-write 'remove)
> procedure (unsafe-socket->semaphore socket mode) → (or/c semaphore? #f)
> socket : exact-integer?
> mode : (or/c 'read 'write 'check-read 'check-write 'remove)

Returns a semaphore that becomes ready when fd or socket is ready for reading or writing, as selected by mode. Specifically, these functions provide a one-shot, edge-triggered indicator; the semaphore is posted the first time any of the following cases holds:

- fd or socket is ready for reading or writing (depending on mode),

- ports were created from fd or socket using unsafe-file-descriptor->port or unsafe-socket->port, and those ports were closed, or

- a subsequent call occurred with the same fd or socket and with 'remove for mode.

The result is #f if a conversion to a semaphore is not supported for the current platform or for the given file descriptor or socket.

The 'check-read and 'check-write modes are like 'read and 'write, but the result if #f if a semaphore is not already generated for the specified file descriptor or socket in the specified mode.

The 'remove mode readies and unregisters any semaphores previously created for the given file descriptor or socket. Semaphores must be unregistered before the file descriptor or socket is closed. Beware that closing a port from unsafe-file-descriptor->port or unsafe-socket->port will also ready and unregister semaphores. In all of those cases, however, the semaphore is made ready asynchronously, so there may be a detectable delay.

> procedure (unsafe-fd->evt fd mode [socket?]) → (or/c evt? #f)
> fd : exact-integer?
> mode : (or/c 'read 'write 'check-read 'check-write 'remove)
> socket? : any/c = #t

Returns an event that is ready when fd is ready for reading or writing, as selected by mode. Specifically, it returns a multi-use, level-triggered indicator; the event is ready whenever any of the following cases holds:

- fd is ready for reading or writing (depending on mode),

- a subsequent call occurred with the same fd and with 'remove for mode (once removed, the event is perpetually ready).

The synchronization result of the event is the event itself.

The 'check-read and 'check-write modes are like 'read and 'write, but the result is #f if an event is not already generated for the specified file descriptor or socketin the specified mode.

The 'remove mode readies and unregisters any events previously created for the given file descriptor or socket. Events must be unregistered before the file descriptor or socket is closed. Unlike the semaphore result of unsafe-file-descriptor->semaphore and unsafe-socket->semaphore, the event result of unsafe-fd->evt is not triggered or unregistered by closing a port—not even a port from unsafe-file-descriptor->port or unsafe-socket->port.

Added in version 7.2.0.6 of package base.

top contents ← prev up next →