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
Possibility for TOCTOU attack
|
TOCTOU not possible
|
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()
Constants #
const (
args = []string{}
)
const max_path_len = 4096
const wd_at_startup = getwd()
const (
sys_write = 1
sys_open = 2
sys_close = 3
sys_mkdir = 83
sys_creat = 85
)
const (
path_separator = '/'
path_delimiter = ':'
)
const (
s_ifmt = 0xF000 // type of file
s_ifdir = 0x4000 // directory
s_iflnk = 0xa000 // link
s_isuid = 0o4000 // SUID
s_isgid = 0o2000 // SGID
s_isvtx = 0o1000 // Sticky
s_irusr = 0o0400 // Read by owner
s_iwusr = 0o0200 // Write by owner
s_ixusr = 0o0100 // Execute by owner
s_irgrp = 0o0040 // Read by group
s_iwgrp = 0o0020 // Write by group
s_ixgrp = 0o0010 // Execute by group
s_iroth = 0o0004 // Read by others
s_iwoth = 0o0002 // Write by others
s_ixoth = 0o0001 // Execute by others
)
(Must be realized in Syscall) (Must be specified) ref: http://www.ccfit.nsu.ru/~deviv/courses/unix/unix/ng7c229.html
fn abs_path #
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 #
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 #
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 #
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 #
fn cache_dir() string
cache_dir returns the path to a writable user specific folder, suitable for writing non-essential data.
fn chdir #
fn chdir(path string) !
chdir changes the current working directory to the new directory in path
.
fn chmod #
fn chmod(path string, mode int) !
chmod change file access attributes of path
to mode
.
Octals like 0o600
can be used.
fn chown #
fn chown(path string, owner int, group int) !
chown changes the owner and group attributes of path
to owner
and group
.
fn config_dir #
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 #
fn cp(src string, dst string) !
cp copies files or folders from src
to dst
.
fn cp_all #
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 #
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 #
fn debugger_present() bool
debugger_present returns a bool indicating if the process is being debugged
fn dir #
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 #
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 #
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 #
fn executable() string
executable returns the path name of the executable that started the current process.
fn execute #
fn execute(cmd string) Result
execute starts the specified command, waits for it to complete, and returns its output.
fn execute_or_exit #
fn execute_or_exit(cmd string) Result
fn execute_or_panic #
fn execute_or_panic(cmd string) Result
fn execve #
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 successfull, since
the child process will take control over execution.
fn execvp #
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 successfull, since
the child process will take control over execution.
fn existing_path #
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 #
fn exists(path string) bool
exists returns true if path
(file or directory) exists.
fn exists_in_system_path #
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 #
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 #
fn fd_close(fd int) int
close filedescriptor
fn fd_read #
fn fd_read(fd int, maxbytes int) (string, int)
read from filedescriptor, don't block return [bytestring,nrbytes]
fn fd_slurp #
fn fd_slurp(fd int) []string
read from filedescriptor, block until data
fn fd_write #
fn fd_write(fd int, s string)
fn file_ext #
fn file_ext(opath string) string
file_ext will return the part after the last occurence 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 #
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 #
fn file_name(opath string) string
file_name will return all characters found after the last occurence of path_separator
.
file extension is included.
fn file_size #
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 #
fn fileno(cfile voidptr) int
fileno returns the file descriptor of an opened C file.
fn find_abs_path_of_executable #
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 #
fn flush()
flush will flush the stdout buffer.
fn fork #
fn fork() int
fork will fork the current system process and return the pid of the fork.
fn from_slash #
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 #
fn get_error_msg(code int) string
get_error_msg return error code representation in string.
fn get_line #
fn get_line() string
get_line returns a one-line string from stdin
fn get_lines #
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 #
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 #
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 #
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 #
fn get_raw_stdin() []u8
get_raw_stdin will get the raw input from stdin.
fn getegid #
fn getegid() int
fn getenv #
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 #
fn getenv_opt(key string) ?string
getenv_opt
returns the value of the environment variable named by the key
If there is not one found, it returns none
.
fn geteuid #
fn geteuid() int
fn getgid #
fn getgid() int
fn getpid #
fn getpid() int
fn getppid #
fn getppid() int
fn getuid #
fn getuid() int
fn getwd #
fn getwd() string
getwd returns the absolute path of the current directory.
fn glob #
fn glob(patterns ...string) ![]string
fn home_dir #
fn home_dir() string
home_dir returns path to the user's home directory.
fn hostname #
fn hostname() !string
fn inode #
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 #
fn input(prompt string) string
input returns a one-line string from stdin, after printing a prompt.
In the event of error (end of input), it returns '<EOF>'.
fn input_opt #
fn input_opt(prompt string) ?string
input_opt returns a one-line string from stdin, after printing a prompt.
In the event of error (end of input), it returns none
.
fn input_password #
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 #
fn is_abs_path(path string) bool
is_abs_path returns true
if the given path
is absolute.
fn is_atty #
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 #
fn is_dir(path string) bool
is_dir returns a bool
indicating whether the given path
is a directory.
fn is_dir_empty #
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 #
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 #
fn is_file(path string) bool
is_file returns a bool
indicating whether the given path
is a file.
fn is_link #
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_readable #
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 #
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 is_writable_folder #
fn is_writable_folder(folder string) !bool
fn join_path #
fn join_path(base string, dirs ...string) string
join_path returns a path as string from input string parameter(s).
fn join_path_single #
fn join_path_single(base string, elem string) string
join_path_single appends the elem
after base
, using a platform specific
path_separator.
fn last_error #
fn last_error() IError
fn link #
fn link(origin string, target string) !
fn log #
fn log(s string)
log will print "os.log: "+s
...
fn loginname #
fn loginname() !string
fn ls #
fn ls(path string) ![]string
fn mkdir #
fn mkdir(path string, params MkdirParams) !
mkdir creates a new directory with the specified path.
fn mkdir_all #
fn mkdir_all(opath string, params MkdirParams) !
mkdir_all will create a valid full path of all directories given in path
.
fn mv #
fn mv(source string, target string) !
mv moves files or folders from src
to dst
.
fn mv_by_cp #
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 #
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 #
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 #
fn open(path string) !File
open tries to open a file for reading and returns back a read-only File
object.
fn open_append #
fn open_append(path string) !File
open_append opens path
file for appending.
fn open_file #
fn open_file(path string, mode string, options ...int) !File
open_file can be used to open or create a file with custom flags and permissions and returns a File
object.
fn open_uri #
fn open_uri(uri string) !
fn posix_get_error_msg #
fn posix_get_error_msg(code int) string
posix_get_error_msg return error code representation in string.
fn posix_set_permission_bit #
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 #
fn quoted_path(path string) string
quoted path - return a quoted version of the path, depending on the platform.
fn raw_execute #
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 #
fn read_bytes(path string) ![]u8
read_bytes returns all bytes read from file in path
.
fn read_file #
fn read_file(path string) !string
read_file reads the file in path
and returns the contents.
fn read_file_array #
fn read_file_array[T](path string) []T
read_file_array reads an array of T
values from file path
.
fn read_lines #
fn read_lines(path string) ![]string
read_lines reads the file in path
into an array of lines.
fn real_path #
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 #
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 #
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 #
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 #
fn rm(path string) !
rm removes file in path
.
fn rmdir #
fn rmdir(path string) !
rmdir removes a specified directory.
fn rmdir_all #
fn rmdir_all(path string) !
rmdir_all recursively removes the specified directory.
fn setenv #
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 #
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_opt #
fn signal_opt(signum Signal, handler SignalHandler) !SignalHandler
signal will assign handler
callback to be called when signum
signal is received.
fn stderr #
fn stderr() File
stderr - return an os.File for stderr
fn stdin #
fn stdin() File
stdin - return an os.File for stdin
fn stdout #
fn stdout() File
stdout - return an os.File for stdout
fn symlink #
fn symlink(origin string, target string) !
fn system #
fn system(cmd string) int
system works like exec
, but only returns a return code.
fn temp_dir #
fn temp_dir() string
temp_dir returns the path to a folder, that is suitable for storing temporary files.
fn to_slash #
fn to_slash(path string) string
to_slash returns the result of replacing each separator character
in path with a slash (/
).
fn truncate #
fn truncate(path string, len u64) !
***************************** OS ops ************************
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 #
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 #
fn unsetenv(name string) int
os.unsetenv clears an environment variable with name
.
fn user_names #
fn user_names() ![]string
user_names returns an array of the name of every user on the system.
fn user_os #
fn user_os() string
user_os returns current user operating system name.
fn utime #
fn utime(path string, actime int, modtime int) !
fn vfopen #
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 #
fn vmodules_dir() string
vmodules_dir returns the path to a folder, where v stores its global modules.
fn vmodules_paths #
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 #
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 #
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 #
fn walk(path string, f fn (string))
walk traverses the given directory path
.
When a file is encountred, 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 #
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 #
fn walk_with_context(path string, context voidptr, fcb FnWalkContextCB)
walk_with_context traverses the given directory path
.
For each encountred 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 #
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 #
fn write_file_array(path string, buffer array) !
write_file_array writes the data in buffer
to a file in path
.
fn (FilePermission) bitmask #
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 #
type FN_SA_Handler = fn (sig int)
type FnWalkContextCB #
type FnWalkContextCB = fn (voidptr, string)
FnWalkContextCB is used to define the callback functions, passed to os.walk_context
type SignalHandler #
type SignalHandler = fn (Signal)
enum FileType #
enum FileType {
regular
directory
character_device
block_device
fifo
symbolic_link
socket
}
enum ProcessState #
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 #
enum SeekMode {
start
current
end
}
enum Signal #
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.stat #
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 Command #
struct Command {
mut:
f voidptr
pub mut:
eof bool
exit_code int
pub:
path string
redirect_stdout bool
}
fn (Command) close #
fn (mut c Command) close() !
fn (Command) read_line #
fn (mut c Command) read_line() string
fn (Command) start #
fn (mut c Command) start() !
struct Eof #
struct Eof {
Error
}
/ Eof error means that we reach the end of the file.
struct ExecutableNotFoundError #
struct ExecutableNotFoundError {
Error
}
fn (ExecutableNotFoundError) msg #
fn (err ExecutableNotFoundError) msg() string
struct File #
struct File {
mut:
cfile voidptr // Using void* instead of FILE*
pub:
fd int
pub mut:
is_opened bool
}
fn (File) close #
fn (mut f File) close()
fn (File) eof #
fn (f &File) eof() bool
eof returns true, when the end of file has been reached
fn (File) flush #
fn (mut f File) flush()
**************************** Utility ops *********************** flush writes any buffered unwritten data left in the file stream.
fn (File) read #
fn (f &File) read(mut buf []u8) !int
read implements the Reader interface.
fn (File) read_bytes #
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 (File) read_bytes_at #
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 (File) read_bytes_into #
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 (File) read_bytes_into_newline #
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 (File) read_from #
fn (f &File) read_from(pos u64, mut buf []u8) !int
read_from implements the RandomReader interface.
fn (File) read_into_ptr #
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 (File) read_raw #
fn (mut f File) read_raw[T]() !T
read_raw reads and returns a single instance of type T
fn (File) read_raw_at #
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 (File) read_struct #
fn (mut f File) read_struct[T](mut t T) !
read_struct reads a single struct of type T
fn (File) read_struct_at #
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 (File) reopen #
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 (File) seek #
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 occures, 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 (File) tell #
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 (File) write #
fn (mut f File) write(buf []u8) !int
**************************** Write ops ***************************
write implements the Writer interface.
It returns how many bytes were actually written.
fn (File) write_full_buffer #
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 (File) write_ptr #
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 (File) write_ptr_at #
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 (File) write_raw #
fn (mut f File) write_raw[T](t &T) !
write_raw writes a single instance of type T
fn (File) write_raw_at #
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 (File) write_string #
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 (File) write_struct #
fn (mut f File) write_struct[T](t &T) !
write_struct writes a single struct of type T
fn (File) write_struct_at #
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 (File) write_to #
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 (File) writeln #
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 #
struct FileMode {
pub:
typ FileType
owner FilePermission
group FilePermission
others FilePermission
}
fn (FileMode) bitmask #
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 #
struct FileNotOpenedError {
Error
}
fn (FileNotOpenedError) msg #
fn (err FileNotOpenedError) msg() string
struct MkdirParams #
struct MkdirParams {
mode u32 = 0o777 // note that the actual mode is affected by the process's umask
}
struct NotExpected #
struct NotExpected {
cause string
code int
}
NotExpected is a generic error that means that we receave a not expecte error.
struct Process #
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 (Process) close #
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 (Process) free #
fn (mut p Process) free()
fn (Process) is_alive #
fn (mut p Process) is_alive() bool
is_alive - query whether the process p.pid is still alive
fn (Process) run #
fn (mut p Process) run()
run - starts the new process
fn (Process) set_args #
fn (mut p Process) set_args(pargs []string)
set_args - set the arguments for the new process
fn (Process) set_environment #
fn (mut p Process) set_environment(envs map[string]string)
set_environment - set a custom environment variable mapping for the new process
fn (Process) set_redirect_stdio #
fn (mut p Process) set_redirect_stdio()
fn (Process) set_work_folder #
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 (Process) signal_continue #
fn (mut p Process) signal_continue()
signal_continue - tell a stopped process to continue/resume its work
fn (Process) signal_kill #
fn (mut p Process) signal_kill()
signal_kill - kills the process, after that it is no longer running
fn (Process) signal_pgkill #
fn (mut p Process) signal_pgkill()
signal_pgkill - kills the whole process group
fn (Process) signal_stop #
fn (mut p Process) signal_stop()
signal_stop - stops the process, you can resume it with p.signal_continue()
fn (Process) stderr_read #
fn (mut p Process) stderr_read() string
fn (Process) stderr_slurp #
fn (mut p Process) stderr_slurp() string
read from stderr pipe, wait for data or EOF
fn (Process) stdin_write #
fn (mut p Process) stdin_write(s string)
fn (Process) stdout_read #
fn (mut p Process) stdout_read() string
read from stdout, return if data or not
fn (Process) stdout_slurp #
fn (mut p Process) stdout_slurp() string
will read from stdout pipe, will only return when EOF (end of file) or data means this will block unless there is data
fn (Process) wait #
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 #
struct Result {
pub:
exit_code int
output string
// stderr string // TODO
}
fn (Result) free #
fn (mut result Result) free()
struct SizeOfTypeIs0Error #
struct SizeOfTypeIs0Error {
Error
}
fn (SizeOfTypeIs0Error) msg #
fn (err SizeOfTypeIs0Error) msg() string
struct Uname #
struct Uname {
pub mut:
sysname string
nodename string
release string
version string
machine string
}
- README
- Constants
- fn abs_path
- fn args_after
- fn args_before
- fn base
- fn cache_dir
- fn chdir
- fn chmod
- fn chown
- fn config_dir
- fn cp
- fn cp_all
- fn create
- fn debugger_present
- fn dir
- fn ensure_folder_is_writable
- fn environ
- fn executable
- fn execute
- fn execute_or_exit
- fn execute_or_panic
- fn execve
- fn execvp
- fn existing_path
- fn exists
- fn exists_in_system_path
- fn expand_tilde_to_home
- fn fd_close
- fn fd_read
- fn fd_slurp
- fn fd_write
- fn file_ext
- fn file_last_mod_unix
- fn file_name
- fn file_size
- fn fileno
- fn find_abs_path_of_executable
- fn flush
- fn fork
- fn from_slash
- fn get_error_msg
- fn get_line
- fn get_lines
- fn get_lines_joined
- fn get_raw_line
- fn get_raw_lines_joined
- fn get_raw_stdin
- fn getegid
- fn getenv
- fn getenv_opt
- fn geteuid
- fn getgid
- fn getpid
- fn getppid
- fn getuid
- fn getwd
- fn glob
- fn home_dir
- fn hostname
- fn inode
- fn input
- fn input_opt
- fn input_password
- fn is_abs_path
- fn is_atty
- fn is_dir
- fn is_dir_empty
- fn is_executable
- fn is_file
- fn is_link
- fn is_readable
- fn is_writable
- fn is_writable_folder
- fn join_path
- fn join_path_single
- fn last_error
- fn link
- fn log
- fn loginname
- fn ls
- fn mkdir
- fn mkdir_all
- fn mv
- fn mv_by_cp
- fn new_process
- fn norm_path
- fn open
- fn open_append
- fn open_file
- fn open_uri
- fn posix_get_error_msg
- fn posix_set_permission_bit
- fn quoted_path
- fn raw_execute
- fn read_bytes
- fn read_file
- fn read_file_array
- fn read_lines
- fn real_path
- fn rename
- fn rename_dir
- fn resource_abs_path
- fn rm
- fn rmdir
- fn rmdir_all
- fn setenv
- fn sigint_to_signal_name
- fn signal_opt
- fn stderr
- fn stdin
- fn stdout
- fn symlink
- fn system
- fn temp_dir
- fn to_slash
- fn truncate
- fn uname
- fn unsetenv
- fn user_names
- fn user_os
- fn utime
- fn vfopen
- fn vmodules_dir
- fn vmodules_paths
- fn vtmp_dir
- fn wait
- fn walk
- fn walk_ext
- fn walk_with_context
- fn write_file
- fn write_file_array
- type FilePermission
- type FN_SA_Handler
- type FnWalkContextCB
- type SignalHandler
- enum FileType
- enum ProcessState
- enum SeekMode
- enum Signal
- struct C.stat
- struct Command
- struct Eof
- struct ExecutableNotFoundError
- struct File
- fn close
- fn eof
- fn flush
- fn read
- fn read_bytes
- fn read_bytes_at
- fn read_bytes_into
- fn read_bytes_into_newline
- fn read_from
- fn read_into_ptr
- fn read_raw
- fn read_raw_at
- fn read_struct
- fn read_struct_at
- fn reopen
- fn seek
- fn tell
- fn write
- fn write_full_buffer
- fn write_ptr
- fn write_ptr_at
- fn write_raw
- fn write_raw_at
- fn write_string
- fn write_struct
- fn write_struct_at
- fn write_to
- fn writeln
- struct FileMode
- struct FileNotOpenedError
- struct MkdirParams
- struct NotExpected
- struct Process
- struct Result
- struct SizeOfTypeIs0Error
- struct Uname