* Bug #15472 fixed - mdelete('test') worked like mdelete('test.*') under Windows
[scilab.git] / scilab / modules / fileio / help / en_US / listfiles.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:lang="en" xml:id="listfiles">
20     <refnamediv>
21         <refname>listfiles</refname>
22         <refpurpose>list of files</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>files = listfiles(paths [, flag, flagexpand])</synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>paths</term>
33                 <listitem>
34                     <para>
35                         a string matrix giving a set of pathnames (eventually  ended by a pattern built with <literal>*</literal>).
36                     </para>
37                 </listitem>
38             </varlistentry>
39             <varlistentry>
40                 <term>flag, flagexpand</term>
41                 <listitem>
42                     <para>
43                         boolean optional parameters (default value is <constant>%t</constant>).
44                     </para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>files</term>
49                 <listitem>
50                     <para>a string matrix.</para>
51                 </listitem>
52             </varlistentry>
53         </variablelist>
54     </refsection>
55     <refsection>
56         <title>Description</title>
57         <para>
58             <function>listfiles</function> can be used to list the files which match
59             the patterns given by one of the paths entries.
60             Patterns are given to the Unix <command>ls</command> or to the Windows
61             <command>dir</command> commands in order to get information about files.
62             Thus in order to write portable Scilab script valid wildcard patterns
63             for both OS are to be given. Note that pathname conversion is
64             performed and for example <literal>SCI/core/macros/*.sci</literal> is a valid
65             pattern for both Unix and Windows.
66         </para>
67         <para>
68             If <varname>flag</varname> is true the pathnames given by
69             <varname>paths</varname> are converted according to the <code>getos() == 'Windows'</code>
70             value (see also <link linkend="pathconvert">pathconvert</link>).
71             Moreover, if <varname>flagexpand</varname> is true leading strings like
72             <literal>SCIHOME</literal>, <literal>SCI</literal> or
73             <literal>~</literal> are expanded using environment variables.
74         </para>
75         <para>
76             If the input argument <varname>paths</varname> is the name of a directory, the returned <varname>files</varname>
77             are the names relative to that directory.
78         </para>
79         <para>
80             If the input argument <varname>paths</varname> contains more than one element, or if it contains
81             a pattern (e.g. <literal>"/*"</literal>, <literal>"*.c"</literal>), the returned <varname>files</varname> are the absolute paths (i.e.
82             file name prepended with the name of the directory).
83         </para>
84     </refsection>
85     <refsection>
86         <title>Examples</title>
87         <programlisting role="example">
88             <![CDATA[
89 files=listfiles(['SCI/modules/core/macros/*.sci';'SCI/modules/core/macros/*.bin']);
90  ]]>
91         </programlisting>
92     </refsection>
93     <refsection role="see also">
94         <title>See also</title>
95         <simplelist type="inline">
96             <member>
97                 <link linkend="findfiles">findfiles</link>
98             </member>
99             <member>
100                 <link linkend="basename">basename</link>
101             </member>
102             <member>
103                 <link linkend="pathconvert">pathconvert</link>
104             </member>
105         </simplelist>
106     </refsection>
107     <refsection>
108         <title>History</title>
109         <revhistory>
110             <revision>
111                 <revnumber>5.4.0</revnumber>
112                 <revremark>If paths is not a single string, all returned files are homogenized with the absolute path form.</revremark>
113             </revision>
114             <revision>
115                 <revnumber>6.0.2</revnumber>
116                 <revremark>
117                     Under Windows, up to 6.0.1, <literal>listfile("test")</literal> actually
118                     performed <literal>listfile("test.*")</literal>. It is no longer the case.
119                 </revremark>
120             </revision>
121         </revhistory>
122     </refsection>
123 </refentry>