node-red/packages/node_modules/@node-red/nodes/locales/en-US/function/90-exec.html

<!--
  Copyright JS Foundation and other contributors, http://js.foundation

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->

<script type="text/html" data-help-name="exec">
    <p>Runs a system command and returns its output.</p>
    <p>The node can be configured to either wait until the command completes, or to
    send its output as the command generates it.</p>
    <p>The command that is run can be configured in the node or provided by the received
    message.</p>

    <h3>Inputs</h3>
    <dl class="message-properties">
        <dt class="optional">payload <span class="property-type">string</span></dt>
        <dd>if configured to do so, will be appended to the executed command.</dd>
        <dt class="optional">kill <span class="property-type">string</span></dt>
        <dd>the type of kill signal to send an existing exec node process.</dd>
        <dt class="optional">pid <span class="property-type">number|string</span></dt>
        <dd>the process ID of an existing exec node process to kill.</dd>
    </dl>

    <h3>Outputs</h3>
    <ol class="node-ports">
        <li>Standard output
            <dl class="message-properties">
                <dt>payload <span class="property-type">string</span></dt>
                <dd>the standard output of the command.</dd>
            </dl>
            <dl class="message-properties">
                <dt>rc <span class="property-type">object</span></dt>
                <dd>exec mode only, a copy of the return code object (also available on port 3)</dd>
            </dl>
        </li>
        <li>Standard error
            <dl class="message-properties">
                <dt>payload <span class="property-type">string</span></dt>
                <dd>the standard error of the command.</dd>
            </dl>
            <dl class="message-properties">
                <dt>rc <span class="property-type">object</span></dt>
                <dd>exec mode only, a copy of the return code object (also available on port 3)</dd>
            </dl>
        </li>
        <li>Return code
            <dl class="message-properties">
                <dt>payload <span class="property-type">object</span></dt>
                <dd>an object containing the return code, and possibly <code>message</code>, <code>signal</code> properties.</dd>
            </dl>
        </li>
    </ol>
    <h3>Details</h3>
    <p>By default uses the <code>exec</code> system call which calls the command, waits for it to complete, and then
    returns the output. For example a successful command should have a return code of <code>{ code: 0 }</code>.</p>
    <p>Optionally can use <code>spawn</code> instead, which returns the output from stdout and stderr
    as the command runs, usually one line at a time. On completion it then returns an object
    on the 3rd port. For example, a successful command should return <code>{ code: 0 }</code>.</p>
    <p>Errors may return extra information on the 3rd port <code>msg.payload</code>, such as a <code>message</code> string,
    <code>signal</code> string.</p>
    <p>The command that is run is defined within the node, with an option to append <code>msg.payload</code> and a further set of parameters.</p>
    <p>Commands or parameters with spaces should be enclosed in quotes - <code>"This is a single parameter"</code></p>
    <p>The returned <code>payload</code> is usually a <i>string</i>, unless non-UTF8 characters are detected, in which
    case it is a <i>buffer</i>.</p>
    <p>The node&apos;s status icon and PID will be visible while the node is active. Changes to this can be read by the <code>Status</code> node.</p>
    <h4>Killing processes</h4>
    <p>Sending <code>msg.kill</code> will kill a single active process. <code>msg.kill</code> should be a string containing
    the type of signal to be sent, for example, <code>SIGINT</code>, <code>SIGQUIT</code> or <code>SIGHUP</code>.
    Defaults to <code>SIGTERM</code> if set to an empty string.</p>
    <p>If the node has more than one process running then <code>msg.pid</code> must also be set with the value of the PID to be killed.</p>
    <p>If a value is provided in the <code>Timeout</code> field then, if the process has not completed when the specified number of seconds has elapsed, the process will be killed automatically</p>
    <p>Tip: if running a Python app you may need to use the <code>-u</code> parameter to stop the output being buffered.</p>
</script>