<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * ...
 *
 * 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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="dir">
    <refnamediv>
        <refname>dir</refname>
        <refpurpose>gets file list </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>dir path
            S=dir([path])
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>path</term>
                <listitem>
                    <para>a string matrix giving a directory pathname (eventually  ended
                        by a pattern built with <literal>*</literal>). Default
                        value is <literal>.</literal> (a dot).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>S</term>
                <listitem>
                    <para>
                        a <literal>tlist</literal> of type <literal>dir</literal> with fields :
                        <literal>name</literal>, <literal>date</literal>, <literal>bytes</literal> and <literal>isdir</literal>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <function>dir</function> can be used to get the files which match
            the patterns given by the <varname>path</varname> argument.
            Patterns are given to the Unix <command>ls</command> or to the Windows
            <command>dir</command> commands in order to get information about files.
            Thus in order to write portable Scilab script valid wildcard patterns
            for both OS are to be given. Note that pathname conversion is
            performed and for example <literal>SCI/modules/core/macros/*.sci</literal>
            is a valid pattern for both Unix and Windows.
        </para>
        <para>
            The <literal>name</literal> field of the returned variable is the column vector
            of the file names.
        </para>
        <para>
            The <literal>date</literal> field of the returned variable is the column vector
            of integers containing a last modification date coded in second from 1 Jan 1970.
        </para>
        <para>
            The <literal>bytes</literal> field of the returned variable is the column vector
            of integers containing the size of the files in bytes.
        </para>
        <para>
            The <literal>isdir</literal> field of the returned variable is the column vector
            of boolean true if the corresponding name is a directory.
        </para>
        <para>
            The default display of the returned structure is a column formatted list
            of files. It can be changed redefining the function <function>%dir_p</function>.
        </para>
        <para>
            Since Scilab 5.3.1, a trailing "/" or "\" (see <link linkend="filesep">filesep</link>) is displayed for each directory.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
dir
dir SCI/modules/core/macros/*.bin
x=dir('SCI/modules/core/macros/*.bin')
dt=getdate(x.date);
mprintf("%s: %04d-%02d-%02d %02d:%02d:%02d\n",x.name,dt(:,[1 2 6 7:9]))
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="listfiles">listfiles</link>
            </member>
            <member>
                <link linkend="findfiles">findfiles</link>
            </member>
            <member>
                <link linkend="ls">ls</link>
            </member>
            <member>
                <link linkend="fileinfo">fileinfo</link>
            </member>
            <member>
                <link linkend="date">date</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
