EMILUA(3em)

💖 NAME 💖

okay bestie, welcome to EMILUA(3em) — the Emilua reference manual page. Emilua is a Lua execution engine, and this page is your group chat for the functions and properties below. no cap, we are keeping every flag, caveat, and tiny little detail. ✨

---

✨ FUNCTIONS ✨

🐚 new() → file.stream

new() → file.stream
  new()                    (1)
  new(fd: file_descriptor) (2)

• (1) — default constructor. literally just makes one. 💅
• (2) — converts a file_descriptor into a file.stream object. slay.

🌟 open(self, path: filesystem.path, flags: string[])

Open the file using the specified path. The flags list may contain:

• "append" — open the file in append mode. 🎀
• "create" — create the file if it does not exist.
• "exclusive" — ensure a new file is created. Must be combined with "create". 💅
• "read_only" — open the file for reading.
• "read_write" — open the file for reading and writing.
• "sync_all_on_write" — open the file so that write operations automatically synchronise the file data and metadata to disk (FILE_FLAG_WRITE_THROUGH/O_SYNC). iconic.
• "truncate" — open the file with any existing contents truncated. 💀
• "write_only" — open the file for writing.

🫶 close(self)

Close the file. It forwards the call to Boost.Asio's same-named function at https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/basic_stream_file/close/overload2.html. Boost.Asio says: any asynchronous read or write operations will be cancelled immediately, and will complete with the boost::asio::error::operation_aborted error. so if you had stuff in flight, it is getting cancelled, bestie. 😭

🦋 cancel(self)

Cancel all asynchronous operations associated with the file. It forwards to Boost.Asio's same-named function at https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/basic_stream_file/cancel/overload2.html. Boost.Asio says this function causes all outstanding asynchronous read and write operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation_aborted error. fr fr. 💅

🌈 assign(self, fd: file_descriptor)

Assign an existing native file to self. simple as that. 🫶

👑 release(self) → file_descriptor

Release ownership of the native descriptor implementation. It forwards to Boost.Asio's same-named function at https://www.boost.org/doc/libs/1_78_0/doc/html/boost_asio/reference/basic_stream_file/release/overload2.html. Boost.Asio says this causes all outstanding asynchronous read and write operations to finish immediately, and the handlers for cancelled operations will be passed the boost::asio::error::operation_aborted error. Ownership of the native file is then transferred to the caller. main character energy, honestly. 🔥

🍓 resize(self, n: integer)

Alter the size of the file. This function resizes the file to the specified size, in bytes. If the current file size exceeds n then any extra data is discarded. If the current size is less than n then the file is extended and filled with zeroes. 🎀

🧚 seek(self, offset: integer, whence: string) → integer

Sets and gets the file position, measured from the beginning of the file, to the position given by offset plus a base specified by the string whence, as follows:

• "set" — seek to an absolute position.
• "cur" — seek to an offset relative to the current file position.
• "end" — seek to an offset relative to the end of the file.

Returns the final file position, measured in bytes from the beginning of the file.

Important: Lua conventions on index starting at 1 are ignored. Indexes here are OS-mandated and start at 0. like, do not come in here assuming Lua indexing, bestie. 😭

🔒 lock(self)

Acquires an exclusive advisory lock on the file. See flock(2).

Note: not available on Windows. 💀

🔒 lock_shared(self)

Acquires a shared advisory lock on the file. See flock(2).

Note: not available on Windows. 💀

🔓 try_lock(self) → boolean

Tries to acquire an exclusive advisory lock on the file. Returns whether lock acquisition was successful. See flock(2).

Note: the current fiber is never suspended. ✨ Note: not available on Windows. 💀

🔓 try_lock_shared(self) → boolean

Tries to acquire a shared advisory lock on the file. Returns whether lock acquisition was successful. See flock(2).

Note: the current fiber is never suspended. ✨ Note: not available on Windows. 💀

🗝️ unlock(self)

Releases an existing advisory lock on the file held by this process. See flock(2).

Note: the current fiber is never suspended. ✨ Note: not available on Windows. 💀

📖 read_some(self, buffer: byte_span) → integer

Read data from the stream file and blocks current fiber until it completes or errs. Returns the number of bytes read. yup, that is the whole vibe. 🫶

✍️ write_some(self, buffer: byte_span) → integer

Write data to the stream file and blocks current fiber until it completes or errs. Returns the number of bytes written. slay that buffer. 💅

---

🌸 PROPERTIES 🌸

🎀 is_open: boolean

Whether the file is open. the vibe check for your file, basically. ✨

📏 size: integer

The size of the file. no cap. 🍓

---

mwah 💋 that is the page, bestie. this is from Emilua 0.12.1-nixpkgs1, dated 1980-01-01 — see u next time, and do not forget the zero-based indexing. 🫶✨