lua localexec

1. Synopsis

localexec is a linux-only lua module that executes a command by accepting (stdin,env,args) as input and returning (resultcode,stdout,stderr) as output.

2. Installation

$ luarock install localexec

3. Usage

Typical use case

local localexec=require("localexec")

local processInput={cmd="/usr/bin/myprogram", 
                    args={arg1,arg2,arg3}, 
                    env={env1=val1,env2=val2,env3=val3}, 
                    stdin="hello this is my stdin input"
                    }

local processOutput=localexec.spawn(processInput)

-- Dump output for test purposes:

print("lua result:" .. tostring(processOutput.luaresult))
print("retcode:" .. tostring(processOutput.retcode))
print("stdout:".. processOutput.stdout)
print("stderr:".. processOutput.stderr)

-- Typical processing:

if processOutput.retcode ~= 0 then
    print("error:" .. processOutput.stderr)
    handleError()
else
    print("success")
    handleSuccess()
end

processInput

cmd: required
args: optional list of arguments
env: optional list of environment variables
stdin: optional string that will be fed to stdin, if present

processOutput

luaresult: result returned by os.execute (nil=ok and false=error)
retcode: integer result returned by shell (0=ok and not 0=error)
stdout: output on stdout
stderr: output on stderr

4. How does it work?

Under the hood localexec actually uses os.execute. It uses shared memory (/dev/shm) to populate stdin, if present, and reads stdout, stderr, and the return code from shared memory after execution:

$ cat /dev/shm/lua_aVjVBv.stdin | env1='val1' env2='val2' ... envN \
    COMMAND arg1 arg2 ... argM \
        > /dev/shm/lua_aVjVBv.stdout \
        2> /dev/shm/lua_aVjVBv.stderr ; \
  echo $? > /dev/shm/lua_aVjVBv.retcode

localexec carefully escapes the environment values and arguments to prevent shell injection. Next, localexec removes the temporary shared-memory files.

Hence, it lets the shell deal with simultaneously reading from stdin while writing to stdout and stderr.

5. Similar modules and functions

(lua built-in) os.execute

Out of the box, os.execute does not accept stdin input nor env variables and only returns retcode. It does not return stdout not stderr output.

(lua built-in) io.popen

io.popen does not accept stdin nor env and only returns stdout. It does not return stderr nor retcode.

popen3

The popen3 module, and its alternative or other alternative provide the user with streams, and leaves him the task to simultaneously feed stdin and read from stdout and stderr. This can be achieved with co-routines, threads, or with the libc select() function. For the purpose of supplying stdin as a lua string and reading out stdout and stderr as lua strings, using these modules requires extra work.

6. admin scripts

The admin.sh facilitates developing, building, and publishing the program. You can use ./admin.sh help to view the commands available.

It pushes the source code changes to the github publication platform. It pushes the lua module to the luarocks distribution platform.

7. Issues and feedback

Feel free to post a message on the issue list.

8. License

Written by Erik Poupaert
Cambodia,(c) 2019
Licensed under the LGPL

eriksank/localexec