EMILUA(3em)

📦 version 0.12.1, in nixos 26.05, nixpkgs unstable

🎀 NAME 🎀

okay bestie, welcome to the EMILUA(3em) manual page. Emilua is a Lua execution engine — literally the whole vibe. 💅

✨ SYNOPSIS ✨

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

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

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

🫶 FUNCTIONS 🫶

okay so this is the function lineup, no cap. every signature is staying exactly as written. 🫡

🌟 new 🌟

new() → unix.stream.socket
        new()                    (1)
        new(fd: file_descriptor) (2)
  • (1) — Default constructor. the starter pack, basically.
  • (2) — Converts a file_descriptor into an unix.stream.socket object.

💞 pair 💞

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

Creates a pair of connected sockets. socket twins fr fr. 👯‍♀️

🔓 open 🔓

open(self)

Opens the socket.

🪢 bind 🪢

bind(self, pathname: filesystem.path)

Binds the socket to the given local endpoint.

🚪 close 🚪

close(self)

Closes the socket.

Then it forwards the call to the <https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/basic_stream_socket/close/overload2.html> function with the same name in Boost.Asio. Boost.Asio says, quote:

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

🛑 cancel 🛑

cancel(self)

Cancels all asynchronous operations associated with the acceptor. (yes, it says acceptor — that’s the original wording, bestie. 🙈)

Then it forwards the call to the <https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/basic_stream_socket/cancel/overload2.html> function with the same name in Boost.Asio. Boost.Asio says, quote:

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 📎

assign(self, fd: file_descriptor)

Assigns an existing native socket to self.

🎁 release 🎁

release(self) → file_descriptor

Releases ownership of the native descriptor implementation.

Then it forwards the call to the <https://www.boost.org/doc/libs/1_81_0/doc/html/boost_asio/reference/basic_stream_socket/release/overload2.html> function with the same name in Boost.Asio. Boost.Asio says, quote:

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 🎛️

io_control(self, command: string[, ...])

Performs an IO control command on the socket.

Currently available commands are:

  • "bytes_readable" — Expects no arguments. Gets the amount of data that can be read without blocking. Implements the FIONREAD IO control command.

🔇 shutdown 🔇

shutdown(self, what: string)

Disables 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 🔌

connect(self, pathname: filesystem.path)

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

🫥 disconnect 🫥

disconnect(self)

Dissolves 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 📖

read_some(self, buffer: byte_span) → integer

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

Returns the number of bytes read.

✍️ write_some ✍️

write_some(self, buffer: byte_span) → integer

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

Returns the number of bytes written.

📥 receive_with_fds 📥

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

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

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

📤 send_with_fds 📤

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

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

Returns the number of bytes written.

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

⚙️ set_option ⚙️

set_option(self, opt: string, val)

Sets an option on the socket.

Currently available options are:

🔍 get_option 🔍

get_option(self, opt: string) → value

Gets an option from the socket.

Currently available options are:

⚠️ Caution: On Linux, groups don’t include the supplementary group list.
⚠️ Caution: 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.

mwah 💋 — this page is from Emilua version 0.12.1-nixpkgs1, dated 1980-01-01. EMILUA(3em) out. 🎀

📦 where this page comes from