file.random_access

Functions

`new() → file.random_access`

new()                    (1)
new(fd: file_descriptor) (2)

1	Default constructor.
2	Converts a file descriptor into a `file.random_access` object.

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

Open the file using the specified path.

flags 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).
"truncate": Open the file with any existing contents truncated.
"write_only": Open the file for writing.

`close(self)`

Close the file.

Forward the call to the function with same name in Boost.Asio:

Any asynchronous read or write 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 file.

Forward the call to the function with same name in Boost.Asio:

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.

`assign(self, fd: file_descriptor)`

Assign an existing native file to self.

`release(self) → file_descriptor`

Release ownership of the native descriptor implementation.

Forward the call to the function with same name in Boost.Asio:

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. Ownership of the native file is then transferred to the caller.

`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

`lock(self)`

Acquires an exclusive advisory lock on the file.

See flock(2).

Not available on Windows.

`lock_shared(self)`

Acquires a shared advisory lock on the file.

See flock(2).

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

The current fiber is never suspended.

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

The current fiber is never suspended.

Not available on Windows.

`unlock(self)`

Releases an existing advisory lock on the file held by this process.

See flock(2).

The current fiber is never suspended.

Not available on Windows.

`read_some_at(self, offset: integer, buffer: byte_span) → integer`

Read data from the file at the specified offset and blocks current fiber until it completes or errs.

Returns the number of bytes read.

Lua conventions on index starting at 1 are ignored. Indexes here are OS-mandated and start at 0.

`write_some_at(self, offset: integer, buffer: byte_span) → integer`

Write data to the file at the specified and blocks current fiber until it completes or errs.

Returns the number of bytes written.

Lua conventions on index starting at 1 are ignored. Indexes here are OS-mandated and start at 0.

Properties

`is_open: boolean`

Whether the file is open.

`size: integer`

The size of the file.