package core:os/os2
Source

⌘K
Ctrl+K
or
/

    Overview

    Package os provides a platform-independent interface to operating system functionality. The design is UNIX-like but with Odin-like error handling. Failing calls return values with a specific error type rather than error number.

    The package os interface is intended to be uniform across all operating systems. Features not generally available appear in the system-specific packages under core:sys/*.

    IMPORTANT NOTE from Bill: this is purely a mockup of what I want the new package os to be, and NON-FUNCTIONING. It is not complete but should give designers a better idea of the general interface and how to write things. This entire interface is subject to change.

    Index

    Variables (4)
    Procedures (167)

    Types

    Error ¶
    Source

    Error :: union {
	General_Error, 
	io.Error, 
	runtime.Allocator_Error, 
	sys_windows.System_Error, 
}
     

    Error is a union of different classes of errors that could be returned from procedures in this package.

    Related Procedures With Parameters
    Related Procedures With Returns
    Related Constants

    File ¶
    Source

    File :: struct {
	impl:   rawptr,
	stream: io.Stream,
	fstat:  Fstat_Callback,
}
     

    Type representing a file handle.

    This struct represents an OS-specific file-handle, which can be one of the following: File Directory Pipe Named pipe Block Device Character device Symlink Socket

    See File_Type enum for more information on file types.

    Related Procedures With Parameters
    Related Procedures With Returns

    File_Flag ¶
    Source

    File_Flag :: enum int {
	Read, 
	Write, 
	Append, 
	Create, 
	Excl, 
	Sync, 
	Trunc, 
	Sparse, 
	Inheritable, 
	Unbuffered_IO, 
}

    File_Flags ¶
    Source

    File_Flags :: distinct bit_set[File_Flag; uint]
     

    Represents the file flags for a file handle

    Related Procedures With Parameters
    Related Constants

    File_Info ¶
    Source

    File_Info :: struct {
	fullpath:          string,
	// fullpath of the file
	name:              string,
	// base name of the file
	inode:             u128,
	// might be zero if cannot be determined
	size:              i64 `fmt:"M"`,
	// length in bytes for regular files; system-dependent for other file types
	mode:              Permissions,
	// file permission flags
	type:              File_Type,
	creation_time:     time.Time,
	modification_time: time.Time,
	access_time:       time.Time,
}
     

    File_Info describes a file and is returned from stat, fstat, and lstat.

    Related Procedures With Parameters
    Related Procedures With Returns

    File_Type ¶
    Source

    File_Type :: enum int {
	// The type of a file could not be determined for the current platform.
	Undetermined, 
	// Represents a regular file.
	Regular, 
	// Represents a directory.
	Directory, 
	// Represents a symbolic link.
	Symlink, 
	// Represents a named pipe (FIFO).
	Named_Pipe, 
	// Represents a socket.
	// **Note(windows)**: Not returned on windows
	Socket, 
	// Represents a block device.
	// **Note(windows)**: On windows represents all devices.
	Block_Device, 
	// Represents a character device.
	// **Note(windows)**: Not returned on windows
	Character_Device, 
}
     

    Type representing the type of a file handle.

    Note(windows): Socket handles can not be distinguished from files, as they are just a normal file handle that is being treated by a special driver. Windows also makes no distinction between block and character devices.

    Fstat_Callback ¶
    Source

    Fstat_Callback :: proc(f: ^File, allocator: runtime.Allocator) -> (File_Info, Error)

    General_Error ¶
    Source

    General_Error :: enum u32 {
	None, 
	Exist, 
	Not_Exist, 
	Timeout, 
	Broken_Pipe, 
	Invalid_File, 
	Invalid_Dir, 
	Invalid_Path, 
	Invalid_Callback, 
	Invalid_Command, 
	Pattern_Has_Separator, 
	No_HOME_Variable, 
	Env_Var_Not_Found, 
}
     

    General errors that are common within this package which cannot be categorized by io.Error nor runtime.Allocator_Error.

    Permission_Flag ¶
    Source

    Permission_Flag :: enum u32 {
	Execute_Other = 0, 
	Write_Other   = 1, 
	Read_Other    = 2, 
	Execute_Group = 3, 
	Write_Group   = 4, 
	Read_Group    = 5, 
	Execute_User  = 6, 
	Write_User    = 7, 
	Read_User     = 8, 
}

    Permissions ¶
    Source

    Permissions :: distinct bit_set[Permission_Flag; u32]
    Related Procedures With Parameters
    Related Procedures With Returns
    Related Constants

    Platform_Error ¶
    Source

    Platform_Error :: sys_windows.System_Error
     

    A platform specific error

    Process ¶
    Source

    Process :: struct {
	pid:    int,
	handle: uintptr,
}
     

    Represents a process handle.

    When a process dies, the OS is free to re-use the pid of that process. The Process struct represents a handle to the process that will refer to a specific process, even after it has died.

    Note(linux): The handle will be referring to pidfd.

    Related Procedures With Parameters
    Related Procedures With Returns

    Process_Desc ¶
    Source

    Process_Desc :: struct {
	// The working directory of the process. If the string has length 0, the
	// working directory is assumed to be the current working directory of the
	// current process.
	working_dir: string,
	// The command to run. Each element of the slice is a separate argument to
	// the process. The first element of the slice would be the executable.
	command:     []string,
	// A slice of strings, each having the format `KEY=VALUE` representing the
	// full environment that the child process will receive.
	// In case this slice is `nil`, the current process' environment is used.
	// NOTE(laytan): maybe should be `Maybe([]string)` so you can do `nil` == current env, empty == empty/no env.
	env:         []string,
	// The `stderr` handle to give to the child process. It can be either a file
	// or a writeable end of a pipe. Passing `nil` will shut down the process'
	// stderr output.
	stderr:      ^File,
	// The `stdout` handle to give to the child process. It can be either a file
	// or a writeabe end of a pipe. Passing a `nil` will shut down the process'
	// stdout output.
	stdout:      ^File,
	// The `stdin` handle to give to the child process. It can either be a file
	// or a readable end of a pipe. Passing a `nil` will shut down the process'
	// input.
	stdin:       ^File,
}
     

    The description of how a process should be created.

    Related Procedures With Parameters

    Process_Info ¶
    Source

    Process_Info :: struct {
	// The information about a process the struct contains. `pid` is always
	// stored, no matter what.
	fields:          bit_set[Process_Info_Field],
	// The ID of the process.
	pid:             int,
	// The ID of the parent process.
	ppid:            int,
	// The process priority.
	priority:        int,
	// The path to the executable, which the process runs.
	executable_path: string,
	// The command line supplied to the process.
	command_line:    string,
	// The arguments supplied to the process.
	command_args:    []string,
	// The environment of the process.
	environment:     []string,
	// The username of the user who started the process.
	username:        string,
	// The current working directory of the process.
	working_dir:     string,
}
     

    Contains information about the process as obtained by the process_info() procedure.

    Related Procedures With Parameters
    Related Procedures With Returns

    Process_Info_Field ¶
    Source

    Process_Info_Field :: enum int {
	Executable_Path, 
	PPid, 
	Priority, 
	Command_Line, 
	Command_Args, 
	Environment, 
	Username, 
	Working_Dir, 
}

    Process_Info_Fields ¶
    Source

    Process_Info_Fields :: bit_set[Process_Info_Field]
     

    Bit set specifying which fields of the Process_Info struct need to be obtained by the process_info() procedure. Each bit corresponds to a field in the Process_Info struct.

    Related Procedures With Parameters
    Related Constants

    Process_Open_Flag ¶
    Source

    Process_Open_Flag :: enum int {
	// Request for reading from the virtual memory of another process.
	Mem_Read, 
	// Request for writing to the virtual memory of another process.
	Mem_Write, 
}

    Process_Open_Flags ¶
    Source

    Process_Open_Flags :: bit_set[Process_Open_Flag]
    Related Procedures With Parameters

    Process_State ¶
    Source

    Process_State :: struct {
	// The ID of the process.
	pid:         int,
	// Specifies whether the process has terminated or is still running.
	exited:      bool,
	// The exit code of the process, if it has exited.
	// Will also store the number of the exception or signal that has crashed the
	// process.
	exit_code:   int,
	// Specifies whether the termination of the process was successfull or not,
	// i.e. whether it has crashed or not.
	// **Note(windows)**: On windows `true` is always returned, as there is no
	// reliable way to obtain information about whether the process has crashed.
	success:     bool,
	// The time the process has spend executing in kernel time.
	system_time: time.Duration,
	// The time the process has spend executing in userspace.
	user_time:   time.Duration,
}
     

    The state of the process after it has finished execution.

    Related Procedures With Returns

    Read_Directory_Iterator ¶
    Source

    Read_Directory_Iterator :: struct {
	f:     ^File,
	err:   struct {
		err:  Error,
		path: [dynamic]u8,
	},
	index: int,
	impl:  Read_Directory_Iterator_Impl,
}
    Related Procedures With Parameters
    Related Procedures With Returns

    Walker ¶
    Source

    Walker :: struct {
	todo:     container_queue.Queue($T=string),
	skip_dir: bool,
	err:      struct {
		path: [dynamic]u8,
		err:  Error,
	},
	iter:     Read_Directory_Iterator,
}
     

    A recursive directory walker.

    Note that none of the fields should be accessed directly.

    Related Procedures With Parameters
    Related Procedures With Returns

    Constants

    ALL_INFO ¶
    Source

    ALL_INFO: bit_set[Process_Info_Field] : Process_Info_Fields{.Executable_Path, .PPid, .Priority, .Command_Line, .Command_Args, .Environment, .Username, .Working_Dir}

    ERROR_NONE ¶
    Source

    ERROR_NONE :: Error{}

    O_APPEND ¶
    Source

    O_APPEND :: File_Flags{.Append}

    O_CREATE ¶
    Source

    O_CREATE :: File_Flags{.Create}

    O_EXCL ¶
    Source

    O_EXCL :: File_Flags{.Excl}

    O_INHERITABLE ¶
    Source

    O_INHERITABLE :: File_Flags{.Inheritable}
     

    If specified, the file handle is inherited upon the creation of a child process. By default all handles are created non-inheritable.

    Note: The standard file handles (stderr, stdout and stdin) are always initialized as inheritable.

    O_RDONLY ¶
    Source

    O_RDONLY :: File_Flags{.Read}

    O_RDWR ¶
    Source

    O_RDWR :: File_Flags{.Read, .Write}

    O_SPARSE ¶
    Source

    O_SPARSE :: File_Flags{.Sparse}

    O_SYNC ¶
    Source

    O_SYNC :: File_Flags{.Sync}

    O_TRUNC ¶
    Source

    O_TRUNC :: File_Flags{.Trunc}

    O_WRONLY ¶
    Source

    O_WRONLY :: File_Flags{.Write}

    Path_List_Separator ¶
    Source

    Path_List_Separator :: _Path_List_Separator
     

    OS-Specific

    Path_Separator ¶
    Source

    Path_Separator :: _Path_Separator
     

    OS-Specific

    Path_Separator_String ¶
    Source

    Path_Separator_String: string : _Path_Separator_String
     

    OS-Specific

    Permissions_All ¶
    Source

    Permissions_All :: Permissions_Read_All + Permissions_Write_All + Permissions_Execute_All

    Permissions_Default ¶
    Source

    Permissions_Default :: Permissions_Default_Directory

    Permissions_Default_Directory ¶
    Source

    Permissions_Default_Directory :: Permissions_Read_All + Permissions_Write_All + Permissions_Execute_All

    Permissions_Default_File ¶
    Source

    Permissions_Default_File :: Permissions_Read_All + Permissions_Write_All

    Permissions_Execute_All ¶
    Source

    Permissions_Execute_All :: Permissions{.Execute_User, .Execute_Group, .Execute_Other}

    Permissions_Read_All ¶
    Source

    Permissions_Read_All :: Permissions{.Read_User, .Read_Group, .Read_Other}

    Permissions_Read_Write_All ¶
    Source

    Permissions_Read_Write_All :: Permissions_Read_All + Permissions_Write_All

    Permissions_Write_All ¶
    Source

    Permissions_Write_All :: Permissions{.Write_User, .Write_Group, .Write_Other}

    TIMEOUT_INFINITE ¶
    Source

    TIMEOUT_INFINITE: time.Duration : time.MIN_DURATION
     

    In procedures that explicitly state this as one of the allowed values, specifies an infinite timeout.

    Variables

    args ¶
    Source

    args: []string = …
     

    Arguments to the current process.

    stderr ¶
    Source

    stderr: ^File = …
     

    stderr is an open file pointing to the standard error file stream

    stdin ¶
    Source

    stdin: ^File = …
     

    stdin is an open file pointing to the standard input file stream

    stdout ¶
    Source

    stdout: ^File = …
     

    stdout is an open file pointing to the standard output file stream

    Procedures

    are_paths_identical ¶
    Source

    are_paths_identical :: proc(a, b: string) -> (identical: bool) {…}
     

    Compare two paths for exactness without normalization.

    This procedure takes into account case-sensitivity on differing systems.

    change_directory ¶
    Source

    change_directory :: proc(name: string) -> Error {…}
     

    Changes the current working directory to the named directory.

    change_mode ¶
    Source

    change_mode :: proc(name: string, mode: Permissions) -> Error {…}
     

    Changes the mode/permissions of the named file to mode. If the file is a symbolic link, it changes the mode of the link's target.

    On Windows, only {.Write_User} of mode is used, and controls whether or not the file has a read-only attribute. Use {.Read_User} for a read-only file and {.Read_User, .Write_User} for a readable & writable file.

    change_owner ¶
    Source

    change_owner :: proc(name: string, uid, gid: int) -> Error {…}
     

    Changes the numeric uid and gid of a named file. If the file is a symbolic link, it changes the uid and gid of the link's target.

    On Windows, it always returns an error.

    change_owner_do_not_follow_links :: proc(name: string, uid, gid: int) -> Error {…}
     

    Changes the numeric uid and gid of the file f. If the file is a symbolic link, it changes the uid and gid of the lin itself.

    On Windows, it always returns an error.

    change_times ¶
    Source

    change_times :: proc(name: string, atime, mtime: time.Time) -> Error {…}
     

    Changes the access atime and modification mtime times of a named file.

    chdir ¶
    Source

    chdir :: change_directory
     

    Changes the current working directory to the named directory.

    chmod ¶
    Source

    chmod :: change_mode
     

    Changes the mode/permissions of the named file to mode. If the file is a symbolic link, it changes the mode of the link's target.

    On Windows, only {.Write_User} of mode is used, and controls whether or not the file has a read-only attribute. Use {.Read_User} for a read-only file and {.Read_User, .Write_User} for a readable & writable file.

    chown ¶
    Source

    chown :: change_owner
     

    Changes the numeric uid and gid of a named file. If the file is a symbolic link, it changes the uid and gid of the link's target.

    On Windows, it always returns an error.

    chtimes ¶
    Source

    chtimes :: change_times
     

    Changes the access atime and modification mtime times of a named file.

    clean_path ¶
    Source

    clean_path :: proc(path: string, allocator: runtime.Allocator) -> (cleaned: string, err: Error) {…}
     

    Normalize a path.

    Allocates Using Provided Allocator

    This will remove duplicate separators and unneeded references to the current or parent directory.

    clear_env ¶
    Source

    clear_env :: proc() {…}

    clone ¶
    Source

    clone :: proc(f: ^File) -> (^File, Error) {…}
     

    clone returns a new ^File based on the passed file f with the same underlying file descriptor.

    close ¶
    Source

    close :: proc(f: ^File) -> Error {…}
     

    Close a file and its stream.

    Any further use of the file or its stream should be considered to be in the same class of bugs as a use-after-free.

    copy_directory_all ¶
    Source

    copy_directory_all :: proc(dst, src: string, dst_perm: int = 0o755) -> Error {…}
     

    Recursively copies a directory to dst from src

    copy_file ¶
    Source

    copy_file :: proc(dst_path, src_path: string) -> Error {…}
     

    copy_file copies a file from src_path to dst_path and returns an error if any was encountered.

    create ¶
    Source

    create :: proc(name: string) -> (^File, Error) {…}
     

    create creates or truncates a named file name. If the file already exists, it is truncated. If the file does not exist, it is created with the Permissions_Default_File permissions. If successful, a ^File is return which can be used for I/O. And error is returned if any is encountered.

    create_temp_file ¶
    Source

    create_temp_file :: proc(dir, pattern: string) -> (f: ^File, err: Error) {…}
     

    Creates a new temperatory file in the directory dir.

    Opens the file for reading and writing, with Permissions_Read_Write_All permissions, and returns the new ^File. The filename is generated by taking a pattern, and adding a randomized string to the end. If the pattern includes an "", the random string replaces the last "". If dir is an empty string, temp_directory() will be used.

    The caller must close the file once finished with.

    current_process_info ¶
    Source

    current_process_info :: proc(selection: bit_set[Process_Info_Field], allocator: runtime.Allocator) -> (Process_Info, Error) {…}
     

    Obtain information about the current process.

    This procedure obtains the information, specified by selection parameter about the currently running process.

    Use free_process_info to free the memory allocated by this procedure. The free_process_info procedure needs to be called, even if this procedure returned an error, as some of the fields may have been allocated.

    Note: The resulting information may or may contain the fields specified by the selection parameter. Always check whether the returned Process_Info struct has the required fields before checking the error code returned by this procedure.

    Related Procedure Groups

    environ ¶
    Source

    environ :: proc(allocator: runtime.Allocator) -> ([]string, Error) {…}
     

    environ returns a copy of strings representing the environment, in the form "key=value" NOTE: the slice of strings and the strings with be allocated using the supplied allocator

    error_string ¶
    Source

    error_string :: proc(ferr: Error) -> string {…}
     

    Attempts to return the error ferr as a string without any allocation

    exists ¶
    Source

    exists :: proc(path: string) -> bool {…}
     

    exists returns whether or not a named file exists.

    exit ¶
    Source

    exit :: proc "contextless" (code: int) -> ! {…}
     

    Exit the current process.

    fchange_directory ¶
    Source

    fchange_directory :: proc(f: ^File) -> Error {…}
     

    Changes the current working directory to the file, which must be a directory.

    fchange_mode ¶
    Source

    fchange_mode :: proc(f: ^File, mode: Permissions) -> Error {…}
     

    Changes the current mode permissions of the file f.

    fchange_owner ¶
    Source

    fchange_owner :: proc(f: ^File, uid, gid: int) -> Error {…}
     

    Changes the numeric uid and gid of the file f. If the file is a symbolic link, it changes the uid and gid of the link's target.

    On Windows, it always returns an error.

    fchange_times ¶
    Source

    fchange_times :: proc(f: ^File, atime, mtime: time.Time) -> Error {…}
     

    Changes the access atime and modification mtime times of the file f.

    fchdir ¶
    Source

    fchdir :: fchange_directory
     

    Changes the current working directory to the file, which must be a directory.

    fchmod ¶
    Source

    fchmod :: fchange_mode
     

    Changes the current mode permissions of the file f.

    fchown ¶
    Source

    fchown :: fchange_owner
     

    Changes the numeric uid and gid of the file f. If the file is a symbolic link, it changes the uid and gid of the link's target.

    On Windows, it always returns an error.

    fchtimes ¶
    Source

    fchtimes :: fchange_times
     

    Changes the access atime and modification mtime times of the file f.

    fd ¶
    Source

    fd :: proc(f: ^File) -> uintptr {…}
     

    fd returns the file descriptor of the file f passed. If the file is not valid, an invalid handle will be returned.

    file_info_clone ¶
    Source

    file_info_clone :: proc(fi: File_Info, allocator: runtime.Allocator) -> (cloned: File_Info, err: runtime.Allocator_Error) {…}

    file_info_delete ¶
    Source

    file_info_delete :: proc(fi: File_Info, allocator: runtime.Allocator) {…}

    file_info_slice_delete ¶
    Source

    file_info_slice_delete :: proc(infos: []File_Info, allocator: runtime.Allocator) {…}

    file_size ¶
    Source

    file_size :: proc(f: ^File) -> (n: i64, err: Error) {…}
     

    file_size returns the length of the file f in bytes and an error, if any is encountered.

    flush ¶
    Source

    flush :: proc(f: ^File) -> Error {…}
     

    flush flushes a file f

    free_process_info ¶
    Source

    free_process_info :: proc(pi: Process_Info, allocator: runtime.Allocator) {…}
     

    Free the information about the process.

    This procedure frees the memory occupied by process info using the provided allocator. The allocator needs to be the same allocator that was supplied to the process_info function.

    fstat ¶
    Source

    fstat :: proc(f: ^File, allocator: runtime.Allocator) -> (File_Info, Error) {…}

    get_absolute_path ¶
    Source

    get_absolute_path :: proc(path: string, allocator: runtime.Allocator) -> (absolute_path: string, err: Error) {…}
     

    Get the absolute path to path with respect to the process's current directory.

    Allocates Using Provided Allocator

    get_egid ¶
    Source

    get_egid :: proc() -> int {…}
     

    Obtain the effective GID of the current process.

    The effective GID is typically the same as the GID of the process. In case the process was run by a user with elevated permissions, the process may lower the privilege to perform some tasks without privilege. In these cases the real GID of the process and the effective GID are different.

    Note(windows): Windows doesn't follow the posix permissions model, so the function simply returns -1.

    get_env_alloc ¶
    Source

    get_env_alloc :: proc(key: string, allocator: runtime.Allocator) -> string {…}
     

    get_env retrieves the value of the environment variable named by the key It returns the value, which will be empty if the variable is not present To distinguish between an empty value and an unset value, use lookup_env NOTE: the value will be allocated with the supplied allocator

    Related Procedure Groups

    get_env_buf ¶
    Source

    get_env_buf :: proc(buf: []u8, key: string) -> string {…}
     

    get_env retrieves the value of the environment variable named by the key It returns the value, which will be empty if the variable is not present To distinguish between an empty value and an unset value, use lookup_env NOTE: this version takes a backing buffer for the string value

    Related Procedure Groups

    get_euid ¶
    Source

    get_euid :: proc() -> int {…}
     

    Obtain the effective UID of the current process.

    The effective UID is typically the same as the UID of the process. In case the process was run by a user with elevated permissions, the process may lower the privilege to perform some tasks without privilege. In these cases the real UID of the process and the effective UID are different.

    Note(windows): Windows doesn't follow the posix permissions model, so the function simply returns -1.

    get_executable_directory ¶
    Source

    get_executable_directory :: proc(allocator: runtime.Allocator) -> (path: string, err: Error) {…}
     

    Get the directory for the currently running executable.

    Allocates Using Provided Allocator

    get_executable_path ¶
    Source

    get_executable_path :: proc(allocator: runtime.Allocator) -> (path: string, err: Error) {…}
     

    Get the path for the currently running executable.

    Allocates Using Provided Allocator

    get_gid ¶
    Source

    get_gid :: proc() -> int {…}
     

    Obtain the GID of the current process.

    Note(windows): Windows doesn't follow the posix permissions model, so the function simply returns -1.

    get_pid ¶
    Source

    get_pid :: proc() -> int {…}
     

    Obtain the ID of the current process.

    get_ppid ¶
    Source

    get_ppid :: proc() -> int {…}
     

    Obtain the ID of the parent process.

    Note(windows): Windows does not mantain strong relationships between parent and child processes. This function returns the ID of the process that has created the current process. In case the parent has died, the ID returned by this function can identify a non-existent or a different process.

    get_relative_path ¶
    Source

    get_relative_path :: proc(base, target: string, allocator: runtime.Allocator) -> (path: string, err: Error) {…}
     

    Get the relative path needed to change directories from base to target.

    Allocates Using Provided Allocator

    The result is such that join_path(base, get_relative_path(base, target)) is equivalent to target.

    NOTE: This procedure expects both base and target to be normalized first, which can be done by calling clean_path on them if needed.

    This procedure will return an Invalid_Path error if base begins with a reference to the parent directory (".."). Use get_working_directory with join_path to construct absolute paths for both arguments instead.

    get_uid ¶
    Source

    get_uid :: proc() -> int {…}
     

    Obtain the UID of the current process.

    Note(windows): Windows doesn't follow the posix permissions model, so the function simply returns -1.

    get_working_directory ¶
    Source

    get_working_directory :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {…}
     

    Get the working directory of the current process.

    Allocates Using Provided Allocator

    getwd ¶
    Source

     

    Get the working directory of the current process.

    Allocates Using Provided Allocator

    heap_allocator ¶
    Source

    heap_allocator :: proc() -> runtime.Allocator {…}
     

    Returns the default heap_allocator for this specific platform.

    heap_allocator_proc ¶
    Source

    heap_allocator_proc :: proc(
	allocator_data:  rawptr, 
	mode:            runtime.Allocator_Mode, 
	size, alignment: int, 
	old_memory:      rawptr, 
	old_size:        int, 
	loc := #caller_location, 
) -> ([]u8, runtime.Allocator_Error) {…}

    is_absolute_path ¶
    Source

    is_absolute_path :: proc(path: string) -> bool {…}
     

    Return true if path is an absolute path as opposed to a relative one.

    is_dir ¶
    Source

    is_dir :: is_directory
     

    Returns whether or not the type of a named file is a File_Type.Directory file.

    is_directory ¶
    Source

    is_directory :: proc(path: string) -> bool {…}
     

    Returns whether or not the type of a named file is a File_Type.Directory file.

    is_file ¶
    Source

    is_file :: proc(path: string) -> bool {…}
     

    is_file returns whether or not the type of a named file is a File_Type.Regular file.

    is_path_separator ¶
    Source

    is_path_separator :: proc(c: u8) -> bool {…}
     

    Return true if c is a character used to separate paths into directory and file hierarchies on the current system.

    is_platform_error ¶
    Source

    is_platform_error :: proc(ferr: Error) -> (err: i32, ok: bool) {…}
     

    Attempts to convert an Error into a platform specific error as an integer. ok is false if not possible

    join_filename ¶
    Source

    join_filename :: proc(base: string, ext: string, allocator: runtime.Allocator) -> (joined: string, err: Error) {…}
     

    Join base and ext with the system's filename extension separator.

    Allocates Using Provided Allocator

    For example, join_filename("foo", "tar.gz") will result in "foo.tar.gz".

    join_path ¶
    Source

    join_path :: proc(elems: []string, allocator: runtime.Allocator) -> (joined: string, err: Error) {…}
     

    Join all elems with the system's path separator and normalize the result.

    Allocates Using Provided Allocator

    For example, join_path({"/home", "foo", "bar.txt"}) will result in "/home/foo/bar.txt".

    last_write_time ¶
    Source

    last_write_time :: modification_time
     

    Returns the modification time of the file f. The resolution of the timestamp is system-dependent.

    last_write_time_by_name ¶
    Source

    last_write_time_by_name :: modification_time_by_path
     

    Returns the modification time of the named file path. The resolution of the timestamp is system-dependent.

    lchown ¶
    Source

     

    Changes the numeric uid and gid of the file f. If the file is a symbolic link, it changes the uid and gid of the lin itself.

    On Windows, it always returns an error.

    link :: proc(old_name, new_name: string) -> Error {…}
     

    link creates a new_name as a hard link to the old_name file.

    lookup_env_alloc ¶
    Source

    lookup_env_alloc :: proc(key: string, allocator: runtime.Allocator) -> (value: string, found: bool) {…}
     

    lookup_env gets the value of the environment variable named by the key If the variable is found in the environment the value (which can be empty) is returned and the boolean is true Otherwise the returned value will be empty and the boolean will be false NOTE: the value will be allocated with the supplied allocator

    Related Procedure Groups

    lookup_env_buf ¶
    Source

    lookup_env_buf :: proc(buf: []u8, key: string) -> (value: string, err: Error) {…}
     

    This version of lookup_env doesn't allocate and instead requires the user to provide a buffer. Note that it is limited to environment names and values of 512 utf-16 values each due to the necessary utf-8 <> utf-16 conversion.

    Related Procedure Groups

    lstat ¶
    Source

     

    Returns a File_Info describing the named file from the file system. If the file is a symbolic link, the File_Info returns describes the symbolic link, rather than following the link. The resulting File_Info must be deleted with file_info_delete.

    make_directory ¶
    Source

    make_directory :: proc(name: string, perm: int = 0o755) -> Error {…}
     

    Make a new directory.

    If path is relative, it will be relative to the process's current working directory.

    make_directory_all ¶
    Source

    make_directory_all :: proc(path: string, perm: int = 0o755) -> Error {…}
     

    Make a new directory, creating new intervening directories when needed.

    If path is relative, it will be relative to the process's current working directory.

    make_directory_temp ¶
    Source

    make_directory_temp :: proc(dir, pattern: string, allocator: runtime.Allocator) -> (temp_path: string, err: Error) {…}
     

    Creates a new temporary directory in the directory dir, and returns the path of the new directory.

    The directory name is generated by taking a pattern, and adding a randomized string to the end. If the pattern includes an "", the random string replaces the last "". If dir is an empty tring, temp_directory() will be used.

    mkdir ¶
    Source

    mkdir :: make_directory
     

    Make a new directory.

    If path is relative, it will be relative to the process's current working directory.

    mkdir_all ¶
    Source

    mkdir_all :: make_directory_all
     

    Make a new directory, creating new intervening directories when needed.

    If path is relative, it will be relative to the process's current working directory.

    mkdir_temp ¶
    Source

    mkdir_temp :: make_directory_temp
     

    Creates a new temporary directory in the directory dir, and returns the path of the new directory.

    The directory name is generated by taking a pattern, and adding a randomized string to the end. If the pattern includes an "", the random string replaces the last "". If dir is an empty tring, temp_directory() will be used.

    modification_time ¶
    Source

    modification_time :: proc(f: ^File) -> (time.Time, Error) {…}
     

    Returns the modification time of the file f. The resolution of the timestamp is system-dependent.

    modification_time_by_path ¶
    Source

    modification_time_by_path :: proc(path: string) -> (time.Time, Error) {…}
     

    Returns the modification time of the named file path. The resolution of the timestamp is system-dependent.

    name ¶
    Source

    name :: proc(f: ^File) -> string {…}
     

    name returns the name of the file. The lifetime of this string lasts as long as the file handle itself.

    new_file ¶
    Source

    new_file :: proc(handle: uintptr, name: string) -> ^File {…}
     

    new_file returns a new ^File with the given file descriptor handle and name. The return value will only be nil IF the handle is not a valid file descriptor.

    open ¶
    Source

    open :: proc(name: string, flags: File_Flags = File_Flags{.Read}, perm: Permissions = Permissions_Default) -> (^File, Error) {…}
     

    open is a generalized open call, which defaults to opening for reading. If the file does not exist, and the {.Create} flag is passed, it is created with the permissions perm, and please note that the containing directory must exist otherwise and an error will be returned. If successful, a ^File is return which can be used for I/O. And error is returned if any is encountered.

    perm_number ¶
    Source

    perm_number :: proc "contextless" (perm: int) -> Permissions {…}
     

    perm_number converts an integer value perm to the bit set Permissions

    Related Procedure Groups

    pipe ¶
    Source

    pipe :: proc() -> (r, w: ^File, err: Error) {…}
     

    Create an anonymous pipe.

    This procedure creates an anonymous pipe, returning two ends of the pipe, r and w. The file r is the readable end of the pipe. The file w is a writeable end of the pipe.

    Pipes are used as an inter-process communication mechanism, to communicate between a parent and a child process. The child uses one end of the pipe to write data, and the parent uses the other end to read from the pipe (or vice-versa). When a parent passes one of the ends of the pipe to the child process, that end of the pipe needs to be closed by the parent, before any data is attempted to be read.

    Although pipes look like files and is compatible with most file APIs in package os2, the way it's meant to be read is different. Due to asynchronous nature of the communication channel, the data may not be present at the time of a read request. The other scenario is when a pipe has no data because the other end of the pipe was closed by the child process.

    pipe_has_data ¶
    Source

    pipe_has_data :: proc(r: ^File) -> (ok: bool, err: Error) {…}
     

    Check if the pipe has any data.

    This procedure checks whether a read-end of the pipe has data that can be read, and returns true, if the pipe has readable data, and false if the pipe is empty. This procedure does not block the execution of the current thread.

    Note: If the other end of the pipe was closed by the child process, the .Broken_Pipe can be returned by this procedure. Handle these errors accordingly.

    print_error :: proc(f: ^File, ferr: Error, msg: string) {…}
     

    print_error is a utility procedure which will print an error ferr to a specified file f.

    process_close ¶
    Source

    process_close :: proc(process: Process) -> Error {…}
     

    Close the handle to a process.

    This procedure closes the handle associated with a process. It does not terminate a process, in case it was running. In case a termination is desired, kill the process first, wait for the process to finish, then close the handle.

    process_exec ¶
    Source

    process_exec :: proc(desc: Process_Desc, allocator: runtime.Allocator, loc := #caller_location) -> (state: Process_State, stdout: []u8, stderr: []u8, err: Error) {…}
     

    Execute the process and capture stdout and stderr streams.

    This procedure creates a new process, with a given command and environment strings as parameters, and waits until the process finishes execution. While the process is running, this procedure accumulates the output of its stdout and stderr streams and returns byte slices containing the captured data from the streams.

    This procedure expects that stdout and stderr fields of the desc parameter are left at default, i.e. a nil value. You can not capture stdout/stderr and redirect it to a file at the same time.

    This procedure does not free stdout and stderr slices before an error is returned. Make sure to call delete on these slices.

    process_info_by_handle ¶
    Source

    process_info_by_handle :: proc(process: Process, selection: bit_set[Process_Info_Field], allocator: runtime.Allocator) -> (Process_Info, Error) {…}
     

    Obtain information about a process.

    This procedure obtains information, specified by selection parameter about a process that has been opened by the application, specified in the process parameter.

    Use free_process_info to free the memory allocated by this procedure. The free_process_info procedure needs to be called, even if this procedure returned an error, as some of the fields may have been allocated.

    Note: The resulting information may or may contain the fields specified by the selection parameter. Always check whether the returned Process_Info struct has the required fields before checking the error code returned by this procedure.

    Related Procedure Groups

    process_info_by_pid ¶
    Source

    process_info_by_pid :: proc(pid: int, selection: bit_set[Process_Info_Field], allocator: runtime.Allocator) -> (Process_Info, Error) {…}
     

    Obtain information about a process.

    This procedure obtains an information, specified by selection parameter of a process given by pid.

    Use free_process_info to free the memory allocated by this procedure. The free_process_info procedure needs to be called, even if this procedure returned an error, as some of the fields may have been allocated.

    Note: The resulting information may or may contain the fields specified by the selection parameter. Always check whether the returned Process_Info struct has the required fields before checking the error code returned by this procedure.

    Related Procedure Groups

    process_kill ¶
    Source

    process_kill :: proc(process: Process) -> Error {…}
     

    Terminate a process.

    This procedure terminates a process, specified by it's handle, process.

    process_list ¶
    Source

    process_list :: proc(allocator: runtime.Allocator) -> ([]int, Error) {…}
     

    Obtain ID's of all processes running in the system.

    process_open ¶
    Source

    process_open :: proc(pid: int, flags: bit_set[Process_Open_Flag] = Process_Open_Flags{}) -> (Process, Error) {…}
     

    Open a process handle using it's pid.

    This procedure obtains a process handle of a process specified by pid. This procedure can be subject to race conditions. See the description of Process.

    Use process_close() function to close the process handle.

    process_start ¶
    Source

    process_start :: proc(desc: Process_Desc) -> (Process, Error) {…}
     

    Create a new process and obtain its handle.

    This procedure creates a new process, with a given command and environment strings as parameters. Use environ() to inherit the environment of the current process.

    The desc parameter specifies the description of how the process should be created. It contains information such as the command line, the environment of the process, the starting directory and many other options. Most of the fields in the struct can be set to nil or an empty value.

    Use process_close to close the handle to the process. Note, that this is not the same as terminating the process. One can terminate the process and not close the handle, in which case the handle would be leaked. In case the function returns an error, an invalid handle is returned.

    This procedure is not thread-safe. It may alter the inheritance properties of file handles in an unpredictable manner. In case multiple threads change handle inheritance properties, make sure to serialize all those calls.

    process_wait ¶
    Source

    process_wait :: proc(process: Process, timeout: time.Duration = TIMEOUT_INFINITE) -> (Process_State, Error) {…}
     

    Wait for a process event.

    This procedure blocks the execution until the process has exited or the timeout (if specified) has reached zero. If the timeout is TIMEOUT_INFINITE, no timeout restriction is imposed and the procedure can block indefinately.

    If the timeout has expired, the General_Error.Timeout is returned as the error.

    If an error is returned for any other reason, other than timeout, the process state is considered undetermined.

    read ¶
    Source

    read :: proc(f: ^File, p: []u8) -> (n: int, err: Error) {…}
     

    read reads up to len(p) bytes from the file f, and then stores them in p. It returns the number of bytes read and an error, if any is encountered. At the end of a file, it returns 0, io.EOF.

    read_all_directory ¶
    Source

    read_all_directory :: proc(f: ^File, allocator: runtime.Allocator) -> (fi: []File_Info, err: Error) {…}
     

    Reads the file f (assuming it is a directory) and returns all of the unsorted directory entries.

    read_all_directory_by_path ¶
    Source

    read_all_directory_by_path :: proc(path: string, allocator: runtime.Allocator) -> (fi: []File_Info, err: Error) {…}
     

    Reads the named directory by path (assuming it is a directory) and returns all of the unsorted directory entries.

    read_at ¶
    Source

    read_at :: proc(f: ^File, p: []u8, offset: i64) -> (n: int, err: Error) {…}
     

    read_at reads up to len(p) bytes from the file f at the byte offset offset, and then stores them in p. It returns the number of bytes read and an error, if any is encountered. read_at always returns a non-nil error when n < len(p). At the end of a file, the error is io.EOF.

    read_at_least ¶
    Source

    read_at_least :: proc(f: ^File, buf: []u8, min: int) -> (n: int, err: Error) {…}
     

    read_at_least reads from f into buf until it has read at least min bytes. It returns the number of bytes copied and an error if fewer bytes were read. The error is only an io.EOF if no bytes were read.

    read_dir ¶
    Source

    read_dir :: read_directory
     

    Reads the file f (assuming it is a directory) and returns the unsorted directory entries. This returns up to n entries OR all of them if n <= 0.

    read_directory ¶
    Source

    read_directory :: proc(f: ^File, n: int, allocator: runtime.Allocator) -> (files: []File_Info, err: Error) {…}
     

    Reads the file f (assuming it is a directory) and returns the unsorted directory entries. This returns up to n entries OR all of them if n <= 0.

    read_directory_by_path ¶
    Source

    read_directory_by_path :: proc(path: string, n: int, allocator: runtime.Allocator) -> (fi: []File_Info, err: Error) {…}
     

    Reads the named directory by path (assuming it is a directory) and returns the unsorted directory entries. This returns up to n entries OR all of them if n <= 0.

    read_directory_iterator ¶
    Source

    read_directory_iterator :: proc(it: ^Read_Directory_Iterator) -> (fi: File_Info, index: int, ok: bool) {…}
     

    Returns the next file info entry for the iterator's directory.

    The given File_Info is reused in subsequent calls so a copy (file_info_clone) has to be made to extend its lifetime.

    Example: 
    package main

import    "core:fmt"
import os "core:os/os2"

main :: proc() {
	f, oerr := os.open("core")
	ensure(oerr == nil)
	defer os.close(f)

	it := os.read_directory_iterator_create(f)
	defer os.read_directory_iterator_destroy(&it)

	for info in os.read_directory_iterator(&it) {
		// Optionally break on the first error:
		// Supports not doing this, and keeping it going with remaining items.
		// _ = os.read_directory_iterator_error(&it) or_break

		// Handle error as we go:
		// Again, no need to do this as it will keep going with remaining items.
		if path, err := os.read_directory_iterator_error(&it); err != nil {
			fmt.eprintfln("failed reading %s: %s", path, err)
			continue
		}

		// Or, do not handle errors during iteration, and just check the error at the end.


		fmt.printfln("%#v", info)
	}

	// Handle error if one happened during iteration at the end:
	if path, err := os.read_directory_iterator_error(&it); err != nil {
		fmt.eprintfln("read directory failed at %s: %s", path, err)
	}
}

    read_directory_iterator_create ¶
    Source

    read_directory_iterator_create :: proc(f: ^File) -> (it: Read_Directory_Iterator) {…}
     

    Creates a directory iterator with the given directory.

    For an example on how to use the iterator, see read_directory_iterator.

    read_directory_iterator_destroy ¶
    Source

    read_directory_iterator_destroy :: proc(it: ^Read_Directory_Iterator) {…}
     

    Destroys a directory iterator.

    read_directory_iterator_error ¶
    Source

    read_directory_iterator_error :: proc(it: ^Read_Directory_Iterator) -> (path: string, err: Error) {…}
     

    Retrieve the last error that happened during iteration.

    read_directory_iterator_init ¶
    Source

    read_directory_iterator_init :: proc(it: ^Read_Directory_Iterator, f: ^File) {…}
     

    Initialize a directory iterator with the given directory.

    This procedure may be called on an existing iterator to reuse it for another directory.

    For an example on how to use the iterator, see read_directory_iterator.

    read_entire_file_from_file ¶
    Source

    read_entire_file_from_file :: proc(f: ^File, allocator: runtime.Allocator, loc := #caller_location) -> (data: []u8, err: Error) {…}
     

    read_entire_file_from_file reads the entire file f into memory allocated with allocator. A slice of bytes and an error is returned, if any error is encountered.

    Related Procedure Groups

    read_entire_file_from_path ¶
    Source

    read_entire_file_from_path :: proc(name: string, allocator: runtime.Allocator, loc := #caller_location) -> (data: []u8, err: Error) {…}
     

    read_entire_file_from_path reads the entire named file name into memory allocated with allocator. A slice of bytes and an error is returned, if any error is encountered.

    Related Procedure Groups

    read_full ¶
    Source

    read_full :: proc(f: ^File, buf: []u8) -> (n: int, err: Error) {…}
     

    read_full reads exactly len(buf) bytes from f into buf. It returns the number of bytes copied and an error if fewer bytes were read. The error is only an io.EOF if no bytes were read.

    It is equivalent to read_at_least(f, buf, len(buf)).

    read_link :: proc(name: string, allocator: runtime.Allocator) -> (string, Error) {…}
     

    read_link returns the destinction of the named symbolic link name.

    read_ptr ¶
    Source

    read_ptr :: proc(f: ^File, data: rawptr, len: int) -> (n: int, err: Error) {…}
     

    read_ptr is a utility procedure that reads the bytes points at data with length len.

    It is equivalent to: read(f, ([^]byte)(data)[:len])

    remove ¶
    Source

    remove :: proc(name: string) -> Error {…}
     

    remove removes a named file or (empty) directory.

    remove_all ¶
    Source

    remove_all :: proc(path: string) -> Error {…}
     

    Delete path and all files and directories inside of path if it is a directory.

    If path is relative, it will be relative to the process's current working directory.

    rename ¶
    Source

    rename :: proc(old_path, new_path: string) -> Error {…}
     

    rename renames (moves) old_path to new_path.

    replace_environment_placeholders ¶
    Source

    replace_environment_placeholders :: proc(path: string, allocator: runtime.Allocator) -> (res: string) {…}
     

    Always allocates for consistency.

    same_file ¶
    Source

    same_file :: proc(fi1, fi2: File_Info) -> bool {…}
     

    Returns true if two File_Infos are equivalent.

    seek ¶
    Source

    seek :: proc(f: ^File, offset: i64, whence: io.Seek_From) -> (ret: i64, err: Error) {…}
     

    seek sets the offsets for the next read or write on a file to a specified offset, according to what whence is set. .Start is relative to the origin of the file. .Current is relative to the current offset. .End is relative to the end. It returns the new offset and an error, if any is encountered. Prefer read_at or write_at if the offset does not want to be changed.

    set_env ¶
    Source

    set_env :: proc(key, value: string) -> Error {…}
     

    set_env sets the value of the environment variable named by the key Returns Error on failure

    set_working_directory ¶
    Source

    set_working_directory :: proc(dir: string) -> (err: Error) {…}
     

    Change the working directory of the current process.

    Allocates Using Provided Allocator

    setwd ¶
    Source

     

    Change the working directory of the current process.

    Allocates Using Provided Allocator

    split_filename ¶
    Source

    split_filename :: proc(filename: string) -> (base, ext: string) {…}
     

    Split a filename from its extension.

    This procedure splits on the last separator.

    If the filename begins with a separator, such as ".readme.txt", the separator will be included in the filename, resulting in ".readme" and "txt".

    For example, split_filename("foo.tar.gz") will return "foo.tar" and "gz".

    split_filename_all ¶
    Source

    split_filename_all :: proc(filename: string) -> (base, ext: string) {…}
     

    Split a filename from its extension.

    This procedure splits on the first separator.

    If the filename begins with a separator, such as ".readme.txt.gz", the separator will be included in the filename, resulting in ".readme" and "txt.gz".

    For example, split_filename_all("foo.tar.gz") will return "foo" and "tar.gz".

    split_path ¶
    Source

    split_path :: proc(path: string) -> (dir, filename: string) {…}
     

    Split a path into a directory hierarchy and a filename.

    For example, split_path("/home/foo/bar.tar.gz") will return "/home/foo" and "bar.tar.gz".

    split_path_list ¶
    Source

    split_path_list :: proc(path: string, allocator: runtime.Allocator) -> (list: []string, err: Error) {…}
     

    Split a string that is separated by a system-specific separator, typically used for environment variables specifying multiple directories.

    Allocates Using Provided Allocator

    For example, there is the "PATH" environment variable on POSIX systems which this procedure can split into separate entries.

    stat ¶
    Source

    stat :: proc(name: string, allocator: runtime.Allocator) -> (File_Info, Error) {…}
     

    stat returns a File_Info describing the named file from the file system. The resulting File_Info must be deleted with file_info_delete.

    stat_do_not_follow_links :: proc(name: string, allocator: runtime.Allocator) -> (File_Info, Error) {…}
     

    Returns a File_Info describing the named file from the file system. If the file is a symbolic link, the File_Info returns describes the symbolic link, rather than following the link. The resulting File_Info must be deleted with file_info_delete.

    symlink :: proc(old_name, new_name: string) -> Error {…}
     

    symlink creates a new_name as a symbolic link to the old_name file.

    sync ¶
    Source

    sync :: proc(f: ^File) -> Error {…}
     

    sync commits the current contents of the file f to stable storage. This usually means flushing the file system's in-memory copy to disk.

    temp_dir ¶
    Source

    temp_dir :: temp_directory
     

    Returns the default directory to use for temporary files.

    On Unix systems, it typically returns $TMPDIR if non-empty, otherwlse /tmp. On Windows, it uses GetTempPathW, returning the first non-empty value from one of the following: * %TMP% * %TEMP% * %USERPROFILE % * or the Windows directory See https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-gettemppathw for more information. On wasi, it returns /tmp.

    temp_directory ¶
    Source

    temp_directory :: proc(allocator: runtime.Allocator) -> (string, Error) {…}
     

    Returns the default directory to use for temporary files.

    On Unix systems, it typically returns $TMPDIR if non-empty, otherwlse /tmp. On Windows, it uses GetTempPathW, returning the first non-empty value from one of the following: * %TMP% * %TEMP% * %USERPROFILE % * or the Windows directory See https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-gettemppathw for more information. On wasi, it returns /tmp.

    to_reader ¶
    Source

    to_reader :: to_stream
     

    Converts a file f into an io.Stream

    to_stream ¶
    Source

    to_stream :: proc(f: ^File) -> (s: io.Stream) {…}
     

    Converts a file f into an io.Stream

    to_writer ¶
    Source

    to_writer :: to_stream
     

    Converts a file f into an io.Stream

    truncate ¶
    Source

    truncate :: proc(f: ^File, size: i64) -> Error {…}
     

    truncate changes the size of the file f to size in bytes. This can be used to shorten or lengthen a file. It does not change the "offset" of the file.

    unset_env ¶
    Source

    unset_env :: proc(key: string) -> bool {…}
     

    unset_env unsets a single environment variable Returns true on success, false on failure

    user_cache_dir ¶
    Source

    user_cache_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {…}
     

    Files that applications can regenerate/refetch at a loss of speed, e.g. shader caches

    Sometimes deleted for system maintenance

    ` Windows: C:\Users\Alice\AppData\Local macOS: /Users/Alice/Library/Caches Linux: /home/alice/.cache `

    user_config_dir ¶
    Source

    user_config_dir :: proc(allocator: runtime.Allocator, roaming: bool = false) -> (dir: string, err: Error) {…}
     

    Application settings/preferences

    ` Windows: C:\Users\Alice\AppData\Local ("C:\Users\Alice\AppData\Roaming" if roaming) macOS: /Users/Alice/Library/Application Support Linux: /home/alice/.config `

    NOTE: (Windows only) roaming is for syncing across multiple devices within a domain network

    user_data_dir ¶
    Source

    user_data_dir :: proc(allocator: runtime.Allocator, roaming: bool = false) -> (dir: string, err: Error) {…}
     

    User-hidden application data

    ` Windows: C:\Users\Alice\AppData\Local ("C:\Users\Alice\AppData\Roaming" if roaming) macOS: /Users/Alice/Library/Application Support Linux: /home/alice/.local/share `

    NOTE: (Windows only) roaming is for syncing across multiple devices within a domain network

    user_desktop_dir ¶
    Source

    user_desktop_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {…}
     

    ` Windows: C:\Users\Alice\Desktop macOS: /Users/Alice/Desktop Linux: /home/alice/Desktop `

    user_documents_dir ¶
    Source

    user_documents_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {…}
     

    ` Windows: C:\Users\Alice\Documents macOS: /Users/Alice/Documents Linux: /home/alice/Documents `

    user_downloads_dir ¶
    Source

    user_downloads_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {…}
     

    ` Windows: C:\Users\Alice\Downloads macOS: /Users/Alice/Downloads Linux: /home/alice/Downloads `

    user_home_dir ¶
    Source

    user_home_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {…}
     

    ` Windows: C:\Users\Alice macOS: /Users/Alice Linux: /home/alice `

    user_log_dir ¶
    Source

    user_log_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {…}
     

    Application log files

    ` Windows: C:\Users\Alice\AppData\Local macOS: /Users/Alice/Library/Logs Linux: /home/alice/.local/state `

    user_music_dir ¶
    Source

    user_music_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {…}
     

    ` Windows: C:\Users\Alice\Music macOS: /Users/Alice/Music Linux: /home/alice/Music `

    user_pictures_dir ¶
    Source

    user_pictures_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {…}
     

    ` Windows: C:\Users\Alice\Pictures macOS: /Users/Alice/Pictures Linux: /home/alice/Pictures `

    user_public_dir ¶
    Source

    user_public_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {…}
     

    ` Windows: C:\Users\Alice\Public macOS: /Users/Alice/Public Linux: /home/alice/Public `

    user_state_dir ¶
    Source

    user_state_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {…}
     

    Non-essential application data, e.g. history, ui layout state

    ` Windows: C:\Users\Alice\AppData\Local macOS: /Users/Alice/Library/Application Support Linux: /home/alice/.local/state `

    user_videos_dir ¶
    Source

    user_videos_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {…}
     

    ` Windows: C:\Users\Alice\Videos macOS: /Users/Alice/Movies Linux: /home/alice/Videos `

    walker_create_file ¶
    Source

    walker_create_file :: proc(f: ^File) -> (w: Walker) {…}
    Related Procedure Groups

    walker_create_path ¶
    Source

    walker_create_path :: proc(path: string) -> (w: Walker) {…}
    Related Procedure Groups

    walker_destroy ¶
    Source

    walker_destroy :: proc(w: ^Walker) {…}

    walker_error ¶
    Source

    walker_error :: proc(w: ^Walker) -> (path: string, err: Error) {…}
     

    Returns the last error that occurred during the walker's operations.

    Can be called while iterating, or only at the end to check if anything failed.

    walker_init_file ¶
    Source

    walker_init_file :: proc(w: ^Walker, f: ^File) {…}
    Related Procedure Groups

    walker_init_path ¶
    Source

    walker_init_path :: proc(w: ^Walker, path: string) {…}
    Related Procedure Groups

    walker_skip_dir ¶
    Source

    walker_skip_dir :: proc(w: ^Walker) {…}
     

    Marks the current directory to be skipped (not entered into).

    walker_walk ¶
    Source

    walker_walk :: proc(w: ^Walker) -> (fi: File_Info, ok: bool) {…}
     

    Returns the next file info in the iterator, files are iterated in breadth-first order.

    If an error occurred opening a directory, you may get zero'd info struct and walker_error will return the error.

    Example: 
    package main

import    "core:fmt"
import    "core:strings"
import os "core:os/os2"

main :: proc() {
	w := os.walker_create("core")
	defer os.walker_destroy(&w)

	for info in os.walker_walk(&w) {
		// Optionally break on the first error:
		// _ = walker_error(&w) or_break

		// Or, handle error as we go:
		if path, err := os.walker_error(&w); err != nil {
			fmt.eprintfln("failed walking %s: %s", path, err)
			continue
		}

		// Or, do not handle errors during iteration, and just check the error at the end.



		// Skip a directory:
		if strings.has_suffix(info.fullpath, ".git") {
			os.walker_skip_dir(&w)
			continue
		}

		fmt.printfln("%#v", info)
	}

	// Handle error if one happened during iteration at the end:
	if path, err := os.walker_error(&w); err != nil {
		fmt.eprintfln("failed walking %s: %v", path, err)
	}
}

    write ¶
    Source

    write :: proc(f: ^File, p: []u8) -> (n: int, err: Error) {…}
     

    write writes len(p) bytes from p to the file f. It returns the number of bytes written to and an error, if any is encountered. write returns a non-nil error when n != len(p).

    write_at ¶
    Source

    write_at :: proc(f: ^File, p: []u8, offset: i64) -> (n: int, err: Error) {…}
     

    write_at writes len(p) bytes from p to the file f starting at byte offset offset. It returns the number of bytes written to and an error, if any is encountered. write_at returns a non-nil error when n != len(p).

    write_byte ¶
    Source

    write_byte :: proc(f: ^File, b: u8) -> (n: int, err: Error) {…}
     

    write_byte writes a byte b to file f. Returns the number of bytes written and an error, if any is encountered.

    write_encoded_rune ¶
    Source

    write_encoded_rune :: proc(f: ^File, r: untyped rune) -> (n: int, err: Error) {…}
     

    write_encoded_rune writes a rune r as an UTF-8 encoded string which with escaped control codes to file f. Returns the number of bytes written and an error, if any is encountered.

    write_entire_file_from_bytes ¶
    Source

    write_entire_file_from_bytes :: proc(name: string, data: []u8, perm: Permissions = Permissions_Read_All + {.Write_User}, truncate: bool = true) -> Error {…}
     

    write_entire_file_from_bytes writes the contents of data into named file name. It defaults with the permssions perm := Permissions_Read_All + {.Write_User}, and truncates by default. An error is returned if any is encountered.

    Related Procedure Groups

    write_entire_file_from_string ¶
    Source

    write_entire_file_from_string :: proc(name: string, data: string, perm: Permissions = Permissions_Read_All + {.Write_User}, truncate: bool = true) -> Error {…}
     

    write_entire_file_from_string writes the contents of data into named file name. It defaults with the permssions perm := Permissions_Read_All + {.Write_User}, and truncates by default. An error is returned if any is encountered.

    Related Procedure Groups

    write_ptr ¶
    Source

    write_ptr :: proc(f: ^File, data: rawptr, len: int) -> (n: int, err: Error) {…}
     

    write_ptr is a utility procedure that writes the bytes points at data with length len.

    It is equivalent to: write(f, ([^]byte)(data)[:len])

    write_rune ¶
    Source

    write_rune :: proc(f: ^File, r: untyped rune) -> (n: int, err: Error) {…}
     

    write_rune writes a rune r as an UTF-8 encoded string to file f. Returns the number of bytes written and an error, if any is encountered.

    write_string ¶
    Source

    write_string :: proc(f: ^File, s: string) -> (n: int, err: Error) {…}
     

    write_string writes a string s to file f. Returns the number of bytes written and an error, if any is encountered.

    write_strings ¶
    Source

    write_strings :: proc(f: ^File, .. strings: ..string) -> (n: int, err: Error) {…}
     

    write_strings writes a variadic list of strings strings to file f. Returns the number of bytes written and an error, if any is encountered.

    Procedure Groups

    get_env ¶
    Source

    get_env :: proc{
	get_env_alloc,
	get_env_buf,
}

    lookup_env ¶
    Source

    lookup_env :: proc{
	lookup_env_alloc,
	lookup_env_buf,
}

    perm ¶
    Source

    perm :: proc{
	perm_number,
}

    process_info ¶
    Source

     

    Obtain information about the specified process.

    read_entire_file ¶
    Source

    walker_create ¶
    Source

    walker_create :: proc{
	walker_create_path,
	walker_create_file,
}
     

    Creates a walker, either using a path or a file pointer to a directory the walker will start at.

    For an example on how to use the walker, see walker_walk.

    walker_init ¶
    Source

    walker_init :: proc{
	walker_init_path,
	walker_init_file,
}
     

    Initializes a walker, either using a path or a file pointer to a directory the walker will start at.

    You are allowed to repeatedly call this to reuse it for later walks.

    For an example on how to use the walker, see walker_walk.

    write_entire_file ¶
    Source

     

    write_entire_file writes the contents of data into named file name. It defaults with the permssions perm := Permissions_Read_All + {.Write_User}, and truncates by default. An error is returned if any is encountered.

    Source Files

    Generation Information

    Generated with odin version dev-2025-11 (vendor "odin") Windows_amd64 @ 2025-11-21 21:12:30.644520900 +0000 UTC