FILE::EXEC 1g 2024-01-10 laplante@plcb.ca GOWEB/FILE

title: “FILE::EXEC” date: “2024-01-10” author: “laplante@plcb.ca” version: “1.0.0”

category: “GOWEB/FILE”

Name

file::exec — execute a program (supports background mode, redirection, timeout, and arguments)

Synopsis

• file::exec or exec(file[, parameters…, error: variable, bg: bool, errfile: string, outfile: string, timeout: string, args: array or string…])

Note: Use /bin/sh as the file argument to run scripts that require a shebang (#!/bin/sh).

Description

This function executes a program. You may pass arguments as additional parameters, as an args array, or as a single args string.
It supports redirecting output to files, running in the background, capturing errors, and applying a timeout.

Parameters

• file — the executable path (or an interpreter like /bin/sh).
  
• args — either an array of arguments or a string.
  
• outfile — path to write stdout.
  
• errfile — path to write stderr.
  
• bg — when true, runs the job in the background and returns a channel ch. Inspect with jobstatus(ch).
  
• timeout — duration string (e.g., "1s", "500ms", "2m"). Kills the process if exceeded.
  
• error — variable to capture any execution error.

Examples

res={{
    res := exec(outfile:"/tmp/resout", "/bin/sh", "../../tests/038-file/file24", "1");
    res; "\n";
    read("/tmp/resout"); "\n--------------\n";
}}.

return

res={"args":["../../tests/038-file/file24","1"],"error":"This message goes to stderr\n","file":"/bin/sh","output":""}
test:
1
end test

--------------
.

res={{
    res := exec(outfile:"/tmp/resout", errfile:"/tmp/reserr", "/bin/sh", "../../tests/038-file/file24", "1");
    "res = "; res; "\n----------\nresout=";
    read("/tmp/resout"); "\n----------\nreserr=";
    read("/tmp/reserr"); "\n--------------\n";
}}.

return 

res=res = {"args":["../../tests/038-file/file24","1"],"error":"","file":"/bin/sh","output":""}
----------
resout=test:
1
end test

----------
reserr=This message goes to stderr

--------------
.

res={{
    res := exec("/bin/sh", "../../tests/038-file/file24", "3", bg:true);
    "res="; res; "\n";
    status := jobstatus(res.ch);
    for ! status.jobstatus {
        "Job not finished: "; status; "\n"; flush();
        sleep("1s");
        status = jobstatus(res.ch);
    }
    "End of job: "; status; "\n";
}}.

Expected return (pattern):

res=res={"args":["../../tests/038-file/file24","3"],"ch":"channel to 0x[0-9a-z]+","file":"/bin/sh"}.*

res={{
    res := exec(error:err, "/bin/sh", "../../tests/038-file/file24", "1");
    "res="; res; "\n";
    "err="; err; "\n";

    res := exec(timeout:"1s", error:err, "/bin/sh", "../../tests/038-file/file24", "2");
    "res="; res; "\n";
    "err="; err; "\n";
}}.

return

res=res={"args":["../../tests/038-file/file24","1"],"error":"This message goes to stderr\n","file":"/bin/sh","output":"test:\n1\nend test\n"}
err=
res=
err=file::exec : execution error : signal: killed
.

res={{
    res := exec(bg:true, timeout:"1s", error:err, "/bin/sh", "../../tests/038-file/file24", "2");
    "res="; res; "\n";
    "err="; err; "\n";
    status := jobstatus(res.ch);
    for ! status.jobstatus {
        "Job not finished: "; status; "\n"; flush();
        sleep("1s");
        status = jobstatus(res.ch);
    }
    "End of job: "; status; "\n";
    if status.runerror != null {
        "Exec was killed\n";
    }
}}.

return (excerpt)

.*execution error : signal: killed"}
Exec was killed
.

Author

• laplante@plcb.ca

See also

• File functions
  
• Index

Version

• 1.0.0 2024-01-10 laplante@plcb.ca initial version