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>