ref: d0ffb958c7247028223c7e53253249d52a47a324
dir: /doc/api/libstd/os.txt/
{
title: OS Interfaces
description: libstd: OS Interfaces
}
OS Interfaces
-------------
pkg std =
type sysinfo = struct
system : byte[:]
version : byte[:]
release : byte[:]
arch : byte[:]
;;
type waitstatus = union
`Wsuccess
`Wfailure
`Wsignalled
`Waiterror
;;
const Enone : errno
const Eperm : errno
const Enoent : errno
const Esrch : errno
const Eintr : errno
const Eio : errno
const Enxio : errno
const E2big : errno
const Enoexec : errno
const Ebadf : errno
const Echild : errno
const Eagain : errno
const Enomem : errno
const Eacces : errno
const Efault : errno
const Enotblk : errno
const Ebusy : errno
const Eexist : errno
const Exdev : errno
const Enodev : errno
const Enotdir : errno
const Eisdir : errno
const Einval : errno
const Enfile : errno
const Emfile : errno
const Enotty : errno
const Etxtbsy : errno
const Efbig : errno
const Enospc : errno
const Espipe : errno
const Erofs : errno
const Emlink : errno
const Epipe : errno
const Edom : errno
const Erange : errno
const Emisc : errno
const Failmem : byte#
const getpid : ( -> pid)
const getsysinfo : (si : sysinfo# -> void)
const execvp : (cmd : byte[:], args : byte[:][:] -> int64)
const execvpe : (cmd : byte[:], args : byte[:][:], env : byte[:][:] -> int64)
const getenv : (name : byte[:] -> option(byte[:]))
const getenvv : (name : byte[:], default : byte[:] -> byte[:])
const fork : (-> pid)
const execv : (cmd : byte[:], args : byte[:][:] -> int64)
const execve : (cmd : byte[:], args : byte[:][:], env : byte[:][:] -> int64)
const waitpid : (pid:pid, loc:int32#, opt : int64 -> int64)
const spork : (cmd : byte[:][:] -> result((pid, fd, fd), int))
const sporkfd : (cmd : byte[:][:], infd : fd, outfd : fd -> result(pid, int))
const exit : (status:int -> void)
const now : (-> time)
const wait : (pid : pid -> waitstatus)
;;
type sysinfo = struct
system : byte[:]
version : byte[:]
release : byte[:]
arch : byte[:]
;;
The `sysinfo` struct is returned from the operating system, giving
some information about the sytem that this program is running on. It
is similar to the `uname` function in the standard C library, although
it is guaranteed to be portable. All the storage for the members is
within the private parts of the struct, and no freeing is needed to
relase them.
type waitstatus = union
`Wsuccess
`Wfailure
`Wsignalled
`Waiterror
;;
This type indicates the exit status of a child process that was invoked
with one of the exec family of functions. It only returns a broad category
of values, and does not return the full details provided by the os -- this
is not portable. If the exact exit status is needed, the `sys` package
should cover this need.
const Enone : errno
const Erange : errno
const Ebadf : errno
const Eexist : errno
const Einval : errno
const Efault : errno
const Eio : errno
const Emisc : errno
The errno results are used to signal OS errors. They are not going to remain
stable, and will probably be replaced with system call specific unions for
error handling in future API work. Use them, but parsimoniously. The code
that uses them will break.
Emisc is used for any non-portable error codes.
const getpid : ( -> pid)
Returns the process id of the current process.
const getsysinfo : (si : sysinfo# -> void)
Fills a `sysinfo` struct with information about the platform that the program
is running on.
const execv : (cmd : byte[:], args : byte[:][:] -> errno)
const execve : (cmd : byte[:], args : byte[:][:], env : byte[:][:] -> errno)
const execvp : (cmd : byte[:], args : byte[:][:] -> errno)
const execvpe : (cmd : byte[:], args : byte[:][:], env : byte[:][:] -> errno)
Executes a program. If the command `cmd` begins with a `/`, then it is
resolved as an absolute path. Otherwise, command is resolved relative to the
current directory.
If the path in `cmd` is not an absolute path, the `execvp` variants of this
function will search the path for this program in each directory relative to
$PATH or $path, in addition to the current directory.
The arguments in `args` are passed to the executed program as its argument
vector. By convention, the first argument in the `args` array should be the
filename of the program being executed.
For the `execvp` exec variant, the current program's environment is inherited,
and is not modified.
The `execvpe` variant of this function takes an additional argument `env`,
which is passed to the invoked binary, replacing alll the current environment
variables. It is in the form of a list of `"ENV_VAR=value"` key value pairs.
Returns: Errno on failure. On success, the function does not return.
const getenv : (name : byte[:] -> option(byte[:]))
The `getenv` function looks up a variable from the process environment.
Returns: `\`Some env\_val` for an environment variable that is present in the
environment, or `\`None` if it is not present.
const getenvv : (name : byte[:], default : byte[:] -> byte[:])
The `getenvv` is the same as `getenv, with the exception that will return the
value of the environment variable if it is present, or `default` if there is
no such environment variable.
Returns: The value of "name" if present, or "default" if not.
const fork : (-> pid)
This forks a new process. This function returns twice, once in the parent
and once in the child.
On a successful fork, within the parent process `fork` returns a process ID
greater than zero, which is the process id of the child process. Within the
child process, `fork` returns zero.
If the `fork` function returns a value less than zero, then creating a child
process failed.
Returns: The pid of the child.
const wait : (pid : pid -> waitstatus)
`wait` waits for a process with the PID `pid` to exit, returning its final
status. This function blocks until the child process has exited. If the
process has already exited before this function is called, but has not yet
been called on the process id of the child process, then this function
will return a status immediately.
If the child process has already been waited on, calling this function is
invalid, and it should return a `\`Waiterror`.
Returns: A waitstatus, telling you if the process crashed, exited with
failure, exited with success, or whether the wait call was invalid.
const spork : (cmd : byte[:][:] -> result((pid, fd, fd), errno))
Spork stand for `Speak to Process Fork`. It returns a process id and an
input and output file descriptor via which you can communicate to the process
over stdin and stdout. Stderr is inherited from the current process.
Returns: Either a tuple of (pid, stdin, stdout) on success, or the error
that caused the failure.
const sporkfd : (cmd : byte[:][:], infd : fd, outfd : fd -> result(pid, errno))
Sporkfd is identical to spork, however, instead of returning new file
descriptors, it uses the file descriptors passed in.
Returns: Either the pid spawned, or the error that caused the spawn failure.
const exit : (status:int -> void)
This exits a process with the status specified. On most Unixy systems,
this will return the value to the shell. On Plan 9, this will call
exits() with the number converted to a string.
This function terminates the process.