For the latest stable version, please use Emilua API 0.10!

unix.stream.socket

local a, b = unix.stream.socket.pair()

spawn(function()
    local buf = byte_span.new(1024)
    local nread = b:read_some(buf)
    print(buf:slice(1, nread))
end):detach()

local nwritten = stream.write_all(a, 'Hello World')
print(nwritten)

Functions

new() → unix.stream.socket

new()                    (1)
new(fd: file_descriptor) (2)
1 Default constructor.
2 Converts a file descriptor into an unix.stream.socket object.

pair() → unix.stream.socket, unix.stream.socket

Create a pair of connected sockets.

open(self)

Open the socket.

bind(self, pathname: filesystem.path)

Bind the socket to the given local endpoint.

close(self)

Close the socket.

Any asynchronous send, receive or connect operations will be cancelled immediately, and will complete with the boost::asio::error::operation_aborted error.

cancel(self)

Cancel all asynchronous operations associated with the acceptor.

This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation_aborted error.

assign(self, fd: file_descriptor)

Assign an existing native socket to self.

release(self) → file_descriptor

Release ownership of the native descriptor implementation.

This function causes all outstanding asynchronous connect, send and receive operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation_aborted error. Ownership of the native socket is then transferred to the caller.

io_control(self, command: string[, …​])

Perform an IO control command on the socket.

Currently available commands are:

"bytes_readable"

Expects no arguments. Get the amount of data that can be read without blocking. Implements the FIONREAD IO control command.

shutdown(self, what: string)

Disable sends or receives on the socket.

what can be one of the following:

"receive"

Shutdown the receive side of the socket.

"send"

Shutdown the send side of the socket.

"both"

Shutdown both send and receive on the socket.

connect(self, pathname: filesystem.path)

Initiate a connect operation and blocks current fiber until it completes or errs.

disconnect(self)

Dissolve the socket’s association by resetting the socket’s peer address (i.e. connect(3) will be called with an AF_UNSPEC address).

read_some(self, buffer: byte_span) → integer

Read data from the stream socket and blocks current fiber until it completes or errs.

Returns the number of bytes read.

write_some(self, buffer: byte_span) → integer

Write data to the stream socket and blocks current fiber until it completes or errs.

Returns the number of bytes written.

receive_with_fds(self, buffer: byte_span, maxfds: integer) → integer, file_descriptor[]

Read data from the stream socket and blocks current fiber until it completes or errs.

Returns the number of bytes read + the table containing the fds read.

send_with_fds(self, buffer: byte_span, fds: file_descriptor[]) → integer

Write data to the stream socket and blocks current fiber until it completes or errs.

Returns the number of bytes written.

fds are not closed and can be re-converted to some Emilua IO object if so one wishes.

set_option(self, opt: string, val)

Set an option on the socket.

Currently available options are:

"send_low_watermark"

Check Boost.Asio documentation.

"send_buffer_size"

Check Boost.Asio documentation.

"receive_low_watermark"

Check Boost.Asio documentation.

"receive_buffer_size"

Check Boost.Asio documentation.

"debug"

Check Boost.Asio documentation.

get_option(self, opt: string) → value

Get an option from the socket.

Currently available options are:

"send_low_watermark"

Check Boost.Asio documentation.

"send_buffer_size"

Check Boost.Asio documentation.

"receive_low_watermark"

Check Boost.Asio documentation.

"receive_buffer_size"

Check Boost.Asio documentation.

"debug"

Check Boost.Asio documentation.

"remote_credentials": { uid: integer, groups: integer[], pid: integer }

Returns the credentials from the remote process.

On Linux, groups don’t include the supplementary group list.
pid is racy and you shouldn’t use it for anything but debugging purposes.
"remote_security_labels": { [string]: string }|string|nil

(FreeBSD only) Returns the security labels associated with each policy for the remote process.

Optionally one may pass an extra argument to get_option() with either a list of strings for the policies of interest, or just a single string in case there’s only one policy of interest.

"remote_security_label": string

(Linux only) Returns the SELinux security label associated with the remote process.

Properties

is_open: boolean

Whether the socket is open.

local_path: filesystem.path

The local address of the socket.

remote_path: filesystem.path

The remote address of the socket.