Myrddin: 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 espork    : (cmd : byte[:][:] -> result((pid, fd, fd, fd), errno))
        const sporkfd   : (cmd : byte[:][:], infd : fd, outfd : fd  -> result(pid, int))
        const sporkdir  : (cmd : byte[:][:], dir : byte[:]  -> result((pid, fd, fd), errno))
        const esporkdir : (cmd : byte[:][:], dir : byte[:]  -> result((pid, fd, fd, fd), errno))
        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, ordefault` 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))
const espork    : (cmd : byte[:][:] -> result((pid, fd, fd, fd), errno))
const sporkdir  : (cmd : byte[:][:], dir : byte[:]  -> result((pid, fd, fd), errno))
const esporkdir : (cmd : byte[:][:], dir : byte[:]  -> result((pid, fd, 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. Espork is similar, but returns a file descriptor for stderr. The dir functions provide a race-free method of starting a process in a specific directory.

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.