b47caddf3480b618d3fedbae94b9549c1c0cff25
[scilab.git] / scilab / modules / fileio / help / en_US / dir.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  * 
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at    
11  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
12  *
13  -->
14 <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" version="5.0-subset Scilab" xml:lang="en" xml:id="dir">
15     <refnamediv>
16         <refname>dir</refname>
17         <refpurpose>gets file list </refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Calling Sequence</title>
21         <synopsis>dir path
22             S=dir([path])
23         </synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Arguments</title>
27         <variablelist>
28             <varlistentry>
29                 <term>path</term>
30                 <listitem>
31                     <para>a string matrix giving a directory pathname (eventually  ended
32                         by a pattern built with <literal>*</literal>). Default
33                         value is <literal>.</literal> (a dot).
34                     </para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>S</term>
39                 <listitem>
40                     <para>
41                         a <literal>tlist</literal> of type <literal>dir</literal> with fields :
42                         <literal>name</literal>, <literal>date</literal>, <literal>bytes</literal> and <literal>isdir</literal>.
43                     </para>
44                 </listitem>
45             </varlistentry>
46         </variablelist>
47     </refsection>
48     <refsection>
49         <title>Description</title>
50         <para>
51             <function>dir</function> can be used to get the files which match 
52             the patterns given by the <varname>path</varname> argument. 
53             Patterns are given to the Unix <command>ls</command> or to the Windows
54             <command>dir</command> commands in order to get information about files. 
55             Thus in order to write portable Scilab script valid wildcard patterns 
56             for both OS are to be given. Note that pathname conversion is
57             performed and for example <literal>SCI/modules/core/macros/*.sci</literal>
58             is a valid pattern for both Unix and Windows.
59         </para>
60         <para>
61             The <literal>name</literal> field of the returned variable is the column vector
62             of the file names.
63         </para>
64         <para>
65             The <literal>date</literal> field of the returned variable is the column vector
66             of integers containing a last modification date coded in second from 1 Jan 1970.
67         </para>
68         <para>
69             The <literal>bytes</literal> field of the returned variable is the column vector
70             of integers containing the size of the files in bytes.
71         </para>
72         <para>
73             The <literal>isdir</literal> field of the returned variable is the column vector
74             of boolean true if the corresponding name is a directory.
75         </para>
76         <para>
77             The default display of the returned structure is a column formatted list
78             of files. It can be changed redefining the function <function>%dir_p</function>.
79         </para>
80         <para>
81             Since Scilab 5.3.1, a trailing "/" or "\" (See <link linkend="filesep">filesep</link>) is displayed for each directory.
82         </para>
83     </refsection>
84     <refsection>
85         <title>Examples</title>
86         <programlisting role="example"><![CDATA[ 
87 dir
88 dir SCI/modules/core/macros/*.bin
89 x=dir('SCI/modules/core/macros/*.bin')
90 dt=getdate(x.date);
91 mprintf("%s: %04d-%02d-%02d %02d:%02d:%02d\n",x.name,dt(:,[1 2 6 7:9]))
92  ]]></programlisting>
93     </refsection>
94     <refsection role="see also">
95         <title>See Also</title>
96         <simplelist type="inline">
97             <member>
98                 <link linkend="listfiles">listfiles</link>
99             </member>
100             <member>
101                 <link linkend="findfiles">findfiles</link>
102             </member>
103             <member>
104                 <link linkend="ls">ls</link>
105             </member>
106             <member>
107                 <link linkend="fileinfo">fileinfo</link>
108             </member>
109             <member>
110                 <link linkend="date">date</link>
111             </member>
112         </simplelist>
113     </refsection>
114 </refentry>