package core:os

Source

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

• error_string
• is_platform_error
• print_error

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.

• clone
• close
• fchange_directory
• fchange_mode
• fchange_owner
• fchange_times
• fd
• file_size
• flush
• fstat
• is_tty
• modification_time
• name
• pipe_has_data
• print_error
• read
• read_all_directory
• read_at
• read_at_least
• read_directory
• read_directory_iterator_create
• read_directory_iterator_init
• read_entire_file_from_file
• read_full
• read_ptr
• read_slice
• seek
• sync
• to_stream
• truncate
• walker_create_file
• walker_init_file
• write
• write_at
• write_byte
• write_encoded_rune
• write_ptr
• write_rune
• write_slice
• write_string
• write_strings
• read_entire_file (procedure groups)
• walker_create (procedure groups)
• walker_init (procedure groups)

• create
• create_temp_file
• new_file
• open
• pipe

Represents the file flags for a file handle

• create_temp_file
• open

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

• file_info_clone
• file_info_delete
• same_file

• fstat
• read_directory_iterator
• stat
• stat_do_not_follow_links
• walker_walk

A subset of the io.Stream_Mode with added File specific modes

Superset interface of io.Stream_Proc with the added runtime.Allocator parameter needed for the Fstat mode

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

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

• change_mode
• copy_directory_all
• fchange_mode
• make_directory
• make_directory_all
• open
• write_entire_file_from_bytes
• write_entire_file_from_string
• write_entire_file (procedure groups)

• perm_number
• perm (procedure groups)

A platform specific error

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.

• process_info_by_handle
• process_kill
• process_terminate
• process_wait
• process_info (procedure groups)

• process_open
• process_start

The description of how a process should be created.

• process_exec
• process_start

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

• current_process_info
• process_info_by_handle
• process_info_by_pid
• process_info (procedure groups)

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.

• current_process_info
• process_info_by_handle
• process_info_by_pid
• process_info (procedure groups)

The state of the process after it has finished execution.

• process_exec
• process_wait

• read_directory_iterator
• read_directory_iterator_destroy
• read_directory_iterator_error
• read_directory_iterator_init

A recursive directory walker.

Note that none of the fields should be accessed directly.

• walker_destroy
• walker_error
• walker_init_file
• walker_init_path
• walker_skip_dir
• walker_walk
• walker_init (procedure groups)

• walker_create_file
• walker_create_path
• walker_create (procedure groups)

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.

OS-Specific

OS-Specific

OS-Specific

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

Arguments to the current process.

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

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

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

Compare two paths for exactness without normalization.

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

Gets the file name and extension from a path.

e.g.

'path/to/name.tar.gz' -> 'name.tar.gz'
'path/to/name.txt'    -> 'name.txt'
'path/to/name'        -> 'name'

Returns "." if the path is an empty string.

Changes the current working directory to the named directory.

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.

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.

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.

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

Changes the current working directory to the named directory.

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.

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.

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

Normalize a path.

Allocates Using Provided Allocator

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

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

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.

Recursively copies a directory to dst from src

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.

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.

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.

Gets the parent directory path from a path.

e.g.

'/home/foo/bar.tar.gz' -> '/home/foo'
'path/to/name.tar.gz'  -> 'path/to'

Returns "." if the path is an empty string.

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

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

exists returns whether or not a named file exists.

Tells the OS to exit the current process directly.

IMPORTANT: @(fini) blocks won't be executed.

If you want @(fini) cleanup to happen, call runtime._cleanup_runtime first.

Gets the file extension from a path, including the dot.

The file extension is such that stem_path(path) + ext(path) = base(path).

Only the last dot is considered when splitting the file extension. See long_ext.

e.g.

'name.tar.gz' -> '.gz'
'name.txt'    -> '.txt'

Returns an empty string if there is no dot. Returns an empty string if there is a trailing path separator.

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

Changes the current mode permissions of the file f.

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.

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

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

Changes the current mode permissions of the file f.

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.

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

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

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

flush flushes a file f

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.

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

Allocates Using Provided Allocator

Obtain the current thread id

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

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

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 the directory for the currently running executable.

Allocates Using Provided Allocator

Get the path for the currently running executable.

Allocates Using Provided Allocator

Obtain the GID of the current process.

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

Obtain the ID of the current process.

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.

Return the number of cores

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.

Obtain the UID of the current process.

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

Get the working directory of the current process.

Allocates Using Provided Allocator

Get the working directory of the current process.

Allocates Using Provided Allocator

glob returns the names of all files matching pattern or nil if there are no matching files The syntax of patterns is the same as "match". The pattern may describe hierarchical names such as /usr/*/bin (assuming '/' is a separator)

glob ignores file system errors

Returns the default heap_allocator for this specific platform.

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

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

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

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

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

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

is_tty returns true if f is a TTY, false if not.

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

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

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

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 creates a new_name as a hard link to the old_name file.

Gets the file extension from a path, including the dot.

The long file extension is such that short_stem(path) + long_ext(path) = base(path).

The first dot is used to split off the file extension, unlike ext which uses the last dot.

e.g.

'name.tar.gz' -> '.tar.gz'
'name.txt'    -> '.txt'

Returns an empty string if there is no dot. Returns an empty string if there is a trailing path separator.

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

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.

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 a new directory.

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

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.

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.

match states whether "name" matches the shell pattern

Pattern syntax is:

pattern:
	{term}
term:
	'*'	        matches any sequence of non-/ characters
	'?'             matches any single non-/ character
	'[' ['^']  { character-range } ']'
									character classification (cannot be empty)
	c               matches character c (c != '*', '?', '\\', '[')
	'\\' c          matches character c

character-range
	c               matches character c (c != '\\', '-', ']')
	'\\' c          matches character c
	lo '-' hi       matches character c for lo <= c <= hi

match requires that the pattern matches the entirety of the name, not just a substring. The only possible error returned is .Syntax_Error or an allocation error.

NOTE(bill): This is effectively the shell pattern matching system found

Make a new directory.

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

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.

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.

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

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

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

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 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 converts an integer value perm to the bit set Permissions

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 os, 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.

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 is a utility procedure which will print an error ferr to a specified file f.

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.

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.

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.

Kill a process.

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

The process is forced to exit and can't ignore the request.

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

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 the process_wait() procedure (optionally prefaced with a process_kill()) to close and free the process handle.

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 the process_wait() procedure (optionally prefaced with a process_kill()) to close and free the process handle.

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.

Terminate a process.

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

The process is requested to exit and can ignore the request.

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

If the timeout is 0, no blocking will be done and the current state is returned.

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

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

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

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

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.

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.

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.

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.

package main

import "core:fmt"
import "core:os"

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

Creates a directory iterator with the given directory.

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

Destroys a directory iterator.

Retrieve the last error that happened during iteration.

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 reads the entire file f into memory allocated with allocator. A slice of bytes and an error is returned, if any error is encountered.

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.

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 returns the destinction of the named symbolic link name.

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

read_slice is a utility procedure that writes the bytes points at slice.

It is equivalent to: read(f, ([^]byte)(raw_data(slice))[:len(slice)*size_of(slice[0])])

remove removes a named file or (empty) directory.

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 renames (moves) old_path to new_path.

Always allocates for consistency.

Returns the result of replacing each path separator character in the path with the new_sep rune.

Allocates Using Provided Allocator

Returns true if two File_Infos are equivalent.

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 sets the value of the environment variable named by the key Returns Error on failure

Change the working directory of the current process.

Allocates Using Provided Allocator

Change the working directory of the current process.

Allocates Using Provided Allocator

Gets the name of a file from a path.

The short stem is such that short_stem(path) + long_ext(path) = base(path), where long_ext is the extension returned by split_filename_all.

The first dot is used to split off the file extension, unlike stem which uses the last dot.

e.g.

'name.tar.gz' -> 'name'
'name.txt'    -> 'name'

Returns an empty string if there is no stem. e.g: '.gitignore'. Returns an empty string if there's a trailing path separator.

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 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 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 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 returns a File_Info describing the named file from the file system. The resulting File_Info must be deleted with file_info_delete.

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.

Gets the name of a file from a path.

The stem of a file is such that stem(path) + ext(path) = base(path).

Only the last dot is considered when splitting the file extension. See short_stem.

e.g.

'name.tar.gz' -> 'name.tar'
'name.txt'    -> 'name'

Returns an empty string if the path is empty Returns an empty string if there is no stem. e.g: '.gitignore'. Returns an empty string if there's a trailing path separator.

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

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.

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.

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.

Converts a file f into an io.Stream

Converts a file f into an io.Stream

Converts a file f into an io.Stream

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 unsets a single environment variable Returns true on success, false on failure

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

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

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

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

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

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

Application log files

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

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

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

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

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

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

Returns leading volume name.

e.g.

"C:\foo\bar\baz" will return "C:" on Windows.
Everything else will be "".

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.

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

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.

package main

import "core:fmt"
import "core:strings"
import "core:os"

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 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 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 writes a byte b to file f. Returns the number of bytes written and an error, if any is encountered.

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

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.

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 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_slice is a utility procedure that writes the bytes points at slice.

It is equivalent to: write(f, ([^]byte)(raw_data(slice))[:len(slice)*size_of(slice[0])])

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

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.

Obtain information about the specified process.

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.

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