diff options
Diffstat (limited to 'doc/api/libstd/os.txt')
| -rw-r--r-- | doc/api/libstd/os.txt | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/doc/api/libstd/os.txt b/doc/api/libstd/os.txt new file mode 100644 index 0000000..2fad271 --- /dev/null +++ b/doc/api/libstd/os.txt @@ -0,0 +1,228 @@ +{ + 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. |