summaryrefslogtreecommitdiff
path: root/doc/api/libstd/os.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/libstd/os.txt')
-rw-r--r--doc/api/libstd/os.txt228
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.