<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) XXXX-2008 - INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2018 - Samuel GOUGEON
 *
 * 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:ns4="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="file" xml:lang="pt">
    <refnamediv>
        <refname>file</refname>
        <refpurpose>Gerenciamento de arquivos</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</title>
        <synopsis>
            [unit, err] = file("open", file-name [,status] [,access [,recl]] [,format])
            file("close", unit)
            file("rewind", unit)
            file("backspace", unit)
            file("last", unit)
            [units, typ, nams, mod, swap] = file()
            [units, typ, nams, mod, swap] = file(unit)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parâmetros</title>
        <variablelist>
            <varlistentry>
                <term>file-name</term>
                <listitem>
                    <para>string, nome o arquivo a ser aberto</para>
                    <warning>
                        This function can not open files whose path has non-ascii
                        UTF characters (accented, etc). In this case, please use mopen.
                    </warning>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>status</term>
                <listitem>
                    <para>string, o status do arquivo a ser aberto</para>
                    <variablelist>
                        <varlistentry>
                            <term>"new"</term>
                            <listitem>
                                <para>o arquivo não deve existir, novo arquivo (padrão)</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>"old"</term>
                            <listitem>
                                <para>o arquivo já deve existir</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>"unknown"</term>
                            <listitem>
                                <para>status desconhecido</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>"scratch"</term>
                            <listitem>
                                <para>o arquivo deve ser deletado ao fim da sessão</para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>access</term>
                <listitem>
                    <para>string, o tipo de acesso ao arquivo</para>
                    <variablelist>
                        <varlistentry>
                            <term>"sequential"</term>
                            <listitem>
                                <para>acesso seqüencial (padrão)</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>"direct"</term>
                            <listitem>
                                <para>acesso direto</para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>format</term>
                <listitem>
                    <para>string,</para>
                    <variablelist>
                        <varlistentry>
                            <term>"formatted"</term>
                            <listitem>
                                <para>para um arquivo formatado (padrão)</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>"unformatted"</term>
                            <listitem>
                                <para>registro binário</para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>recl</term>
                <listitem>
                    <para>inteiro, é o tamanho de registros quando
                        <literal>access="direct"</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>unit</term>
                <listitem>
                    <para>inteiro, descritor de unidade lógica do arquivo aberto</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>units</term>
                <listitem>
                    <para>vetor de inteiros, descritores de unidades lógicas dos
                        arquivos abertos. As unidades 5 e 6 são reservadas pelo sistema para
                        dispositivos de entrada e saída.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>typs</term>
                <listitem>
                    <para>vetor de strings, tipo (C ou Fortran) dos arquivos
                        abertos.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>nams</term>
                <listitem>
                    <para>vetor de strings, endereços dos arquivos abertos.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mod</term>
                <listitem>
                    <para>modo de abertura de arquivo. Formado por três dígitos abc:
                    </para>
                    <table border="0">
                        <tr valign="top">
                            <td colspan="2"><emphasis role="bold">Arquivos Fortran</emphasis></td>
                        </tr>
                        <tr valign="top">
                            <th>a</th>
                            <td>0 significa formatado e 1 não formatado (binário)</td>
                        </tr>
                        <tr valign="top">
                            <th>b</th>
                            <td>0 significa acesso sequencial e 1 acesso direto</td>
                        </tr>
                        <tr valign="top">
                            <th>c</th>
                            <td>0 significa "new", 1 significa "old", 2 significa "scratch" e 3
                                significa "unknown"
                            </td>
                        </tr>
                        <tr valign="top">
                            <td colspan="2"><emphasis role="bold">Arquivos C</emphasis></td>
                        </tr>
                        <tr valign="top">
                            <th>a</th>
                            <td>1 significa "r" (leitura), 2 significa "w" (escrita) e 3 significa
                                "a" (anexação)</td>
                        </tr>
                        <tr valign="top">
                            <th>b</th>
                            <td>é 1 se o arquivo foi aberto pelo modo "+" (atualização)</td>
                        </tr>
                        <tr valign="top">
                            <th>c</th>
                            <td>é 1 se o arquivo foi aberto pelo modo "b" (binário)</td>
                        </tr>
                    </table>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>swap</term>
                <listitem>
                    <para>alavanca de troca automática. swap=1 se a troca automática
                        estiver ativada. swap é sempre 0 para arquivos Fortran.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>err</term>
                <listitem>
                    <para>
                    </para>
                    <para>inteiro, número de erro, se a abertura falha. Se <varname>err</varname>
                    for omitido, uma mensagem de erro aparece.
                    </para>
                    <table>
                        <tr valign="top"><th>65</th><td>File already used</td></tr>
                        <tr valign="top"><th>66</th><td>Too many files opened!</td></tr>
                        <tr valign="top"><th>67</th><td>Unknown file format</td></tr>
                        <tr valign="top"><th>240</th>
                                         <td>The file already exists or directory write
                                             access denied.</td></tr>
                        <tr valign="top"><th>241</th><td>The file does not exist or read access denied.</td></tr>
                    </table>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>action</term>
                <listitem>
                    <para>é um dos seguintes strings:</para>
                    <variablelist>
                        <varlistentry>
                            <term>"close"</term>
                            <listitem>
                                <para>fecha os arquivos fornecidos pelos descritores de
                                    unidades lógicas fornecidos em <literal>units</literal>
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>"rewind"</term>
                            <listitem>
                                <para>coloca o ponteiro no início do arquivo</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>"backspace"</term>
                            <listitem>
                                <para>coloca o ponteiro no início do último registro.</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>"last"</term>
                            <listitem>
                                <para>coloca o ponteiro após o último registro.</para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Descrição</title>
        <para>
            Seleciona uma unidade lógica <literal>unit</literal> e gerencia o
            arquivo <literal>file-name</literal>.
        </para>
        <para>
            <literal>[unit [,err]]=file('open', file-name [,status] [,access
                [,recl]][,format])
            </literal>
            permite abrir um arquivo com propriedades
            especificadas e obter o número de unidade associado
            <literal>unit</literal>. Este número de unidade pode ser utilizado para
            ações futuras no arquivo, ou como descritor de arquivo em chamadas às
            funções <literal>read</literal>, <literal>write</literal>,
            <literal>readb</literal>,
            <literal>writb</literal>,<literal>save</literal>,
            <literal>load</literal>.
        </para>
        <para>
            <literal>file(action,unit)</literal> permite fechar o arquivo, ou
            mover o ponteiro do arquivo corrente.
        </para>
        <para>
            <literal>file()</literal> retorna os descritores dos arquivos abertos.
        </para>
        <para>To test whether a file  #<literal>id</literal> is opened,
            <literal>file(id)~=[]</literal> may be used.
        </para>
        <para>
            <literal>file('close',file() )</literal> fecha
            todos os arquivos do usuário abertos (tipo C ou Fortran).
        </para>
    </refsection>
    <refsection>
        <title>Exemplos</title>
        <programlisting role="example"><![CDATA[
u=file('open',TMPDIR+'/foo','unknown')
for k=1:4
  a=rand(1,4)
  write(u,a)
end
file('rewind',u)
x=read(u,2,4)
file('close',u)
//
u1=file('open',TMPDIR+'/foo','unknown')
u2=mopen(TMPDIR+'/foo1','wb')
[units,typs,nams]=file()
file('close',u1);
mclose(u2);
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Ver Também</title>
        <simplelist type="inline">
            <member>
                <link linkend="isfile">isfile</link>
            </member>
            <member>
                <link linkend="read">read</link>
            </member>
            <member>
                <link linkend="readb">readb</link>
            </member>
            <member>
                <link linkend="write">write</link>
            </member>
            <member>
                <link linkend="writb">writb</link>
            </member>
            <member>
                <link linkend="mopen">mopen</link>
            </member>
            <member>
                <link linkend="save">save</link>
            </member>
            <member>
                <link linkend="load">load</link>
            </member>
            <member>
                <link linkend="uigetfile">uigetfile</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>Histórico</title>
        <revhistory>
            <revision>
                <revnumber>6.0.0</revnumber>
                <revdescription>
                    stderr is inserted in the output of file() as units(1)=0, typ(1)="STD" and
                    nams(1)="stderr".
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
