OS Library

This library contains some OS-dependent functionality. This is an inherently "unsafe" library as scripts could use this to perform malicious code on your system.

This library depends upon the stream library. If you want the OS library, the stream library must be loaded.

Members

1. os.system([cmd: string])
2. os.getEnv([name: string, default = null])
3. os.putEnv(name: string[, value: string])
4. class Process
   1. this()
   2. workDir([path: string])
   3. isRunning()
   4. execute(cmd: string|array [, env: table])
   5. stdin()
   6. stdout()
   7. stderr()
   8. wait()
   9. kill()

os.system([cmd: string])

Execute the command 'string' as if you typed it into a shell in the current working directory. Returns the status of the command. If called without arguments, returns a boolean indicating whether a command processor is available on this system.

os.getEnv([name: string, default = null])

If called with one or more parameters, gets the value of the environment variable named name from the process's execution environment. If no variable of that name exists, returns the value of the default parameter (which defaults to null).

If called without parameters, gets a table representing the execution environment, where keys are names and values are the variables' values.

os.putEnv(name: string[, value: string])

Sets the value of the environment variable given by name. If value is not passed, unsets the variable; otherwise sets name to value.

class Process

The Process class allows you to spawn a new process (i.e. another program) and access its standard input, output, and error streams. These are exposed as stream.InputStream and stream.OutputStream objects.

The general flow of using a Process goes something like this:

1. Instantiate Process to get a new instance.
2. Call the new instance's execute method with some parameters to start the process.
3. Read and write data to and from the instance through the stdin, stdout, and stderr streams.
4. End the process, either by forcibly killing it with the kill method, or by waiting for it with wait.

Here are the methods defined by Process.

this()

Process constructor. After a Process has been instantiated, it is in a state of limbo and won't do anything until you actually execute something in it.

workDir([path: string])

Get or set the working directory of the Process. Defaults to the empty string, which means the current working directory. Calling this method will only have an effect if the process is not currently running. Changing the working directory while the process is running will have no effect.

isRunning()

Returns a bool indicating whether the process is currently running.

execute(cmd: string|array [, env: table])

Execute a program within this Process object.

The cmd parameter is the command to execute. It can be a string, in which case any quotes are parsed according to the system's shell's rules. Alternatively, it can be an array of strings, where each element is one piece of the command. In that case, it must have at least one element, where element 0 is the name of the program to run.

The optional env parameter is a table of environment variables that should be given to the process. It should be a table that maps from strings to strings, where the key is the environment variable name and the value is the value.

stdin()

Gets a reference to the standard input stream of the process. Of course, since you're on the other end of it, this is an output stream (a stream.OutputStream to be exact). You can then write data to this stream and the other process will see it as input.

stdout()

Gets a reference to the standard output stream of the process. Since you're on the other end, this is an input stream (a stream.InputStream). You can read data from the process through this.

stderr()

Gets a reference to the standard error stream of the process (as a stream.InputStream). Similar to stdout.

wait()

Waits for the process to terminate normally. Returns two values: the reason (as a string) and the status code (as an int). The meaning of the status code is dependent upon the reason, and is explained below.

The "reason" return value can be one of the following strings:

• "exit": The process terminated on its own accord. The status code is the code that the process returned.
• "signal": The process was terminated by a signal. The status code is the signal number that killed it.
• "stop": The process was stopped by a signal. The status code is the signal number that stopped it.
• "continue": The process had been stopped but has now been resumed. The status code is the signal number that resumed it.
• "error": The wait failed for some reason. The status code is an error number if the process was running, and -1 if it wasn't.

The "signal", "stop", and "continue" codes will only be returned on POSIX-compatible systems.

kill()

Forcibly kill a process. This blocks until the process has been killed.