os #

Description:

os provides common OS/platform independent functions for accessing command line arguments, reading/writing files, listing folders, handling processes etc.

Security advice related to TOCTOU attacks

A few os module functions can lead to the TOCTOU vulnerability if used incorrectly. TOCTOU (Time-of-Check-to-Time-of-Use problem) can occur when a file, folder or similar is checked for certain specifications (e.g. read, write permissions) and a change is made afterwards. In the time between the initial check and the edit, an attacker can then cause damage. The following example shows an attack strategy on the left and an improved variant on the right so that TOCTOU is no longer possible.

Example Hint: os.create() opens a file in write-only mode

if os.is_writable('file') {
// time to make a quick attack
// (e.g. symlink /etc/passwd to `file`)

mut f := os.create('path/to/file')!
// do something with file
f.close()
}

mut f := os.create('path/to/file') or {
println('file not writable')
}

// file is locked
// do something with file

f.close()

Proven affected functions
The following functions should be used with care and only when used correctly.

• os.is_readable()
• os.is_writable()
• os.is_executable()
• os.is_link()

fn abs_path(path string) string

abs_path joins the current working directory with the given path (if the path is relative) and returns the absolute path representation.

fn args_after(cut_word string) []string

args_after returns all os.args, located after a specified cut_word. When cut_word is NOT found, os.args is returned unmodified.

fn args_before(cut_word string) []string

args_before returns all os.args, located before a specified cut_word. When cut_word is NOT found, os.args is returned unmodified.

fn base(opath string) string

base returns the last element of path. Trailing path separators are removed before extracting the last element. If the path is empty, base returns ".". If the path consists entirely of separators, base returns a single separator.

fn cache_dir() string

cache_dir returns the path to a writable user specific folder, suitable for writing non-essential data.

fn chdir(path string) !

chdir changes the current working directory to the new directory in path.

fn chmod(path string, mode int) !

chmod change file access attributes of path to mode. Octals like 0o600 can be used.

fn chown(path string, owner int, group int) !

chown changes the owner and group attributes of path to owner and group.

fn config_dir() !string

config_dir returns the path to the user configuration directory (depending on the platform). On windows, that is %AppData%. On macos, that is ~/Library/Application Support. On the rest, that is $XDG_CONFIG_HOME, or if that is not available, ~/.config. If the path cannot be determined, it returns an error. (for example, when $HOME on linux, or %AppData% on windows is not defined)

fn cp(src string, dst string) !

cp copies files or folders from src to dst.

fn cp_all(src string, dst string, overwrite bool) !

cp_all will recursively copy src to dst, optionally overwriting files or dirs in dst.

fn create(path string) !File

create creates or opens a file at a specified location and returns a write-only File object.

fn debugger_present() bool

debugger_present returns a bool indicating if the process is being debugged

fn dir(opath string) string

dir returns all but the last element of path, typically the path's directory. After dropping the final element, trailing slashes are removed. If the path is empty, dir returns ".". If the path consists entirely of separators, dir returns a single separator. The returned path does not end in a separator unless it is the root directory.

fn ensure_folder_is_writable(folder string) !

ensure_folder_is_writable checks that folder exists, and is writable to the process by creating an empty file in it, then deleting it.

fn environ() map[string]string

See: https://linux.die.net/man/5/environ for unix platforms. See: https://docs.microsoft.com/bg-bg/windows/win32/api/processenv/nf-processenv-getenvironmentstrings os.environ returns a map of all the current environment variables

fn executable() string

executable returns the path name of the executable that started the current process.

fn execute(cmd string) Result

execute starts the specified command, waits for it to complete, and returns its output.

fn execute_opt(cmd string) !Result

execute_opt returns the os.Result of executing cmd, or an error with its output on failure.

fn execute_or_exit(cmd string) Result

fn execute_or_panic(cmd string) Result

fn execve(cmdpath string, cmdargs []string, envs []string) !

execve - loads and executes a new child process, in place of the current process. The child process executable is located in cmdpath. The arguments, that will be passed to it are in args. You can pass environment variables to through envs.

Note: this function will NOT return when successful, since the child process will take control over execution.

fn execvp(cmdpath string, cmdargs []string) !

execvp - loads and executes a new child process, in place of the current process. The child process executable is located in cmdpath. The arguments, that will be passed to it are in args.

Note: this function will NOT return when successful, since the child process will take control over execution.

fn existing_path(path string) !string

existing_path returns the existing part of the given path. An error is returned if there is no existing part of the given path.

fn exists(path string) bool

exists returns true if path (file or directory) exists.

fn exists_in_system_path(prog string) bool

exists_in_system_path returns true if prog exists in the system's PATH

fn expand_tilde_to_home(path string) string

expand_tilde_to_home expands the character ~ in path to the user's home directory. See also home_dir().

fn fd_close(fd int) int

fd_close closes the file descriptor. It returns 0 on success.

fn fd_is_pending(fd int) bool

fd_is_pending returns true, when there is pending data, waiting to be read from file descriptor fd. If the file descriptor is closed, or if reading from it, will block (there is no data), fd_is_pending returns false.

fn fd_read(fd int, maxbytes int) (string, int)

fd_read reads data from the file descriptor. It returns the read data, and how many bytes were read.

fn fd_slurp(fd int) []string

fd_slurp reads all the remaining data from the file descriptor.

fn fd_write(fd int, s string)

fd_write writes the given string to the file descriptor. It blocks until all the data in the string is written.

fn file_ext(opath string) string

file_ext will return the part after the last occurrence of . in path. The . is included. Examples:

assert os.file_ext('file.v') == '.v' assert os.file_ext('.ignore_me') == '' assert os.file_ext('.') == ''

fn file_last_mod_unix(path string) i64

file_last_mod_unix returns the "last modified" time stamp of file in path.

fn file_name(opath string) string

file_name will return all characters found after the last occurrence of path_separator. file extension is included.

fn file_size(path string) u64

file_size returns the size of the file located in path. If an error occurs it returns 0. Note that use of this on symbolic links on Windows returns always 0.

fn fileno(cfile voidptr) int

fileno returns the file descriptor of an opened C file.

fn find_abs_path_of_executable(exepath string) !string

find_abs_path_of_executable walks the environment PATH, just like most shell do, it returns the absolute path of the executable if found

fn flush()

flush will flush the stdout buffer.

fn fork() int

fork will fork the current system process and return the pid of the fork.

fn from_slash(path string) string

from_slash returns the result of replacing each slash (/) character is path with a separator character.

fn get_error_msg(code int) string

get_error_msg return error code representation in string.

fn get_line() string

get_line returns a one-line string from stdin

fn get_lines() []string

get_lines returns an array of strings read from from stdin. reading is stopped when an empty line is read.

fn get_lines_joined() string

get_lines_joined returns a string of the values read from from stdin. reading is stopped when an empty line is read.

fn get_raw_line() string

get_raw_line returns a one-line string from stdin along with '\n' if there is any.

fn get_raw_lines_joined() string

get_raw_lines_joined reads all input lines from stdin. It returns them as one large string. Note: unlike os.get_lines_joined, empty lines (that contain only \r\n or \n), will be present in the output. Reading is stopped, only on EOF of stdin.

fn get_raw_stdin() []u8

get_raw_stdin will get the raw input from stdin.

fn getegid() int

fn getenv(key string) string

getenv returns the value of the environment variable named by the key. If there is not one found, it returns an empty string ''.

fn getenv_opt(key string) ?string

getenv_opt returns the value of a given environment variable. Returns none if the environment variable does not exist.

fn geteuid() int

fn getgid() int

fn getpid() int

fn getppid() int

fn getuid() int

fn getwd() string

getwd returns the absolute path of the current directory.

fn glob(patterns ...string) ![]string

fn home_dir() string

home_dir returns path to the user's home directory.

fn hostname() !string

fn inode(path string) FileMode

inode returns the mode of the file/inode containing inode type and permission information it supports windows for regular files but it doesn't matter if you use owner, group or others when checking permissions on windows

fn input(prompt string) string

input returns a one-line string from stdin, after printing a prompt. Returns '' in case of an error (end of input).

fn input_opt(prompt string) ?string

input_opt returns a one-line string from stdin, after printing a prompt. Returns none in case of an error (end of input).

fn input_password(prompt string) !string

input_password prompts the user for a password-like secret. It disables the terminal echo during user input and resets it back to normal when done.

fn is_abs_path(path string) bool

is_abs_path returns true if the given path is absolute.

fn is_atty(fd int) int

is_atty returns 1 if the fd file descriptor is open and refers to a terminal

fn is_dir(path string) bool

is_dir returns a bool indicating whether the given path is a directory.

fn is_dir_empty(path string) bool

is_dir_empty will return a bool whether or not path is empty. Note that it will return true if path does not exist.

fn is_executable(path string) bool

is_executable returns true if path is executable. Warning: is_executable() is known to cause a TOCTOU vulnerability when used incorrectly (for more information: https://github.com/vlang/v/blob/master/vlib/os/README.md)

fn is_file(path string) bool

is_file returns a bool indicating whether the given path is a file.

fn is_link(path string) bool

is_link returns a boolean indicating whether path is a link. Warning: is_link() is known to cause a TOCTOU vulnerability when used incorrectly (for more information: https://github.com/vlang/v/blob/master/vlib/os/README.md)

fn is_main_thread() bool

is_main_thread returns whether the current thread is the main thread.

fn is_readable(path string) bool

is_readable returns true if path is readable. Warning: is_readable() is known to cause a TOCTOU vulnerability when used incorrectly (for more information: https://github.com/vlang/v/blob/master/vlib/os/README.md)

fn is_writable(path string) bool

is_writable returns true if path is writable. Warning: is_writable() is known to cause a TOCTOU vulnerability when used incorrectly (for more information: https://github.com/vlang/v/blob/master/vlib/os/README.md)

fn join_path(base string, dirs ...string) string

join_path joins any number of path elements into a single path, separating them with a platform-specific path_separator. Empty elements are ignored.

fn join_path_single(base string, elem string) string

join_path_single appends the elem after base, separated with a platform-specific path_separator. Empty elements are ignored.

fn last_error() IError

fn link(origin string, target string) !

fn log(s string)

log will print "os.log: "+s ...

fn loginname() !string

fn ls(path string) ![]string

fn mkdir(path string, params MkdirParams) !

mkdir creates a new directory with the specified path.

fn mkdir_all(opath string, params MkdirParams) !

mkdir_all will create a valid full path of all directories given in path.

fn mv(source string, target string) !

mv moves files or folders from src to dst.

fn mv_by_cp(source string, target string) !

mv_by_cp first copies the source file, and if it is copied successfully, deletes the source file. may be used when you are not sure that the source and target are on the same mount/partition.

fn new_process(filename string) &Process

new_process - create a new process descriptor

Note: new does NOT start the new process. That is done because you may want to customize it first, by calling different set_ methods on it. In order to start it, call p.run() or p.wait()

fn norm_path(path string) string

norm_path returns the normalized version of the given path by resolving backlinks (..), turning forward slashes into back slashes on a Windows system and eliminating:- references to current directories (.)

• redundant path separators
• the last path separator

fn open(path string) !File

open tries to open a file from a given path for reading.

fn open_append(path string) !File

open_append tries to open a file from a given path. If successful, it and returns a File for appending.

fn open_file(path string, mode string, options ...int) !File

open_file tries to open or create a file with custom flags and permissions.

fn open_uri(uri string) !

open_uri opens a given uri.

fn page_size() int

page_size returns the page size in bytes.

fn posix_get_error_msg(code int) string

posix_get_error_msg return error code representation in string.

fn posix_set_permission_bit(path_s string, mode u32, enable bool)

Turns the given bit on or off, depending on the enable parameter

fn quoted_path(path string) string

quoted path - return a quoted version of the path, depending on the platform.

fn raw_execute(cmd string) Result

raw_execute does the same as execute on Unix platforms. On Windows raw_execute starts the specified command, waits for it to complete, and returns its output. It's marked as unsafe to help emphasize the problems that may arise by allowing, for example, user provided escape sequences.

fn read_bytes(path string) ![]u8

read_bytes returns all bytes read from file in path.

fn read_file(path string) !string

read_file reads the file in path and returns the contents.

fn read_file_array[T](path string) []T

read_file_array reads an array of T values from file path.

fn read_lines(path string) ![]string

read_lines reads the file in path into an array of lines.

fn real_path(fpath string) string

real_path returns the full absolute path for fpath, with all relative ../../, symlinks and so on resolved. See http://pubs.opengroup.org/onlinepubs/9699919799/functions/realpath.html Also https://insanecoding.blogspot.com/2007/11/pathmax-simply-isnt.html and https://insanecoding.blogspot.com/2007/11/implementing-realpath-in-c.html

Note: this particular rabbit hole is deep ...

fn rename(src string, dst string) !

rename renames the file or folder from src to dst. Use mv to move or rename a file in a platform independent manner.

fn rename_dir(src string, dst string) !

rename_dir renames the folder from src to dst. Use mv to move or rename a file in a platform independent manner.

fn resource_abs_path(path string) string

resource_abs_path returns an absolute path, for the given path. (the path is expected to be relative to the executable program) See https://discordapp.com/channels/592103645835821068/592294828432424960/630806741373943808 It gives a convenient way to access program resources like images, fonts, sounds and so on, no matter how the program was started, and what is the current working directory.

fn rm(path string) !

rm removes file in path.

fn rmdir(path string) !

rmdir removes a specified directory.

fn rmdir_all(path string) !

rmdir_all recursively removes the specified directory.

fn setenv(name string, value string, overwrite bool) int

os.setenv sets the value of an environment variable with name to value.

fn sigint_to_signal_name(si int) string

sigint_to_signal_name will translate si signal integer code to it's string code representation.

fn signal_ignore(args ...Signal)

signal_ignore to mask system signals, e.g.: signal_ignore(.pipe, .urg, ...)

fn signal_opt(signum Signal, handler SignalHandler) !SignalHandler

signal will assign handler callback to be called when signum signal is received.

fn stderr() File

stderr - return an os.File for stderr

fn stdin() File

stdin - return an os.File for stdin

fn stdout() File

stdout - return an os.File for stdout

fn symlink(origin string, target string) !

fn system(cmd string) int

system works like exec, but only returns a return code.

fn temp_dir() string

temp_dir returns the path to a folder, that is suitable for storing temporary files.

fn to_slash(path string) string

to_slash returns the result of replacing each separator character in path with a slash (/).

fn truncate(path string, len u64) !

truncate changes the size of the file located in path to len. Note that changing symbolic links on Windows only works as admin.

fn uname() Uname

uname returns information about the platform on which the program is running For example: os.Uname{ sysname: 'Linux' nodename: 'nemesis' release: '5.15.0-57-generic' version: '#63~20.04.1-Ubuntu SMP Wed Nov 30 13:40:16 UTC 2022' machine: 'x86_64' } where the fields have the following meaning: sysname is the name of this implementation of the operating system nodename is the name of this node within an implementation-dependent communications network release is the current release level of this implementation version is the current version level of this release machine is the name of the hardware type, on which the system is running See also https://pubs.opengroup.org/onlinepubs/7908799/xsh/sysutsname.h.html

fn unsetenv(name string) int

os.unsetenv clears an environment variable with name.

fn user_names() ![]string

user_names returns an array of the name of every user on the system.

fn user_os() string

user_os returns current user operating system name.

fn utime(path string, actime int, modtime int) !

fn vfopen(path string, mode string) !&C.FILE

vfopen returns an opened C file, given its path and open mode.

Note: os.vfopen is useful for compatibility with C libraries, that expect FILE *. If you write pure V code, os.create or os.open are more convenient.

fn vmodules_dir() string

vmodules_dir returns the path to a folder, where v stores its global modules.

fn vmodules_paths() []string

vmodules_paths returns a list of paths, where v looks up for modules. You can customize it through setting the environment variable VMODULES [manualfree]

fn vtmp_dir() string

vtmp_dir returns the path to a folder, that is writable to V programs, and specific to the OS user. It can be overridden by setting the env variable VTMP.

fn wait() int

wait blocks the calling process until one of its child processes exits or a signal is received. After child process terminates, parent continues its execution after wait system call instruction.

fn walk(path string, f fn (string))

walk traverses the given directory path. When a file is encountered, it will call the callback f with current file as argument.

Note: walk can be called even for deeply nested folders, since it does not recurse, but processes them iteratively.

fn walk_ext(path string, ext string) []string

walk_ext returns a recursive list of all files in path ending with ext.

fn walk_with_context(path string, context voidptr, fcb FnWalkContextCB)

walk_with_context traverses the given directory path. For each encountered file and directory, it will call your fcb callback, passing it the arbitrary context in its first parameter, and the path to the file in its second parameter.

Note: walk_with_context can be called even for deeply nested folders, since it does not recurse, but processes them iteratively.

fn write_file(path string, text string) !

write_file writes text data to the file in path. If path exists, the contents of path will be overwritten with the contents of text.

fn write_file_array(path string, buffer array) !

write_file_array writes the data in buffer to a file in path.

fn (p FilePermission) bitmask() u32

bitmask returns a 3 bit sequence in the order RWE where the bit is set to 1 if the value is true or 0 otherwise.

type FN_SA_Handler = fn (sig int)

type FnWalkContextCB = fn (voidptr, string)

FnWalkContextCB is used to define the callback functions, passed to os.walk_context

type SignalHandler = fn (Signal)

enum ChildProcessPipeKind {
	stdin
	stdout
	stderr
}

The kind of the pipe file descriptor, that is used for communicating with the child process

enum FileType {
	regular
	directory
	character_device
	block_device
	fifo
	symbolic_link
	socket
}

enum ProcessState {
	not_started
	running
	stopped
	exited
	aborted
	closed
}

• ProcessState.not_started - the process has not yet started
• ProcessState.running - the process is currently running
• ProcessState.stopped - the process was running, but was stopped temporarily
• ProcessState.exited - the process has finished/exited
• ProcessState.aborted - the process was terminated by a signal
• ProcessState.closed - the process resources like opened file descriptors were freed/discarded, final state.

enum SeekMode {
	start
	current
	end
}

enum Signal {
	hup    = 1
	int    = 2
	quit   = 3
	ill    = 4
	trap   = 5
	abrt   = 6
	bus    = 7
	fpe    = 8
	kill   = 9
	usr1   = 10
	segv   = 11
	usr2   = 12
	pipe   = 13
	alrm   = 14
	term   = 15
	stkflt = 16
	chld   = 17
	cont   = 18
	stop   = 19
	tstp   = 20
	ttin   = 21
	ttou   = 22
	urg    = 23
	xcpu   = 24
	xfsz   = 25
	vtalrm = 26
	prof   = 27
	winch  = 28
	poll   = 29
	pwr    = 30
	sys    = 31
}

os.Signal - enumerate possible POSIX signals and their integer codes.

Note: the integer codes are given here explicitly, to make it easier to lookup, without needing to consult man pages / signal.h .

struct C.__stat64 {
	st_mode  u32
	st_size  u64
	st_mtime u64
}

struct C.dirent {
	d_name [256]char
}

struct C.fd_set {}

struct C.sigaction {
mut:
	sa_mask      int
	sa_sigaction int
	sa_flags     int
	sa_handler   FN_SA_Handler
}

struct C.stat {
	st_dev     u64 // 8
	st_ino     u64 // 8
	st_nlink   u64 // 8
	st_mode    u32 // 4
	st_uid     u32 // 4
	st_gid     u32 // 4
	st_rdev    u64 // 8
	st_size    u64 // 8
	st_blksize u64 // 8
	st_blocks  u64 // 8
	st_atime   i64 // 8
	st_mtime   i64 // 8
	st_ctime   i64 // 8
}

struct C.timeval {
	tv_sec  u64
	tv_usec u64
}

struct C.utimbuf {
	actime  int
	modtime int
}

struct C.utsname {
mut:
	sysname  &char
	nodename &char
	release  &char
	version  &char
	machine  &char
}

struct Command {
mut:
	f voidptr
pub mut:
	eof       bool
	exit_code int
pub:
	path            string
	redirect_stdout bool
}

fn (mut c Command) close() !

fn (mut c Command) read_line() string

fn (mut c Command) start() !

struct Eof {
	Error
}

/ Eof error means that we reach the end of the file.

struct ExecutableNotFoundError {
	Error
}

fn (err ExecutableNotFoundError) msg() string

struct File {
mut:
	cfile voidptr // Using void* instead of FILE*
pub:
	fd int
pub mut:
	is_opened bool
}

fn (mut f File) close()

fn (f &File) eof() bool

eof returns true, when the end of file has been reached

fn (mut f File) flush()

flush writes any buffered unwritten data left in the file stream.

fn (f &File) read(mut buf []u8) !int

read implements the Reader interface.

fn (f &File) read_bytes(size int) []u8

read_bytes reads bytes from the beginning of the file. Utility method, same as .read_bytes_at(size, 0).

fn (f &File) read_bytes_at(size int, pos u64) []u8

read_bytes_at reads size bytes at the given position in the file.

fn (f &File) read_bytes_into(pos u64, mut buf []u8) !int

read_bytes_into fills buf with bytes at the given position in the file. buf must have length greater than zero. Returns the number of read bytes, or an error.

fn (f &File) read_bytes_into_newline(mut buf []u8) !int

read_bytes_into_newline reads from the beginning of the file into the provided buffer. Each consecutive call on the same file continues reading where it previously ended. A read call is either stopped, if the buffer is full, a newline was read or EOF.

fn (f &File) read_from(pos u64, mut buf []u8) !int

read_from implements the RandomReader interface.

fn (f &File) read_into_ptr(ptr &u8, max_size int) !int

read_into_ptr reads at most max_size bytes from the file and writes it into ptr. Returns the amount of bytes read or an error.

fn (mut f File) read_raw[T]() !T

read_raw reads and returns a single instance of type T

fn (mut f File) read_raw_at[T](pos u64) !T

read_raw_at reads and returns a single instance of type T starting at file byte offset pos

fn (mut f File) read_struct[T](mut t T) !

read_struct reads a single struct of type T

fn (mut f File) read_struct_at[T](mut t T, pos u64) !

read_struct_at reads a single struct of type T at position specified in file

fn (mut f File) reopen(path string, mode string) !

reopen allows a File to be reused. It is mostly useful for reopening standard input and output.

fn (mut f File) seek(pos i64, mode SeekMode) !

seek moves the file cursor (if any) associated with a file to a new location, offset pos bytes from the origin. The origin is dependent on the mode and can be: .start -> the origin is the start of the file .current -> the current position/cursor in the file .end -> the end of the file If the file is not seek-able, or an error occurs, the error will be returned to the caller. A successful call to the fseek() function clears the end-of-file indicator for the file.

fn (f &File) tell() !i64

tell will return the current offset of the file cursor measured from the start of the file, in bytes. It is complementary to seek, i.e. you can use the return value as the pos parameter to .seek( pos, .start ), so that your next read will happen from the same place.

fn (mut f File) write(buf []u8) !int

write implements the Writer interface. It returns how many bytes were actually written.

fn (mut f File) write_full_buffer(buffer voidptr, buffer_len usize) !

write_full_buffer writes a whole buffer of data to the file, starting from the address in buffer, no matter how many tries/partial writes it would take.

fn (mut f File) write_ptr(data voidptr, size int) int

write_ptr writes size bytes to the file, starting from the address in data.

Note: write_ptr is unsafe and should be used carefully, since if you pass invalid pointers to it, it will cause your programs to segfault.

fn (mut f File) write_ptr_at(data voidptr, size int, pos u64) int

write_ptr_at writes size bytes to the file, starting from the address in data, at byte offset pos, counting from the start of the file (pos 0).

Note: write_ptr_at is unsafe and should be used carefully, since if you pass invalid pointers to it, it will cause your programs to segfault.

fn (mut f File) write_raw[T](t &T) !

write_raw writes a single instance of type T

fn (mut f File) write_raw_at[T](t &T, pos u64) !

write_raw_at writes a single instance of type T starting at file byte offset pos

fn (mut f File) write_string(s string) !int

write_string writes the string s into the file It returns how many bytes were actually written.

fn (mut f File) write_struct[T](t &T) !

write_struct writes a single struct of type T

fn (mut f File) write_struct_at[T](t &T, pos u64) !

write_struct_at writes a single struct of type T at position specified in file

fn (mut f File) write_to(pos u64, buf []u8) !int

write_to implements the RandomWriter interface. It returns how many bytes were actually written. It resets the seek position to the end of the file.

fn (mut f File) writeln(s string) !int

writeln writes the string s into the file, and appends a \n character. It returns how many bytes were written, including the \n character.

struct FileMode {
pub:
	typ    FileType
	owner  FilePermission
	group  FilePermission
	others FilePermission
}

fn (m FileMode) bitmask() u32

bitmask returns a 9 bit sequence in the order owner + group + others. This is a valid bitmask to use with os.chmod.

struct FileNotOpenedError {
	Error
}

fn (err FileNotOpenedError) msg() string

struct MkdirParams {
	mode u32 = 0o777 // note that the actual mode is affected by the process's umask
}

struct NotExpected {
	cause string
	code  int
}

NotExpected is a generic error that means that we receave a not expected error.

struct Process {
pub mut:
	filename string // the process's command file path
	pid      int    // the PID of the process
	code     int = -1
	// the exit code of the process, != -1 *only* when status is .exited *and* the process was not aborted
	status ProcessState = .not_started
	// the current status of the process
	err              string   // if the process fails, contains the reason why
	args             []string // the arguments that the command takes
	work_folder      string   // the initial working folder of the process. When '', reuse the same folder as the parent process.
	env_is_custom    bool     // true, when the environment was customized with .set_environment
	env              []string // the environment with which the process was started  (list of 'var=val')
	use_stdio_ctl    bool     // when true, then you can use p.stdin_write(), p.stdout_slurp() and p.stderr_slurp()
	use_pgroup       bool     // when true, the process will create a new process group, enabling .signal_pgkill()
	stdio_fd         [3]int   // the stdio file descriptors for the child process, used only by the nix implementation
	wdata            voidptr  // the WProcess; used only by the windows implementation
	create_no_window bool     // sets a value indicating whether to start the process in a new window, The default is false; used only by the windows implementation
}

fn (mut p Process) close()

close - free the OS resources associated with the process. Can be called multiple times, but will free the resources just once. This sets the process state to .closed, which is final.

fn (mut p Process) free()

fn (mut p Process) is_alive() bool

is_alive - query whether the process p.pid is still alive

fn (mut p Process) is_pending(pkind ChildProcessPipeKind) bool

is_pending returns whether there is data to be read from child process's pipe corresponding to pkind. For example if p.is_pending(.stdout) { dump( p.stdout_read() ) } will not block indefinitely.

fn (mut p Process) pipe_read(pkind ChildProcessPipeKind) ?string

pipe_read reads a block of data, from the given pipe of the child process. It will return none, if there is no data to be read, without blocking.

fn (mut p Process) run()

run - starts the new process

fn (mut p Process) set_args(pargs []string)

set_args - set the arguments for the new process

fn (mut p Process) set_environment(envs map[string]string)

set_environment - set a custom environment variable mapping for the new process

fn (mut p Process) set_redirect_stdio()

fn (mut p Process) set_work_folder(path string)

set_work_folder - set the initial working folder for the new process If you do not set it, it will reuse the current working folder of the parent process.

fn (mut p Process) signal_continue()

signal_continue - tell a stopped process to continue/resume its work

fn (mut p Process) signal_kill()

signal_kill - kills the process, after that it is no longer running

fn (mut p Process) signal_pgkill()

signal_pgkill - kills the whole process group

fn (mut p Process) signal_stop()

signal_stop - stops the process, you can resume it with p.signal_continue()

fn (mut p Process) stderr_read() string

stderr_read reads a block of data, from the stderr pipe of the child process. It will block, if there is no data to be read. Call .is_pending() to check if there is data to be read, if you do not want to block.

fn (mut p Process) stderr_slurp() string

stderr_slurp will read from the stderr pipe, and will block until it either reads all the data, or until the pipe is closed (end of file).

fn (mut p Process) stdin_write(s string)

stdin_write will write the string s, to the stdin pipe of the child process.

fn (mut p Process) stdout_read() string

stdout_read reads a block of data, from the stdout pipe of the child process. It will block, if there is no data to be read. Call .is_pending() to check if there is data to be read, if you do not want to block.

fn (mut p Process) stdout_slurp() string

stdout_slurp will read from the stdout pipe, and will block until it either reads all the data, or until the pipe is closed (end of file).

fn (mut p Process) wait()

wait - wait for a process to finish.

Note: You have to call p.wait(), otherwise a finished process would get to a zombie state, and its resources will not get released fully, until its parent process exits.

Note: This call will block the calling process until the child process is finished.

struct Result {
pub:
	exit_code int
	output    string
	// stderr string // TODO
}

fn (mut result Result) free()

struct SizeOfTypeIs0Error {
	Error
}

fn (err SizeOfTypeIs0Error) msg() string

struct Uname {
pub mut:
	sysname  string
	nodename string
	release  string
	version  string
	machine  string
}