Exec program

18.4.0 released Sep 25, 2023

Exec program

Purpose: Execute a program.

exec-program <program path> \
    [ args <program arg> [ , ... ] ] \
    [ status [ define ] <exit status> ] \
    [ ( input <input string> [ input-length <string length> ] ) \
        | ( input-file <input file> ) ] \
    [ ( output [ define ] <output string> [ output-length [ define ] <output length> ] ) \
        | ( output-file <output file> ) ] \
    [ ( error [ define ] <error string> ) | ( error-file <error file> ) ]

exec-program executes a program specified in <program path>, which can be a program name without path that exists in the path specified by the PATH environment variable; or an absolute path; or a path relative to the application home directory (see how-vely-works).

A program can have input arguments (specified with "args" clause), and if there are more than one, they must be separated by a comma. There is no limit on the number of input arguments, other than of the underlying Operating System. Each argument <program arg> may contain a comma if it is a string (i.e. double-quoted) or it is an expression within parenthesis.

You can specify a status variable <exit status>, which either must exist, or if it doesn't, use "define" to create it - this variable will have program's exit status. Note that if the program was terminated by a signal, <exit status> will have a value of 128+signal_number, so for example if the program was terminated with signal 9 (i.e. KILL signal), <exit status> will be 137 (i.e. 128+9). Any other kind of abnormal program termination (i.e. program termination that did not end in setting the exit code with exit() or similar) will return 126 as <exit code>.

Specifying program input and output is optional. If program has output and you are not capturing it in any way, the output is redirected to a temporary file that is deleted after exec-program completes.

You can specify an <input string> to be passed to program's standard input (stdin) via "input" clause. If "input-length" is not used, the length of this input is the string length of <input string>, otherwise <string length> bytes is passed to the program, allowing binary input. Alternatively, you can specify a file <input file> (via "input-file" clause) to be opened and directed into program's standard input (stdin).

You can redirect the program's output (which is "stdout") to a file <output file> using "output-file" clause. Alternatively, program's output can be captured in <output string> (via "output" clause) with its length in <output length> (via "output-length" clause), both of which can be created with optional "define". <output string> is allocated memory.

To get the program's error output (which is "stderr") to a file <error file>, use "error-file" clause. Alternatively, program's error output can be captured in <error string> (via "error" clause) which can be created with "define". <error string> is allocated memory.

If <input file> cannot be opened, VV_ERR_READ is reported in <exit status>, and if either <output file> or <error file> cannot be opened, the status is VV_ERR_WRITE.

Do not use system() function as it may be unsafe. Use exec-program instead.

Examples

To simply execute a program that is in the path, without any arguments, input or output:

exec-program "myprogram"

Run "grep" program using a string as its standard input in order to remove a line that contains "bad line" in it, and outputting the result into "ovar" variable:

exec-program "grep" args "-v", "bad line" "config" input "line 1\nline 2\nbad line\nline 3" output ovar
p-out ovar

Get the list of files in the application home directory into buffer "ovar" (and its length into variable "olen") and then display it:

exec-program "ls" output define ovar output-length define olen

Similar to the above example of listing files, but output results to a file (which is then read and the result displayed), and provide options "-a -l -s" to "ls" program:

exec-program "ls" args "-a", "-l", "-s" output-file "lsout"
read-file "lsout" to define final_res
p-out final_res

Count the lines of file "config" (which is redirected to the standard output of "wc" program) and store the result in variable "ovar" (by means of redirecting the output of "wc" program to it), and then display:

exec-program "wc" args "-l" input-file "config" output define ovar
p-out ovar