<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://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:ns5="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="fr">
    <refnamediv>
        <refname>unix_g</refname>
        <refpurpose>
          exécute des instructions Windows, Linux ou MacOS : résultats dans des variables
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Séquence d'appel</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>chaîne de caractères unique : instructions à exécuter.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>rep</term>
                <listitem>
                    <para>colonne de texte : résultats normalement affichés en sortie standard.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>status</term>
                <listitem>
                    <para>
                        nombre entier : code de résultat d'exécution. status==0 est retourné si
                        aucune erreur ne s'est produite.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>msgerr</term>
                <listitem>
                    <para>Colonne de texte : message d'erreur.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>unix_g()</literal> ouvre une nouvelle session de l'interpréteur de commandes
            du système d'exploitation (OS) (<emphasis>sh</emphasis> avec Linux,
            <emphasis>cmd.exe</emphasis> avec MS Windows, etc..), lui envoie les instructions
            <varname>commands</varname>, attend le traitement de celles-ci, reçoit les messages
            de résultats standard ou le possible message d'erreur générés lors du traitement,
            et ferme la session de l'interpréteur.
        </para>
        <para>
            Le dossier de travail initial et les variables d'environnement de la session OS ouverte
            sont établis <link linkend="host_description">comme pour host()</link>.
        </para>
        <para>
            Les résultats standard habituellement affichés dans le terminal de l'interpréteur sont
            capturés et stockés en colonne texte dans la variable <varname>rep</varname>.
        </para>
        <para>
            Si <varname>commands</varname> comporte une instruction erronée,
            <itemizedlist>
                <listitem>
                    <varname>rep</varname> vaut "".
                </listitem>
                <listitem>
                    Si la variable de sortie <varname>msgerr</varname> est indiquée, le message d'erreur
                    normalement affiché dans le terminal de l'interpréteur est capturé et enregistré
                    dans celle-ci. Sinon, le message d'erreur est affiché dans la console Scilab.
                </listitem>
                <listitem>
                    Les instructions suivant celle erronée sont ignorées.
                </listitem>
                <warning>
                    Les opérations effectuées par les instructions valides figurant dans
                    <varname>commands</varname> avant l'instruction
                    erronée demeurent réelles (par exemple, fichiers supprimés). Leurs
                    compte-rendus ou résultats d'exécution affichables sont cependant ignorés
                    et perdus. Les instructions multiples sont déconseillées. Elles sont souvent
                    plus difficiles à déboguer.
                </warning>
            </itemizedlist>
        </para>
    </refsection>
    <refsection>
        <title>Exemples</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>Voir aussi</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">Liste de codes de sortie MS Windows</ulink>
            </member>
        </simplelist>
    </refsection>
</refentry>
