On this page:
unsafe-file-descriptor->port
unsafe-socket->port
unsafe-port->file-descriptor
unsafe-port->socket
unsafe-file-descriptor->semaphore
unsafe-socket->semaphore

5.11 Ports

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

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)
For mode as 'read or 'write, returns a semaphore that becomes ready when fd or socket becomes ready for reading or writing, respectively. 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 'read-check and 'write-check 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.