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. See: https://specifications.freedesktop.org/basedir-spec/latest/ . There is a single base directory relative to which user-specific non-essential (cached) data should be written. This directory is defined by the environment variable $XDG_CACHE_HOME. $XDG_CACHE_HOME defines the base directory relative to which user specific non-essential data files should be stored. If $XDG_CACHE_HOME is either not set or empty, a default equal to $HOME/.cache should be used.

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 data_dir() string

data_dir returns the path to a writable user-specific folder, suitable for writing application data. See: https://specifications.freedesktop.org/basedir-spec/latest/ . There is a single base directory relative to which user-specific data files should be written. This directory is defined by the environment variable $XDG_DATA_HOME. If $XDG_DATA_HOME is either not set or empty, a default equal to $HOME/.local/share should be used.

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 error_posix(e SystemError) IError

Return a POSIX error: Code defaults to last error (from C.errno) Message defaults to POSIX error message for the error code

fn error_win32(e SystemError) IError

Return a Win32 API error: Code defaults to last error (calling C.GetLastError()) Message defaults to Win 32 API error message for the error code

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 in bytes, 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(exe_name string) !string

find_abs_path_of_executable searches the environment PATH for the absolute path of the given executable name.

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 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 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 the path to the current user's home directory.

fn hostname() !string

fn inode(path string) FileInfo

inode returns the metadata of the file/inode, containing inode type, permission information, size and modification time. it supports windows for regular files, but it doesn't matter if you use owner, group or others when checking permissions on windows. if a symlink is targeted, it returns info on the link, not the target

fn input(prompt string) string

input returns a one-line string from stdin, after printing a prompt. Returns EOF 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. Windows platform output will rewrite forward slashes to backslash. Consider looking at the unit tests in os_test.v for semi-formal API.

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

last_error returns a V error, formed by the last libc error (from GetLastError() on windows and from errno on !windows)

fn link(origin string, target string) !

fn local_bin_dir() string

local_bin_dir returns $HOME/.local/bin, which is guaranteed to be in the PATH of the current user, for distributions, following the XDG spec from https://specifications.freedesktop.org/basedir-spec/latest/ : > User-specific executable files may be stored in $HOME/.local/bin . > Distributions should ensure this directory shows up in the UNIX $PATH environment variable, at an appropriate place.

fn log(s string)

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

fn loginname() !string

fn ls(path string) ![]string

  entries := os.ls(os.home_dir()) or { [] }
  for entry in entries {
    if os.is_dir(os.join_path(os.home_dir(), entry)) {
      println('dir: $entry')
    } else {
      println('file: $entry')
    }
  }

https://github.com/vlang/v/blob/master/examples/readdir.v

fn lstat(path string) !Stat

lstat returns a platform-agnostic Stat struct comparable to what is available in other programming languages and fails with the POSIX error if the stat call fails. If a link is stat'd, the stat info for the link is provided.

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, opts MvParams) !

mv moves files or folders from src to dst.

fn mv_by_cp(source string, target string, opts MvParams) !

mv_by_cp copies files or folders from source to target. If copying is successful, source is deleted. It may be used when the paths are not 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 stat(path string) !Stat

stat returns a platform-agnostic Stat struct comparable to what is available in other programming languages and fails with the POSIX error if the stat call fails. Symlinks are followed and the resulting Stat provided. (If this is not desired, use lstat().)

fn state_dir() string

state_dir returns a writable folder user-specific folder, suitable for storing state data, that should persist between (application) restarts, but that is not important or portable enough to the user that it should be stored in os.data_dir() . See: https://specifications.freedesktop.org/basedir-spec/latest/ . $XDG_STATE_HOME defines the base directory relative to which user-specific state files should be stored. If $XDG_STATE_HOME is either not set or empty, a default equal to $HOME/.local/state should be used. It may contain:* actions history (logs, history, recently used files, …)

• current state of the application that can be reused on a restart (view, layout, open files, undo history, …)

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 containing the names of all users on the system.

fn user_os() string

user_os returns the current user's 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. For listing only one level deep, see: os.ls

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

walk_ext returns a recursive list of all files in path ending with ext. For listing only one level deep, see: os.ls

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. For listing only one level deep, see: os.ls

fn write_file(path string, text string) !

write_file writes text data to a file with the given path. If path already exists, it will be overwritten.

fn write_file_array(path string, buffer array) !

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

fn write_lines(path string, lines []string) !

write_lines writes the given array of lines to path. The lines are separated by \n .

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 FileBufferMode {
	fully_buffered = C._IOFBF // many characters are saved up and written as a block
	line_buffered  = C._IOLBF // characters are saved up until a newline is output or input is read from any stream attached to a terminal device (typically stdin)
	not_buffered   = C._IONBF // information appears on the destination file or terminal as soon as it is written
}

FileBufferMode describes the available buffering modes for an os.File: unbuffered, line buffered and block/fully buffered. Normally all files are block buffered. If a stream refers to a terminal (as stdout normally does), it is line buffered. The standard error stream stderr is always unbuffered by default.

enum FileType {
	unknown
	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  // hangup
	int    = 2  // interrupt from keyboard
	quit   = 3  // quit from keyboard
	ill    = 4  // illegal instruction
	trap   = 5  // trace trap
	abrt   = 6  // abort
	bus    = 7  // bus error
	fpe    = 8  // floating point exception
	kill   = 9  // kill signal
	usr1   = 10 // user-defined signal 1
	segv   = 11 // segmentation violation
	usr2   = 12 // user-defined signal 2
	pipe   = 13 // write on a pipe with no one to read it
	alrm   = 14 // alarm clock
	term   = 15 // software termination signal
	stkflt = 16 // stack fault
	chld   = 17 // child process has stopped or exited
	cont   = 18 // continue executing, if stopped
	stop   = 19 // stop executing (cannot be caught or ignored)
	tstp   = 20 // stop executing, can be caught and ignored
	ttin   = 21 // terminal input for background process
	ttou   = 22 // terminal output for background process
	urg    = 23 // urgent condition on socket
	xcpu   = 24 // CPU time limit exceeded
	xfsz   = 25 // file size limit exceeded
	vtalrm = 26 // virtual time alarm
	prof   = 27 // profiling timer alarm
	winch  = 28 // window size change
	poll   = 29 // pollable event occurred
	pwr    = 30 // power failure
	sys    = 31 // bad system call
}

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.timespec {
pub mut:
	tv_sec  i64
	tv_nsec i64
}

struct C.timeval {
pub:
	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 size 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 current position of the file into the provided buffer.

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

read_bytes_with_newline reads from the current position of the file into the provided buffer. Each consecutive call on the same file, continues reading, from where it previously ended. A read call is either stopped, if the buffer is full, a newline was read or EOF. On EOF, the method returns 0. The methods will also return any IO error encountered.

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 (mut f File) set_buffer(mut buffer []u8, mode FileBufferMode) int

set_buffer sets the buffer for the file, and the file buffering mode (see also os.FileBufferMode). Unlike File.setvbuf, it allows you to pass an existing V []u8 array directly.

Note: f.set_buffer() may be used only after opening a file stream, and before any other operations have been performed on it.

fn (mut f File) set_line_buffered()

set_line_buffered sets the file buffering mode to FileBufferMode.line_buffered.

Note: f.set_line_buffered() may be used only after opening a file stream, and before any other operations have been performed on it.

fn (mut f File) set_unbuffered()

set_unbuffered sets the file buffering mode to FileBufferMode.not_buffered.

Note: f.set_unbuffered() may be used only after opening a file stream, and before any other operations have been performed on it.

fn (mut f File) setvbuf(buffer &char, mode FileBufferMode, size usize) int

setvbuf sets the buffer and buffering mode for the given file f. See also os.FileBufferMode. It returns 0 on success. It returns nonzero on failure (the mode is invalid, or the request cannot be honored). Except for unbuffered files, the buffer argument should point to a buffer at least size bytes long; this buffer will be used instead of the current buffer. If the argument buffer is nil, only the mode is affected; a new buffer will be allocated on the next read or write operation.

Note: make sure, that the space, that buffer points to (when != 0), still exists by the time the file stream is closed, which also happens at program termination.

Note: f.setvbuf() may be used only after opening a file stream, and before any other operations have been performed on it.

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. The size in bytes, of the buffer, should be passed in buffer_len.

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 file byte offset pos.

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 FileInfo {
	FileMode
pub:
	size  u64 // size of the file in bytes
	mtime i64 // last modification time in seconds after the Unix epoch
}

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 FilePermission {
pub:
	read    bool
	write   bool
	execute bool
}

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.

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

struct MvParams {
pub:
	overwrite bool = true
}

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) signal_term()

signal_term - terminate the process

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 Stat {
pub:
	dev   u64 // ID of device containing file
	inode u64 // Inode number
	mode  u32 // File type and user/group/world permission bits
	nlink u64 // Number of hard links to file
	uid   u32 // Owner user ID
	gid   u32 // Owner group ID
	rdev  u64 // Device ID (if special file)
	size  u64 // Total size in bytes
	atime i64 // Last access (seconds since UNIX epoch)
	mtime i64 // Last modified (seconds since UNIX epoch)
	ctime i64 // Last status change (seconds since UNIX epoch)
}

Stat struct modeled on POSIX

fn (st Stat) get_filetype() FileType

get_filetype returns the FileType from the Stat struct

fn (st Stat) get_mode() FileMode

get_mode returns the file type and permissions (readable, writable, executable) in owner/group/others format

struct SystemError {
pub:
	msg  string
	code int = error_code_not_set
}

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