core.os

FileHandle : struct {
    value : RawPtr
    valid : bool = false
}

DirectoryHandle : struct {
    value : RawPtr
    valid : bool = false
}

OsFileInfo : struct {
    kind : OsFileKind
    size : i64 = -1
}

OsDirectoryEntry : struct {
    // Borrowed until the next read_dir call on the same handle, or close_dir.
    name : cstring
    name_length : i64
    kind : OsFileKind
}

sleep_ms : func(milliseconds : u64) -> void

Suspends the current thread for approximately the requested duration.

Parameters:
  milliseconds - duration to sleep, expressed in milliseconds.

Returns:
  void

Notes:
  - Long sleeps are split into one-second chunks to keep the POSIX
    microsecond argument in range.

file_exists : func(path : string) -> bool

Reports whether a filesystem path exists.

Parameters:
  path - path to query.

Returns:
  bool - true if the path exists and is visible to the current process;
         false otherwise.

Notes:
  - Permission or metadata-query failures are reported as false.

file_info : func(path : string) -> [OsFileInfo, OsStatus]

file_info_no_follow : func(path : string) -> [OsFileInfo, OsStatus]

Returns metadata for the path entry itself without following a link.
DirectoryLink is used when Windows reports both directory and reparse-point
attributes; Darwin symbolic links are reported as SymbolicLink.

file_info : func(handle : ^FileHandle) -> [OsFileInfo, OsStatus]

open_file : func(path : string, mode : OsFileMode) -> [FileHandle, OsStatus]

close_file : func(handle : ^FileHandle) -> OsStatus

read_file : func(handle : ^FileHandle, buffer : RawPtr, count : i64) -> [i64, OsStatus]

write_file : func(handle : ^FileHandle, buffer : RawPtr, count : i64) -> [i64, OsStatus]

seek_file : func(handle : ^FileHandle, offset : i64, origin : OsSeekOrigin) -> [i64, OsStatus]

same_file : func(first : ^FileHandle, second : ^FileHandle) -> [bool, OsStatus]

Compares stable identities for two already-open handles.
Path names are deliberately not consulted, avoiding rename and hard-link
races between a comparison and a destructive operation.

truncate_file : func(handle : ^FileHandle, length : i64) -> OsStatus

Changes the length of an already-open writable file.

create_dir : func(path : string) -> OsStatus

remove_dir : func(path : string) -> OsStatus

open_dir : func(path : string) -> [DirectoryHandle, OsStatus]

read_dir : func(handle : ^DirectoryHandle) -> [OsDirectoryEntry, bool, OsStatus]

close_dir : func(handle : ^DirectoryHandle) -> OsStatus

remove_file : func(path : string) -> OsStatus

Removes a file at path.

Parameters:
  path - file path to remove.

Returns:
  OsStatus.Ok            - file was removed.
  OsStatus.FileNotFound  - path does not exist.
  OsStatus.InternalError - platform removal failed.

Notes:
  - Directory removal is not supported by this helper.

rename_file : func(from : string, to : string) -> OsStatus

Renames or moves a file from one path to another.

Parameters:
  from - existing source path.
  to   - destination path.

Returns:
  OsStatus.Ok            - file was renamed or moved.
  OsStatus.FileNotFound  - source path does not exist.
  OsStatus.InternalError - platform rename failed.

current_dir : func(allocator : ^Allocator) -> [string, OsStatus]

Returns the process current working directory.

Parameters:
  allocator - allocator used for the returned string buffer.

Returns:
  [string, OsStatus] - current directory and status.
                      On success, status is OsStatus.Ok.
                      On failure, string is empty and status is:
                        OsStatus.InvalidAllocator - allocator was null.
                        OsStatus.AllocatorFailed  - allocation failed.
                        OsStatus.InternalError    - platform query failed.

Notes:
  - The returned string owns allocator-backed memory.
  - The fixed internal buffer size is 4096 bytes.

set_current_dir : func(path : string) -> OsStatus

Changes the process current working directory.

Parameters:
  path - target directory path.

Returns:
  OsStatus.Ok            - current directory was changed.
  OsStatus.FileNotFound  - target path does not exist.
  OsStatus.InternalError - platform chdir failed.