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