[doc] misc. patchs & small improvements
[scilab.git] / scilab / modules / io / help / en_US / file.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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2018 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19           xmlns:scilab="http://www.scilab.org" xml:id="file" xml:lang="en">
20     <refnamediv>
21         <refname>file</refname>
22         <refpurpose>file management</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             [unit, err] = file("open", file-name [,status] [,access [,recl]] [,format])
28             file("close", unit)
29             file("rewind", unit)
30             file("backspace", unit)
31             file("last", unit)
32             [units, typ, nams, mod, swap] = file()
33             [units, typ, nams, mod, swap] = file(unit)
34         </synopsis>
35     </refsynopsisdiv>
36     <refsection>
37         <title>Arguments</title>
38         <variablelist>
39             <varlistentry>
40                 <term>file-name</term>
41                 <listitem>
42                     <para>string, file name of the file to be opened</para>
43                     <warning>
44                         This function can not open files whose path has non-ascii
45                         UTF characters (accented, etc). In this case, mopen() must be used.
46                     </warning>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>status</term>
51                 <listitem>
52                     <para>string, The status of the file to be opened</para>
53                     <variablelist>
54                         <varlistentry>
55                             <term>"new"</term>
56                             <listitem>
57                                 <para>file must not exist new file (default)</para>
58                             </listitem>
59                         </varlistentry>
60                         <varlistentry>
61                             <term>"old"</term>
62                             <listitem>
63                                 <para>file must already exists.</para>
64                             </listitem>
65                         </varlistentry>
66                         <varlistentry>
67                             <term>"unknown"</term>
68                             <listitem>
69                                 <para>unknown status</para>
70                             </listitem>
71                         </varlistentry>
72                         <varlistentry>
73                             <term>"scratch"</term>
74                             <listitem>
75                                 <para>file is to be deleted at end of session</para>
76                             </listitem>
77                         </varlistentry>
78                     </variablelist>
79                 </listitem>
80             </varlistentry>
81             <varlistentry>
82                 <term>access</term>
83                 <listitem>
84                     <para>string, The type of access to the file</para>
85                     <variablelist>
86                         <varlistentry>
87                             <term>"sequential"</term>
88                             <listitem>
89                                 <para>sequential access (default)</para>
90                             </listitem>
91                         </varlistentry>
92                         <varlistentry>
93                             <term>"direct"</term>
94                             <listitem>
95                                 <para>direct access.</para>
96                             </listitem>
97                         </varlistentry>
98                     </variablelist>
99                 </listitem>
100             </varlistentry>
101             <varlistentry>
102                 <term>format</term>
103                 <listitem>
104                     <para>string,</para>
105                     <variablelist>
106                         <varlistentry>
107                             <term>"formatted"</term>
108                             <listitem>
109                                 <para>for a formatted file (default)</para>
110                             </listitem>
111                         </varlistentry>
112                         <varlistentry>
113                             <term>"unformatted"</term>
114                             <listitem>
115                                 <para>binary record.</para>
116                             </listitem>
117                         </varlistentry>
118                     </variablelist>
119                 </listitem>
120             </varlistentry>
121             <varlistentry>
122                 <term>recl</term>
123                 <listitem>
124                     <para>integer,is the size of records in bytes when
125                         <literal>access="direct"</literal>
126                     </para>
127                 </listitem>
128             </varlistentry>
129             <varlistentry>
130                 <term>unit</term>
131                 <listitem>
132                     <para>integer, logical unit descriptor of the opened file</para>
133                 </listitem>
134             </varlistentry>
135             <varlistentry>
136                 <term>units</term>
137                 <listitem>
138                     <para>integer vector, logical unit descriptor of the opened files.
139                         Units 5 and 6 (%io) are reserved by the system for input and output
140                         devices.
141                     </para>
142                 </listitem>
143             </varlistentry>
144             <varlistentry>
145                 <term>typs</term>
146                 <listitem>
147                     <para>Character string vector, type (C or Fortran) of opened
148                         files.
149                     </para>
150                 </listitem>
151             </varlistentry>
152             <varlistentry>
153                 <term>nams</term>
154                 <listitem>
155                     <para>Character string vector, pathnames of opened files.</para>
156                 </listitem>
157             </varlistentry>
158             <varlistentry>
159                 <term>mod</term>
160                 <listitem>
161                     <para>file opening mode. Formed by three digits abc:</para>
162                     <table border="0">
163                         <tr valign="top">
164                             <td colspan="2">><emphasis role="bold">Fortran files</emphasis></td>
165                         </tr>
166                         <tr valign="top">
167                             <th>a</th>
168                             <td>0 stands for formatted and 1 for unformatted (binary)</td>
169                         </tr>
170                         <tr valign="top">
171                             <th>b</th>
172                             <td>0 stands for sequential access and 1 for direct access</td>
173                         </tr>
174                         <tr valign="top">
175                             <th>c</th>
176                             <td>0 stands for "new", 1 for "old", 2 for "scratch" and 3 for "unknown"</td>
177                         </tr>
178                         <tr valign="top">
179                             <td colspan="2"><emphasis role="bold">C files</emphasis></td>
180                         </tr>
181                         <tr valign="top">
182                             <th>a</th>
183                             <td>1 stands for "r" (read), 2 stands for "w" (write)  and 3 for "a" (append)</td>
184                         </tr>
185                         <tr valign="top">
186                             <th>b</th>
187                             <td>is 1 if file has been opened with a "+" (updating) mode</td>
188                         </tr>
189                         <tr valign="top">
190                             <th>c</th>
191                             <td>is 1 if file has been opened with a "b" (binary) mode</td>
192                         </tr>
193                     </table>
194                 </listitem>
195             </varlistentry>
196             <varlistentry>
197                 <term>swap</term>
198                 <listitem>
199                     <para>automatic swap switch. swap=1 if automatic swap is on. swap is
200                         always 0 for Fortran files.
201                     </para>
202                 </listitem>
203             </varlistentry>
204             <varlistentry>
205                 <term>err</term>
206                 <listitem>
207                     <para>integer code returned if opening the file fails. If <varname>err</varname>
208                     is omitted, an error message is issued.
209                     </para>
210                     <table>
211                         <tr valign="top"><th>65</th><td>File already used</td></tr>
212                         <tr valign="top"><th>66</th><td>Too many files opened!</td></tr>
213                         <tr valign="top"><th>67</th><td>Unknown file format</td></tr>
214                         <tr valign="top"><th>240</th>
215                                          <td>The file already exists or directory write
216                                              access denied.</td></tr>
217                         <tr valign="top"><th>241</th><td>The file does not exist or read access denied.</td></tr>
218                     </table>
219                 </listitem>
220             </varlistentry>
221         </variablelist>
222     </refsection>
223     <refsection>
224         <title>Description</title>
225         <para>
226             <literal>file(…)</literal> selects a logical unit <varname>unit</varname> and manages
227             the file <varname>file-name</varname>.
228         </para>
229         <variablelist>
230             <varlistentry>
231                 <term>[unit [,err]]=file("open", file-name [,status] [,access [,recl]][,format])
232                 </term>
233                 <listitem>
234                     <para>
235                         allows to open a file with specified
236                         properties and to get the associated unit number <varname>unit</varname>.
237                         This unit number may be used for further actions on this file or as file
238                         descriptor in <function>read</function>, <function>write</function>,
239                         <function>readb</function>,
240                         <function>writb</function>,<function>save</function>, <function>load</function>
241                         function calls.
242                     </para>
243                 </listitem>
244             </varlistentry>
245             <varlistentry>
246                 <term>
247                     file("close", unit)
248                 </term>
249                 <listitem>
250                     <para>
251                         allows to close the file, or move the current file pointer.
252                     </para>
253                 </listitem>
254             </varlistentry>
255             <varlistentry>
256                 <term>
257                     file("rewind", unit)
258                 </term>
259                 <listitem>
260                     <para>
261                         puts the pointer at the beginning of the file.
262                     </para>
263                 </listitem>
264             </varlistentry>
265             <varlistentry>
266                 <term>
267                     file("backspace", unit)
268                 </term>
269                 <listitem>
270                     <para>
271                         puts the pointer at the beginning of last record.
272                     </para>
273                 </listitem>
274             </varlistentry>
275             <varlistentry>
276                 <term>
277                     file("last", unit)
278                 </term>
279                 <listitem>
280                     <para>
281                         puts the pointer after last record.
282                     </para>
283                 </listitem>
284             </varlistentry>
285             <varlistentry>
286                 <term>
287                     file()
288                 </term>
289                 <listitem>
290                     <para>
291                         returns the descriptors of the opened files.
292                     </para>
293                     <para>To test whether a file whose unit is <literal>id</literal> is opened,
294                         <literal>file(id)~=[]</literal> may be used.
295                     </para>
296                     <para>To close all user opened files (C or Fortran type),
297                         <literal>file("close",file())</literal> may be used.
298                     </para>
299                 </listitem>
300             </varlistentry>
301         </variablelist>
302     </refsection>
303     <refsection>
304         <title>Examples</title>
305         <programlisting role="example"><![CDATA[
306 u=file("open",TMPDIR+"/foo","unknown")
307 for k=1:4
308   a=rand(1,4)
309   write(u,a)
310 end
311 file("rewind",u)
312 x=read(u,2,4)
313 file("close",u)
314 //
315 u1=file("open",TMPDIR+"/foo","unknown")
316 u2=mopen(TMPDIR+"/foo1","wb")
317 [units,typs,nams]=file()
318 file("close",u1);
319 mclose(u2);
320  ]]></programlisting>
321     </refsection>
322     <refsection role="see also">
323         <title>See also</title>
324         <simplelist type="inline">
325             <member>
326                 <link linkend="isfile">isfile</link>
327             </member>
328             <member>
329                 <link linkend="read">read</link>
330             </member>
331             <member>
332                 <link linkend="readb">readb</link>
333             </member>
334             <member>
335                 <link linkend="write">write</link>
336             </member>
337             <member>
338                 <link linkend="writb">writb</link>
339             </member>
340             <member>
341                 <link linkend="mopen">mopen</link>
342             </member>
343             <member>
344                 <link linkend="save">save</link>
345             </member>
346             <member>
347                 <link linkend="load">load</link>
348             </member>
349             <member>
350                 <link linkend="uigetfile">uigetfile</link>
351             </member>
352         </simplelist>
353     </refsection>
354     <refsection role="history">
355         <title>History</title>
356         <revhistory>
357             <revision>
358                 <revnumber>6.0.0</revnumber>
359                 <revdescription>
360                     stderr is inserted in the output of file() as units(1)=0, typ(1)="STD" and
361                     nams(1)="stderr".
362                 </revdescription>
363             </revision>
364         </revhistory>
365     </refsection>
366 </refentry>