►The Racket Foreign Interface
▼5 Derived Utilities
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
  top  ← prev  up  next → 

5.11 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:

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:

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  ← prev  up  next →