Ratchet Library :: Command Execution
API  ·  Manual

ratchet.exec API Reference


Creating a new ratchet.exec object is the first step towards running a command, however it should be noted that creating the object does not actually start the new process.

The argument to ratchet.exec.new() is a table array of arguments to the command. This includes the initial command name (known in C as argv[0]). The first item in the table array can be a full-path filename or a command from the system $PATH.

To start execution of the process, use the object's start() method, which takes no extra parameters and returns nothing. Behind the scenes, this method will fork() the process and call execvp().

local process = ratchet.exec.new({"echo", "hello", "world"})

Standard IO

Once the process is started, three new methods are available to it: stdin(), stdout(), and stderr(). These methods return file-like objects whose methods will work nicely within ratchet threads. All three have a method close() which will close the underlying file descriptor, which is especially useful for the stdin() object.

While not initially intuitive, the stdin() object allows writing and the stdout() and stderr() objects allow reading. Writing data to an stdin() object will cause that data to be readable in the process's standard input stream. Reading from stdout() or stderr() will get data that the process wrote to either stream.

local p = ratchet.exec.new({"echo", "hello", "world"})
local line = p:stdout():read()
line = line:gsub("%\r?%\n$", "")
assert("hello world" == line)


local p = ratchet.exec.new({"cat"})
local line = p:stdout():read()
line = line:gsub("%\r?%\n$", "")
assert("test" == line)

All process IO will pause the current ratchet thread until the request can be carried out.

Waiting for Completion

Once you are done with IO in a process, you must call the wait() method to prevent the process from going zombie, see the wait manpage for details. This method will return an exit status (like what os.exit() provides), followed by true or false depending on if the process ended in normal circumstances.

assert(0 == process:wait(), "The process exited unsuccessfully!")

The wait() method will pause the current ratchet thread until the process exits. Keep in mind that some processes stream from stdin() and will not end until that stream is closed.

Communicate Method

Instead of doing everything manually, there is a convenience function communicate() which is easier to use in most cases.

The first thing it does it call start() to begin the command process. It immediately closes the process's standard input stream, after sending it any optional data passed as communicate()'s argument.

It then waits for the process's standard output and error streams to close, concatenating any data received on them into the first two returned values. Once both streams have closed, it calls wait() to close the process and returns the exit code as the third returned value.

local p = ratchet.exec.new({"cat"})
local out, err, status = p:communicate("testing")
assert("testing" == out)
assert("" == err)
assert(0 == status)

Last modified:  Sun, 17 Aug 2014 09:32:32 -0400
Author:  ian.good