file.stream

Functions

`new() → file.stream`

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

1	Default constructor.
2	Converts a file descriptor into a `file.stream` 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

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

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

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

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

Properties

`is_open: boolean`

Whether the file is open.

`size: integer`

The size of the file.