process

The process module provides subprocess management functionality for creating, controlling, and communicating with external processes. This is the underlying module for os.exec and os.execv functions. This is an extension module of xmake.

TIP

To use this module, you need to import it first: import("core.base.process")

process.open

• Open a subprocess with command string

Function Prototype

API

process.open(command: <string>, opt: <table>)

Parameter Description

Parameter	Description
command	Required. The command string to execute
opt	Optional. Process options table

Options in opt:

• stdin - Input source (file path, file object, or pipe object)
• stdout - Output destination (file path, file object, or pipe object)
• stderr - Error output destination (file path, file object, or pipe object)
• envs - Environment variables array (e.g., {"PATH=xxx", "XXX=yyy"})

Usage

Creates a new subprocess by executing a command string. Returns a subprocess object that can be used to control and communicate with the process.

-- Basic process execution
local proc = process.open("echo hello world")
local ok, status = proc:wait()
proc:close()

-- Process with file redirection
local stdout = os.tmpfile()
local stderr = os.tmpfile()
local proc = process.open("xmake lua print 'hello'", {
    stdout = stdout,
    stderr = stderr
})
proc:wait()
proc:close()

-- Read output from file
local output = io.readfile(stdout):trim()
print(output)  -- Output: hello

Process with environment variables:

local proc = process.open("echo $MY_VAR", {
    envs = {"MY_VAR=hello from xmake"}
})
proc:wait()
proc:close()

process.openv

• Open a subprocess with program and arguments list

Function Prototype

API

process.openv(program: <string>, argv: <table>, opt: <table>)

Parameter Description

Parameter	Description
program	Required. The program to execute
argv	Required. Array of arguments to pass to the program
opt	Optional. Process options table (same as process.open)

Usage

Creates a new subprocess by executing a program with a list of arguments. This is safer than process.open as it avoids shell interpretation issues.

-- Execute program with arguments
local proc = process.openv("xmake", {"lua", "print", "hello world"})
local ok, status = proc:wait()
proc:close()

-- Execute with file redirection
local stdout = os.tmpfile()
local proc = process.openv("xmake", {"lua", "print", "xmake"}, {
    stdout = stdout,
    stderr = stderr
})
proc:wait()
proc:close()

-- Read the output
local output = io.readfile(stdout):trim()
print(output)  -- Output: xmake

Execute with environment variables:

local proc = process.openv("env", {"MY_VAR=test"}, {
    envs = {"MY_VAR=hello from xmake"}
})
proc:wait()
proc:close()

process:wait

• Wait for subprocess to complete

Function Prototype

API

process:wait(timeout: <number>)

Parameter Description

Parameter	Description
timeout	Optional. Timeout in milliseconds. Use -1 for infinite wait, 0 for non-blocking

Usage

Waits for the subprocess to complete and returns the exit status. Can be used with or without timeout.

Returns:

• ok - Exit code (0 for success, negative for error)
• status - Process status or error message

local proc = process.open("echo hello")
local ok, status = proc:wait()
print("Exit code:", ok)  -- Output: 0 (success)
print("Status:", status)  -- Output: nil or error message
proc:close()

Wait with timeout:

local proc = process.open("sleep 10")
local ok, status = proc:wait(1000)  -- Wait max 1 second
if ok < 0 then
    print("Process timed out or failed:", status)
end
proc:close()

Non-blocking wait:

local proc = process.open("echo hello")
local ok, status = proc:wait(0)  -- Non-blocking
if ok < 0 then
    print("Process not ready yet")
else
    print("Process completed with code:", ok)
end
proc:close()

process:kill

• Kill the subprocess

Function Prototype

API

process:kill()

Parameter Description

No parameters required for this function.

Usage

Terminates the subprocess immediately. Returns true if successful, false with error message if failed.

local proc = process.open("sleep 60")
-- ... do something ...

-- Kill the process
local success, error = proc:kill()
if success then
    print("Process killed successfully")
else
    print("Failed to kill process:", error)
end
proc:close()

Kill long-running process:

local proc = process.open("xmake l os.sleep 60000")
print("Process started:", proc)

-- Kill after 2 seconds
os.sleep(2000)
local success = proc:kill()
print("Kill result:", success)
proc:close()

process:close

• Close the subprocess

Function Prototype

API

process:close()

Parameter Description

No parameters required for this function.

Usage

Closes the subprocess and releases associated resources. Should be called when done with the process.

local proc = process.open("echo hello")
proc:wait()
local success = proc:close()
print("Close result:", success)

Always close processes:

local proc = process.open("some command")
local ok, status = proc:wait()
-- Always close, even if process failed
proc:close()

process:name

• Get the process name

Function Prototype

API

process:name()

Parameter Description

No parameters required for this function.

Usage

Returns the name of the process (filename without path).

local proc = process.open("xmake lua print 'hello'")
print("Process name:", proc:name())  -- Output: xmake
proc:close()

process:program

• Get the process program path

Function Prototype

API

process:program()

Parameter Description

No parameters required for this function.

Usage

Returns the full program path that was used to start the process.

local proc = process.openv("xmake", {"lua", "print", "hello"})
print("Program:", proc:program())  -- Output: xmake
proc:close()

process:cdata

• Get the process cdata

Function Prototype

API

process:cdata()

Parameter Description

No parameters required for this function.

Usage

Returns the underlying cdata object for the process. Used internally by the scheduler and other low-level operations.

local proc = process.open("echo hello")
local cdata = proc:cdata()
print("CData type:", type(cdata))
proc:close()

process:otype

• Get the object type

Function Prototype

API

process:otype()

Parameter Description

No parameters required for this function.

Usage

Returns the object type identifier. For subprocess objects, this returns 3 (poller.OT_PROC).

local proc = process.open("echo hello")
print("Object type:", proc:otype())  -- Output: 3
proc:close()

TIP

The process module is the underlying implementation for os.exec and os.execv functions. It provides more control and flexibility for process management, including timeout handling, pipe integration, and scheduler support. Use process.open for simple command execution and process.openv for safer argument handling.