* fileinfo can now take a row vector as input.
[scilab.git] / scilab / modules / fileio / help / en_US / fileinfo.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) XXXX-2008 - INRIA
5  *
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
11  *
12  -->
13 <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="fileinfo" xml:lang="en">
14     <refnamediv>
15         <refname>fileinfo</refname>
16         <refpurpose>provides information about a file</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>[x, ierr] = fileinfo(files)</synopsis>
21     </refsynopsisdiv>
22     <refsection>
23         <title>Arguments</title>
24         <variablelist>
25             <varlistentry>
26                 <term>files</term>
27                 <listitem>
28                     <para>
29                         a character string or a string vector, file pathname.
30                     </para>
31                 </listitem>
32             </varlistentry>
33             <varlistentry>
34                 <term>x</term>
35                 <listitem>
36                     <para>
37                         an integer vector of size 13 containing information or an empty matrix if file does not exist.
38                     </para>
39                     <para>
40                         If <varname>files</varname> is a string 1 x m or m x 1 vector, <varname>x</varname> will be a matrix of size <literal>m x 13</literal>.
41                     </para>
42                     <para>
43                         If a filename does not exist, it will return as output information a line of size 13 with <constant>Nan</constant> in each element of this line.
44                     </para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>ierr</term>
49                 <listitem>
50                     <para>error indicator, 0, if no error has occurred.</para>
51                 </listitem>
52             </varlistentry>
53         </variablelist>
54     </refsection>
55     <refsection>
56         <title>Description</title>
57         <para>
58             <code>x = fileinfo(file)</code> returns:
59         </para>
60         <variablelist>
61             <varlistentry>
62                 <term>x(1)</term>
63                 <listitem>
64                     <para>The file size</para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>x(2)</term>
69                 <listitem>
70                     <para>The file mode (decimal value)</para>
71                 </listitem>
72             </varlistentry>
73             <varlistentry>
74                 <term>x(3)</term>
75                 <listitem>
76                     <para>The user id</para>
77                 </listitem>
78             </varlistentry>
79             <varlistentry>
80                 <term>x(4)</term>
81                 <listitem>
82                     <para>The group id</para>
83                 </listitem>
84             </varlistentry>
85             <varlistentry>
86                 <term>x(5)</term>
87                 <listitem>
88                     <para>The device number</para>
89                 </listitem>
90             </varlistentry>
91             <varlistentry>
92                 <term>x(6)</term>
93                 <listitem>
94                     <para>The date of last data modification</para>
95                 </listitem>
96             </varlistentry>
97             <varlistentry>
98                 <term>x(7)</term>
99                 <listitem>
100                     <para>The date of last file status change</para>
101                 </listitem>
102             </varlistentry>
103             <varlistentry>
104                 <term>x(8)</term>
105                 <listitem>
106                     <para>The date of last access</para>
107                 </listitem>
108             </varlistentry>
109             <varlistentry>
110                 <term>x(9)</term>
111                 <listitem>
112                     <para>The device type (if inode device)</para>
113                 </listitem>
114             </varlistentry>
115             <varlistentry>
116                 <term>x(10)</term>
117                 <listitem>
118                     <para>The blocksize for filesystem I/O (always 0 on Windows)</para>
119                 </listitem>
120             </varlistentry>
121             <varlistentry>
122                 <term>x(11)</term>
123                 <listitem>
124                     <para>The number of blocks allocated (always 0 on Windows)</para>
125                 </listitem>
126             </varlistentry>
127             <varlistentry>
128                 <term>x(12)</term>
129                 <listitem>
130                     <para>The inode</para>
131                 </listitem>
132             </varlistentry>
133             <varlistentry>
134                 <term>x(13)</term>
135                 <listitem>
136                     <para>The number of hard links</para>
137                 </listitem>
138             </varlistentry>
139         </variablelist>
140     </refsection>
141     <refsection>
142         <title>References</title>
143         <para>
144             This function is an interface to the C function <function>stat</function>.
145         </para>
146         <para>
147             Permissions are typically specified as octal numbers: <code>dec2oct(x(2))</code> to convert.
148         </para>
149         <para>Numeric mode is from one to four octal digits (0-7), derived by
150             adding up the bits with values 4, 2, and 1. Any omitted digits are assumed
151             to be leading zeros. The first digit selects the set user ID (4) and set
152             group ID (2) and sticky (1) attributes. The second digit selects
153             permissions for the user who owns the file: read (4), write (2), and
154             execute (1); the third selects permissions for other users in the file's
155             group, with the same values; and the fourth for other users not in the
156             file's group, with the same values. 
157         </para>
158         <para>
159             So, to check permissions, it is necessary to use masks. Let us take an example:
160             In octal, x(2)=1664, so first digit corresponds to sticky attributes. The second
161             indicates that file owner has permission of writing and reading. It is the same
162             for other users in the file's group. Finally, others users has just right to read.
163             To apply a mask, it is simpler to look at this octal in binary. 
164             So: <varname>x</varname>(2)= 1 110 110 100.
165             To check if the owner has write permission, we must take a look at the second triplet: 110 
166             and compare it with write permission 010. So, the operation is: 110 000 000 &amp; 010 000 000.
167             If result is not null (it is the case here), owner has write permission.
168         </para>
169     </refsection>
170     <refsection>
171         <title>Examples</title>
172         <programlisting role="example"><![CDATA[ 
173 w = fileinfo(SCI+'/etc/scilab.start')
174 // file permission
175 dec2oct(w(2))
176 // file date
177 getdate(w(6))
178
179 // Permissions
180 S_IWRITE = 128; // mask write permission
181 S_IEXEC = 64; // mask exec permission
182 S_IREAD = 256; // mask read permission
183 S_IFCHR = 8192; // mask directory permission
184
185 // Checks write permission
186 if ( bitand( w(2), S_IWRITE ) <> 0) then
187  disp('WRITE PERMISSION on this file.');
188 else
189  disp('NO WRITE PERMISSION on this file.');
190 end
191 // Checks read permission
192 if ( bitand( w(2), S_IREAD ) <> 0) then
193  disp('READ PERMISSION on this file.');
194 else
195  disp('NO READ PERMISSION on this file.');
196 end
197
198 FILES = [SCI;SCIHOME;'not_exist_file';TMPDIR]
199 [X,ERRS] = fileinfo(FILES)
200  ]]></programlisting>
201     </refsection>
202     <refsection role="see also">
203         <title>See Also</title>
204         <simplelist type="inline">
205             <member>
206                 <link linkend="getdate">getdate</link>
207             </member>
208             <member>
209                 <link linkend="file">file</link>
210             </member>
211             <member>
212                 <link linkend="dispfiles">dispfiles</link>
213             </member>
214             <member>
215                 <link linkend="newest">newest</link>
216             </member>
217             <member>
218                 <link linkend="isdir">isdir</link>
219             </member>
220         </simplelist>
221     </refsection>
222     <refsection>
223         <title>History</title>
224         <revhistory>
225             <revision>
226                 <revnumber>6.0.0</revnumber>
227                 <revremark>
228                     <literal>files</literal> can now be a row vector.
229                 </revremark>
230             </revision>
231         </revhistory>
232     </refsection>
233 </refentry>