os

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

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.

Represents the file flags for a file handle

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

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.

General errors that are common within this package which cannot

be categorized by `io.Error` nor `runtime.Allocator_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.

The description of how a process should be created.

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

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.

The state of the process after it has finished execution.

A recursive directory walker.

Note that none of the fields should be accessed directly.

Most implementations will EINVAL at some point when doing big writes. In practice a read/write call would probably never read/write these big buffers all at once, which is why the number of bytes is returned and why there are procs that will call this in a loop for you. We set a max of 1GB to keep alignment and to be safe.

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

A platform specific error

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

This implementation is for all systems that have POSIX-compliant filesystem paths.

NOTE: will throw error without super user priviledges

NOTE: will throw error without super user priviledges

Internal implementation of glob, not meant to be used by the user. Prefer glob.

NOTE: will throw error without super user priviledges

Splits pattern by the last wildcard "", if it exists, and returns the prefix and suffix parts which are split by the last ""

NOTE: _stat and _lstat are using _fstat to avoid a race condition when populating fullpath

If <config-dir>/user-dirs.dirs doesn't exist, or xdg_key can't be found there: returns ""

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.

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.

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

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.

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

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.

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

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.

@(require_results) open_buffered :: proc(name: string, buffer_size: uint, flags := File_Flags{.Read}, perm := 0o777) -> (^File, Error) {

if buffer_size == 0 {
		return _open(name, flags, perm)
	}
	return _open_buffered(name, buffer_size, flags, perm)
}
`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.