dymokomi/luce-std
Source of release 0.7.3
0.7.3 / src / files / handles.lucb
#==============================================================================================
#
# handles - Open files and their descriptors
#
# DESCRIPTION:
# A File over an OS descriptor, opened by policy (replace, create_new, append), with
# read, write, seek, sync, truncate, metadata and permission operations, and the line,
# text and byte reads a Luce program uses through `files.open`.
#
#==============================================================================================
## File opening policy. `replace` creates or truncates; `create_new` refuses an
## existing path; `create_new_read_write` also permits reads. `append` creates if
## needed and makes each write append atomically. `create_temporary` is
## `create_new_read_write` for a file nobody else should find: it goes away with
## its last handle, even when the process is killed. On POSIX its name is removed
## as soon as it is open; on Windows the system deletes it when the last handle
## closes (FILE_FLAG_DELETE_ON_CLOSE).
## Creation permissions are filtered by the process umask, never changed afterward.
pub enum OpenMode as u8:
read = 0
read_write = 1
replace = 2
create_new = 3
append = 4
create_new_read_write = 5
create_temporary = 6
## Where a seek offset is measured from.
pub enum SeekOrigin as u8:
start = 0
current = 1
end = 2
# mark: The open file =========================================================================
## One owned descriptor. The zero value is closed. Borrow through a pointer or an
## io interface; copying this value does not duplicate ownership or the OS handle.
## A copied value must not be independently closed. Calls on one handle require
## external synchronization. `close` reports errors; `destroy` is unwind cleanup.
## Luce sees a File as an object, opened by `files.open` and closed by `with` or `close()`.
pub struct File: io.Reader, io.Writer:
var handle: i32?
## Bytes `read_line` and `read_text` fetched beyond what they answered; `read` and
## `seek` account for them.
var ahead: readahead.ReadAhead
## Open a close-on-exec descriptor. Only the named creation modes create paths.
pub static func open(path: c.str, mode: OpenMode = OpenMode.read, permissions: u32 = 420) -> File!:
let temporary = mode == OpenMode.create_temporary
let flags = try file_open_flags(OpenMode.create_new_read_write if temporary else mode, permissions)
var fd = try open_descriptor(path, flags, permissions, temporary)
while fd < 0 and c.errno() == c.interrupted:
fd = try open_descriptor(path, flags, permissions, temporary)
if fd < 0:
error(classify_error(c.errno()), "the file could not be opened")
var opened = File(handle = fd)
if temporary:
try forget_name(path, &opened)
return opened
## Borrow the descriptor for OS interoperability; none after close. The caller
## must not close it or retain it past this owner's lifetime.
pub func descriptor() -> i32?:
return self.handle
## Query the open object, even after its pathname has been renamed or removed.
pub func metadata() -> Metadata!:
let descriptor = self.handle else error(io.closed, "the file is closed")
return try metadata_descriptor(descriptor)
## Set the logical length without moving the file position. Shrinking
## discards the suffix; extension reads as zero bytes. Requires a writable
## descriptor. Reject negative lengths before calling the OS.
pub func truncate(length: i64) -> !:
let descriptor = self.handle else error(io.closed, "the file is closed")
if length < 0:
error(invalid_options, "a file length cannot be negative")
var result = ftruncate(descriptor, length)
while result != 0 and c.errno() == c.interrupted:
result = ftruncate(descriptor, length)
if result != 0:
error(classify_error(c.errno()), "the file length could not be changed")
## Set permission and special mode bits on this opened object, independent
## of pathname changes. Umask is not applied. Host permission rules may
## reject or clear requested special bits; inspect metadata for the result.
pub func set_permissions(permissions: u32) -> !:
let descriptor = self.handle else error(io.closed, "the file is closed")
if permissions > 4095:
error(invalid_options, "file permissions must fit the Unix mode bits")
if platform.windows:
try windows_permissions(descriptor, permissions)
return
else:
while true:
let result = fchmod_macos(descriptor, (u16)permissions) if platform.macos else fchmod_linux(descriptor, permissions)
if result == 0:
return
if c.errno() != c.interrupted:
error(classify_error(c.errno()), "file permissions could not be changed")
## Set explicit access and modification times; creation/status-change times
## are not set by this operation. Validate nanoseconds before the OS call.
## The filesystem's range and timestamp resolution still apply.
pub func set_times(accessed: FileTime, modified: FileTime) -> !:
let descriptor = self.handle else error(io.closed, "the file is closed")
if accessed.nanoseconds >= 1000000000 or modified.nanoseconds >= 1000000000:
error(invalid_options, "a timestamp nanosecond fraction must be below one billion")
if platform.windows:
try windows_set_times(descriptor, accessed, modified)
return
else:
let times: NativeFileTime[2] = [NativeFileTime(seconds = accessed.seconds, nanoseconds = (i64)accessed.nanoseconds),
NativeFileTime(seconds = modified.seconds, nanoseconds = (i64)modified.nanoseconds)]
var result = futimens(descriptor, ×[0])
while result != 0 and c.errno() == c.interrupted:
result = futimens(descriptor, ×[0])
if result != 0:
error(classify_error(c.errno()), "file timestamps could not be changed")
## Read some bytes, retrying interruption. Zero for nonempty storage is EOF;
## empty input makes no system call. The handle must be open even for empty I/O.
pub func read(buffer: u8[]) -> usize!:
let fd = self.handle else error(io.closed, "the file is closed")
if self.ahead.count() > 0:
return self.ahead.take(buffer)
return try read_descriptor(fd, buffer)
## Write some bytes, retrying interruption. Use io.write_all for a full payload.
## Success confirms an OS write, not durable storage; call sync when required.
pub func write(data: const u8[]) -> usize!:
let fd = self.handle else error(io.closed, "the file is closed")
if data.length == 0:
return 0
if self.ahead.count() > 0:
# bytes read ahead were not answered yet: write where the reader stands
_ = try self.seek(0, SeekOrigin.current)
let count = data.length if data.length < transfer_limit else transfer_limit
var written = c_write(fd, data.data, count)
while written < 0 and c.errno() == c.interrupted:
written = c_write(fd, data.data, count)
if written < 0:
error(classify_error(c.errno()), "the file could not be written")
return (usize)written
## Seek a seekable file and return its resulting byte offset. Pipes and other
## unseekable descriptors report failure instead of pretending their size is zero.
pub func seek(offset: i64, origin: SeekOrigin = SeekOrigin.start) -> i64!:
let fd = self.handle else error(io.closed, "the file is closed")
# the descriptor stands past the bytes read ahead; a relative seek starts before them
let target = offset - (i64)self.ahead.count() if origin == SeekOrigin.current else offset
var position = lseek(fd, target, (i32)origin)
while position < 0 and c.errno() == c.interrupted:
position = lseek(fd, target, (i32)origin)
if position < 0:
error(classify_error(c.errno()), "the file could not be positioned")
self.ahead.clear()
return position
## Request the OS's fsync durability boundary for this file; this does not sync
## a containing directory or promise persistence beyond the OS/device contract.
pub func sync() -> !:
let fd = self.handle else error(io.closed, "the file is closed")
var result = fsync(fd)
while result < 0 and c.errno() == c.interrupted:
result = fsync(fd)
if result < 0:
error(classify_error(c.errno()), "the file could not be synchronized")
# mark: Lines, text and bytes ============================================================
## The next line without its `\n` or `\r\n`; the unfinished last line at the end, and
## none after it. A line that is not UTF-8 is invalid_text. The view lasts until the
## next read.
pub func read_line() -> str?!:
var source = Descriptor(handle = self.handle else error(io.closed, "the file is closed"))
return try self.ahead.line(&source)
## Up to `maximum` bytes, or all the rest with a negative maximum; empty at the end. The
## view lasts until the next read.
pub func read_bytes(maximum: i64 = -1) -> const u8[]!:
var source = Descriptor(handle = self.handle else error(io.closed, "the file is closed"))
return try self.ahead.bytes(&source, read_limit(maximum), true)
## Up to `maximum` bytes as text, or all the rest with a negative maximum, ending on a
## whole character; empty at the end. Text that is not UTF-8 is invalid_text.
pub func read_text(maximum: i64 = -1) -> str!:
var source = Descriptor(handle = self.handle else error(io.closed, "the file is closed"))
return try self.ahead.text(&source, read_limit(maximum), true)
## Write all of `data`.
pub func write_bytes(data: const u8[]) -> !:
try io.write_all(&self, data)
## Write all of `text`.
pub func write_text(text: str) -> !:
try io.write_all(&self, text.bytes)
## Consume ownership before closing, so repeated calls on this value are safe
## even after failure. Never retry close: a reused descriptor may belong to
## another thread. A reported failure must not be retried using descriptor().
pub func close() -> !:
let fd = self.handle else return
self.handle = none
self.ahead.release()
if close(fd) != 0:
error(classify_error(c.errno()), "the file could not be closed")
## Best-effort cleanup while unwinding another error. Use close explicitly on
## the successful path when delayed close errors must be reported to the caller.
pub func destroy():
self.close() catch failure:
_ = failure
## Open `path` as a File object for Luce: `files.open("notes.txt")` reads, and a mode
## such as `files.OpenMode.replace` or `.append` writes. It closes with `with` or `close()`.
## Base programs use `File.open`, which answers the File as a value.
pub func open(path: c.str, mode: OpenMode = OpenMode.read, permissions: u32 = 420) -> interop.Reference[File]!:
var reservation = try interop.Reservation[File](file_type)
errdefer reservation.cancel()
var opened = try File.open(path, mode, permissions)
let native = new File(handle = opened.handle) catch failure:
opened.destroy()
error(failure.code, failure.message)
return reservation.publish(native)
## The interop type of an open file.
pub let file_type: interop.Type[File] = interop.Type[File]("File", File.destroy, closeable = true)
## The text read is not valid UTF-8.
pub let invalid_text: ErrorCode = readahead.invalid_text
## A descriptor read directly, under the file's read-ahead bytes.
struct Descriptor: io.Reader:
var handle: i32
func read(buffer: u8[]) -> usize!:
return try read_descriptor(self.handle, buffer)
## Read some bytes, retrying interruption; zero at the end.
func read_descriptor(fd: i32, buffer: u8[]) -> usize!:
if buffer.length == 0:
return 0
let count = buffer.length if buffer.length < transfer_limit else transfer_limit
var received = c_read(fd, buffer.data, count)
while received < 0 and c.errno() == c.interrupted:
received = c_read(fd, buffer.data, count)
if received < 0:
error(classify_error(c.errno()), "the file could not be read")
return (usize)received
## A Luce read maximum: a negative one is everything.
func read_limit(maximum: i64) -> usize:
return ~(usize)0 if maximum < 0 else (usize)maximum
func classify_error(number: i32) -> ErrorCode:
if number == 2:
return missing
if number == 1 or number == 13:
return permission_denied
if number == 17:
return already_exists
if number == 28:
return no_space
if number == 20:
return not_directory
if number == 21:
return is_directory
if number == 30:
return read_only_filesystem
# the UCRT numbers its errors its own way: `ENOTEMPTY` 41, `ENAMETOOLONG` 38, no `ELOOP`
if number == (66 if platform.macos else (41 if platform.windows else 39)):
return not_empty
if number == 18:
return cross_device
if number == (62 if platform.macos else 40) and not platform.windows:
return symlink_loop
if number == (63 if platform.macos else (38 if platform.windows else 36)):
return name_too_long
if number == would_block_errno:
return would_block
return failed
## Shared mode validation for path-based and directory-relative file opening.
func open_descriptor(path: c.str, flags: i32, permissions: u32, temporary: bool = false) -> i32!:
if platform.windows:
return try windows_open(path, flags, permissions, delete_on_close = temporary)
else:
return posix_open(path, flags, permissions)
## A temporary file's name goes once it is open (POSIX); Windows deletes it when
## its last handle closes, so the name stays until then.
func forget_name(path: c.str, opened: File*) -> !:
if platform.windows:
return
else:
remove_file(path) catch failure:
opened.destroy()
error(failure.code, failure.message)
func file_open_flags(mode: OpenMode, permissions: u32) -> i32!:
if permissions > 4095:
error(invalid_options, "file permissions must fit the Unix mode bits")
var flags = close_on_exec
if platform.windows:
flags |= 32768
if mode == OpenMode.read:
flags |= read_only_flag
elif mode == OpenMode.read_write:
flags |= read_write_flag
elif mode == OpenMode.replace:
flags |= write_only | create | truncate
elif mode == OpenMode.create_new or mode == OpenMode.create_new_read_write:
flags |= create | exclusive_flag | (read_write_flag if mode == OpenMode.create_new_read_write else write_only)
elif mode == OpenMode.append:
flags |= write_only | create | append_flag
elif mode != OpenMode.read:
error(invalid_options, "unknown file opening mode")
return flags