execresult
Prototype: execresult(command, shell)
Return type: string
The return value is cached.
Description: Execute command
and return output (both stdout
and stderr
) as string
.
If the command is not found, the result will be the empty string.
The shell
argument decides whether a shell will be used to encapsulate the
command. This is necessary in order to combine commands with pipes etc, but
remember that each command requires a new process that reads in files beyond
CFEngine's control. Thus using a shell is both a performance hog and a
potential security issue.
Arguments:
command
:string
, in the range:.+
shell
: one ofnoshell
useshell
powershell
Example:
Prepare:
rm -rf /tmp/testhere
mkdir -p /tmp/testhere
touch /tmp/testhere/a
touch /tmp/testhere/b
touch /tmp/testhere/c
touch /tmp/testhere/d
touch /tmp/testhere/e
echo "#!/usr/bin/env sh" >/tmp/testhere/echo-stdout-and-stderr
echo "echo stderr >&2" >>/tmp/testhere/echo-stdout-and-stderr
echo "echo stdout" >>/tmp/testhere/echo-stdout-and-stderr
chmod +x /tmp/testhere/echo-stdout-and-stderr
Run:
body common control
{
bundlesequence => { "example" };
}
bundle agent example
{
vars:
"my_result"
string => execresult("/bin/ls /tmp/testhere", noshell);
"my_result_with_stdout_and_stderr"
string => execresult("/tmp/testhere/echo-stdout-and-stderr", noshell);
"my_result_with_stdout"
string => execresult("/tmp/testhere/echo-stdout-and-stderr 2>/dev/null", useshell);
"my_result_with_stderr"
string => execresult("/tmp/testhere/echo-stdout-and-stderr 1>/dev/null", useshell);
reports:
"/bin/ls /tmp/testhere returned '$(my_result)'";
"my_result_with_stdout_and_stderr == '$(my_result_with_stdout_and_stderr)'";
"my_result_with_stdout == '$(my_result_with_stdout)'";
"my_result_with_stderr == '$(my_result_with_stderr)'";
}
Output:
R: /bin/ls /tmp/testhere returned 'a
b
c
d
e
echo-stdout-and-stderr'
R: my_result_with_stdout_and_stderr == 'stderr
stdout'
R: my_result_with_stdout == 'stdout'
R: my_result_with_stderr == 'stderr'
Notes: you should never use this function to execute commands that
make changes to the system, or perform lengthy computations. Such an
operation is beyond CFEngine's ability to guarantee convergence, and
on multiple passes and during syntax verification these function calls
are executed, resulting in system changes that are covert. Calls
to execresult
should be for discovery and information extraction
only. Effectively calls to this function will be also repeatedly
executed by cf-promises
when it does syntax checking, which is
highly undesirable if the command is expensive. Consider using
commands
promises instead, which have locking and are not evaluated
by cf-promises
. If capturing stderr is undesirable, consider useshell and
redirecting it to /dev/null
.
See also: returnszero()
.
Change: policy change in CFEngine 3.0.5. Previously newlines were changed for spaces, now newlines are preserved.