<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) XXXX-2008 - INRIA
 * Copyright (C) 2018 - Samuel GOUGEON
 * Copyright (C) 2018 - Stanislav KROTER
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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="ru">
    <refnamediv>
        <refname>fileinfo</refname>
        <refpurpose>предоставляет информацию о файле</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Синтаксис</title>
        <synopsis>
             x = fileinfo(filesPaths)
            [x,ierr] = fileinfo(filesPaths)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Аргументы</title>
        <variablelist>
            <varlistentry>
                <term>filesPaths</term>
                <listitem>
                    <para>
                        вектор или матрица путей (в виде текста). Файлы могут быть любого типа:
                        обычные файлы, директории (внутри собственные директории), ярлыки, символьные
                        ссылки, и т.д.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x</term>
                <listitem>
                    <para>
                        матрицы или десятичные целые числа размером (m,13), где m: число
                        указанных путей файлов. Строка №i возвращает информацию о файле
                        <literal>filesPaths(i)</literal>.
                    </para>
                   <para>
                     Если запрошен единственный путь, а файла не существует, то <varname>x</varname>
                     возвращается в виде [].
                    </para>
                    <para>
                        Если запрошено несколько файлов: когда файла среди них не существует, то функция
                        возвращает <varname>x</varname>, в котором строка заполнена значениями <constant>Nan</constant>.
                    </para>
                    <para>
                        <table>
                            <tr><th>столбец x</th><th align="left">Описание</th></tr>
                            <tr><td align="center" valign="top">1 : </td>
                                <td>фактический размер файла (байты). 0 для директории.</td>
                            </tr>
                            <tr><td align="center" valign="top">2 : </td>
                                <td>права файла (см. описание)</td>
                            </tr>
                            <tr><td align="center" valign="top">3 : </td>
                                <td>идентификатор собственника файла (всегда 0 в Windows)</td>
                            </tr>
                            <tr><td align="center" valign="top">4 : </td>
                                <td>идентификатор группы файла (всегда 0 в Windows)</td>
                            </tr>
                            <tr><td align="center" valign="top">5 : </td>
                                <td>номер устройства</td>
                            </tr>
                            <tr><td align="center" valign="top">6 : </td>
                                <td>
                                    временная метка UNIX последней модификации данных.
                                    <literal>getdate(x(:,6))(:,[1 2 6 7 8 9])</literal> возвращает
                                    соответствующую дату в виде матрицы из числовых строк [год месяц день час мин сек].
                                </td>
                            </tr>
                            <tr><td align="center" valign="top">7 : </td>
                                <td>временная метка UNIX последнего изменения статуса файла.</td>
                            </tr>
                            <tr><td align="center" valign="top">8 : </td>
                                <td>временная метка UNIX последнего доступа к файлу.</td>
                            </tr>
                            <tr><td align="center" valign="top">9 : </td>
                                <td>Тип устройства (если узловое устройство).</td>
                            </tr>
                            <tr><td align="center" valign="top">10 : </td>
                                <td>Размер блока файловой системы ввода-вывода (всегда 0 в Windows)</td>
                            </tr>
                            <tr><td align="center" valign="top">11 : </td>
                                <td>Количество блоков распределённых по этому хранилищу файлов
                                    (всегда 0 в Windows)
                                </td>
                            </tr>
                            <tr><td align="center" valign="top">12 : </td>
                                <td>индексный дескриптор файла (уникальный идентификатор) (всегда 0 в Windows)</td>
                            </tr>
                            <tr><td align="center" valign="top">13 : </td>
                                <td>Количество жёстких ссылок, указывающих на этот файл (всегда 1 в Windows).
                                </td>
                            </tr>
                        </table>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ierr</term>
                <listitem>
                    <para>
                        указатель ошибки, 0, если ошибки не произошло.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Описание</title>
        <para>
            Эта функция является интерфейсом к C-функции <function>stat</function>.
        </para>
        <para>
            Права обычно определяются в виде восьмеричных чисел: используйте
            для преобразования <code>dec2oct(x(2))</code>.
        </para>
        <para>
            Числовой режим представляет собой от одной до четырёх восьмеричных цифр
            (0-7), полученных добавлением битов со значениями 4, 2 и
            1. Любые опущенные цифры предполагаются предварёнными
            нулями. Первая цифра выбирает набор атрибутов идентификатора пользователя
            (4), группы пользователя (2) и sticky-бита (1). Вторая цифра
            выбирает права пользователя, который владеет файлом: чтение (4),
            запись (2) и исполнение (1); третье число выбирает права для
            других пользователей в группе файлов с теми же самыми значениями.
        </para>
        <para>
            Таким образом, чтобы проверить права, необходимо использовать маски.
            Например, в восьмеричной системе <varname>x</varname><literal>(2)=1664</literal>,
            таким образом первый элемент соответствует атрибуту sticky-бита (защита
            от удаления и переименования). Второй указывает на то, что владелец
            файла имеет право на запись и чтение. То же самое и для других пользователей
            в группе файла. Наконец, другие пользователи имеют право лишь на чтение.
            Использовать маску проще, чем смотреть на эти восьмеричные коды в
            двоичном виде. Таким образом: <varname>x</varname><literal>(2)= 1 110 110 100</literal>.
            Чтобы проверить имеет ли пользователь право на запись, нужно посмотреть
            на вторую тройку: <literal>110</literal> и сравнить её с правом на запись
            <literal>010</literal>. Таким образом, операция заключается в
            <literal>110 000 000</literal> &amp; <literal>010 000 000</literal>.
            Если результат отличен от нуля (как в данном случае), то пользователь
            имеет право на запись.
        </para>
    </refsection>
    <refsection>
        <title>Примеры</title>
        <programlisting role="example"><![CDATA[
w = fileinfo(SCI+'/etc/scilab.start')
// права на файл
dec2oct(w(2))
// дата файла : [год месяц день час мин сек .сек]
getdate(w(6))(:,[1 2 6:10])
// Проверка прав на запись
w = fileinfo(SCI+'/etc/scilab.start')
S_IWRITE = 128; // маска прав на запись
S_IEXEC = 64; // маска прав на исполнение
S_IREAD = 256; // маска прав на чтение
S_IFCHR = 8192; // маска прав директории
if ( bitand( w(2), S_IWRITE ) <> 0) then
 disp('Для этого файла есть ПРАВО НА ЗАПИСЬ.');
else
 disp('Для этого файла НЕТ ПРАВА НА ЗАПИСЬ.');
end
FILES = [SCI;SCIHOME;'несуществующий_файл';TMPDIR]
[X,ERRS] = fileinfo(FILES)
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Смотрите также</title>
        <simplelist type="inline">
            <member>
                <link linkend="getdate">getdate</link>
            </member>
            <member>
                <link linkend="file">file</link>
            </member>
            <member>
                <link linkend="dispfiles">dispfiles</link>
            </member>
            <member>
                <link linkend="newest">newest</link>
            </member>
            <member>
                <link linkend="isfile">isfile</link>
            </member>
            <member>
                <link linkend="isdir">isdir</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>История</title>
        <revhistory>
            <revision>
                <revnumber>6.0.0</revnumber>
                <revremark>
                    Теперь могут быть обработаны несколько путей файлов.
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
