<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) XXXX-2008 - INRIA
 * Copyright (C) 2018 - Samuel GOUGEON
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
          xmlns:scilab="http://www.scilab.org" xml:id="unix_g" xml:lang="en">
    <refnamediv>
        <refname>unix_g</refname>
        <refpurpose>
          executes some Windows, Linux or MacOS instructions: output in variables
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            rep = unix_g(commands)
            [rep, status] = unix_g(commands)
            [rep, status, msgerr] = unix_g(commands)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>commands</term>
                <listitem>
                    <para>A single text: instruction(s) to be executed</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>rep</term>
                <listitem>
                    <para>column of text: standard output.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>status</term>
                <listitem>
                    <para>an integer, the error status. status=0 if no error occurred</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>msgerr</term>
                <listitem>
                    <para>column of text: error message.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>unix_g(…)</literal> opens a new session of the Operating System (OS) command
            interpreter (<emphasis>sh</emphasis> with Linux, <emphasis>cmd.exe</emphasis> with
            Windows, etc..), sends <varname>commands</varname> to it,
            lets it processing <varname>commands</varname> instructions, receives the standard
            output and possible error message yielded by the processing, and closes the interpreter
            session.
        </para>
        <para>
            The starting working directory and environment variables of the opened interpreter
            are set <link linkend="host_description">as described for host()</link>.
        </para>
        <para>
            The standard output is recorded in the variable <varname>rep</varname>.
        </para>
        <para>
            If <varname>commands</varname> includes an erroneous instruction,
            <itemizedlist>
              <listitem>
                <varname>rep</varname> is set to "".
              </listitem>
              <listitem>
                If the output variable <varname>msgerr</varname> is used, the error message normally
                displayed in the OS terminal is caught and stored in it. Otherwise, the OS error
                is displayed in the Scilab console.
              </listitem>
              <listitem>
                The remaining instructions after the erroneous one are ignored.
              </listitem>
            </itemizedlist>
            <warning>
              The effects of valid instructions processed before the erroneous one remain actual
              (for instance, deleted files). However, their standard output is lost.
              This is why multiple instructions in <varname>commands</varname> are not recommended.
            </warning>
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
function d = DIR(path)
  path = pathconvert(path,%t,%t)
  if getos() == 'Windows' then
    d = unix_g('dir '+path)
  else
    d = unix_g('ls '+path)
  end
endfunction

DIR('SCI/etc')
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="unix_s">unix_s</link>
            </member>
            <member>
                <link linkend="unix_w">unix_w</link>
            </member>
            <member>
                <link linkend="unix_x">unix_x</link>
            </member>
            <member>
                <link linkend="host">host</link>
            </member>
            <member>
                <link linkend="getos">getos</link>
            </member>
            <member>
                <link linkend="setenv">setenv</link>
            </member>
            <member>
                <link linkend="powershell">powershell</link>
            </member>
            <member>
                <ulink url="https://msdn.microsoft.com/en-us/library/windows/desktop/ms681382.aspx">list of MS Windows exit codes</ulink>
            </member>
        </simplelist>
    </refsection>
</refentry>
