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