8b948a3c9b68d2d7a63ad0028136c3c8673bfeb1
[scilab.git] / scilab / modules / fileio / help / en_US / mopen.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) 2008 - INRIA
5  * Copyright (C) 2011 - DIGITEO - Allan CORNET
6  *
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
12  *
13  -->
14 <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="mopen" xml:lang="en">
15     <refnamediv>
16         <refname>mopen</refname>
17         <refpurpose>opens a file in Scilab</refpurpose>
18     </refnamediv>
19     <refsynopsisdiv>
20         <title>Calling Sequence</title>
21         <synopsis>[fd, err] = mopen(file [, mode, swap ])</synopsis>
22     </refsynopsisdiv>
23     <refsection>
24         <title>Arguments</title>
25         <variablelist>
26             <varlistentry>
27                 <term>file</term>
28                 <listitem>
29                     <para>a character string. The pathname of the file to open.</para>
30                 </listitem>
31             </varlistentry>
32             <varlistentry>
33                 <term>mode</term>
34                 <listitem>
35                     <para>
36                         a character string that controls whether the file is opened for 
37                         reading (<literal>r</literal>), writing (<literal>w</literal>), 
38                         or appending (<literal>a</literal>) and whether the file is 
39                         opened for updating (<literal>+</literal>). The 
40                         <varname>mode</varname> can also include a <literal>b</literal> 
41                         parameter to indicate a binary file.
42                     </para>
43                     <para>
44                         The default value is <literal>'rb'</literal>.
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>swap</term>
50                 <listitem>
51                     <para>
52                         a scalar. If <varname>swap</varname> is present and
53                         <code>swap = 0</code> then automatic bytes swap is
54                         disabled.
55                     </para>
56                     <para>The default value is 1.</para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>err</term>
61                 <listitem>
62                     <para>a scalar. Error indicator.</para>
63                     <informaltable border="1">
64                         <tr>
65                             <td>error value:</td>
66                             <td>error message:</td>
67                         </tr>
68                         <tr>
69                             <td>0</td>
70                             <td>No error</td>
71                         </tr>
72                         <tr>
73                             <td>-1</td>
74                             <td>no more logical units</td>
75                         </tr>
76                         <tr>
77                             <td>-2</td>
78                             <td>cannot open file</td>
79                         </tr>
80                         <tr>
81                             <td>-3</td>
82                             <td>no more memory</td>
83                         </tr>
84                         <tr>
85                             <td>-4</td>
86                             <td>invalid name</td>
87                         </tr>
88                         <tr>
89                             <td>-5</td>
90                             <td>invalid status</td>
91                         </tr>
92                     </informaltable>
93                 </listitem>
94             </varlistentry>
95             <varlistentry>
96                 <term>fd</term>
97                 <listitem>
98                     <para>
99                         a scalar: a file descriptor (it's a positive integer).
100                     </para>
101                 </listitem>
102             </varlistentry>
103         </variablelist>
104     </refsection>
105     <refsection>
106         <title>Description</title>
107         <para>
108             <function>mopen</function> may be used to open a <varname>file</varname> in a way
109             compatible with the C <function>fopen</function> procedure. Without 
110             <varname>swap</varname> argument the <varname>file</varname> is supposed to be coded in "little endian IEEE 
111             format" and data are swaped if necessary to match the IEEE format of 
112             the processor.
113         </para>
114         <para>
115             The <varname>mode</varname> parameter controls the access allowed to 
116             the stream. The parameter can have one of the following values. In this 
117             list of values, the <literal>b</literal> character indicates a binary 
118             file.
119         </para>
120         <variablelist>
121             <varlistentry>
122                 <term>r</term>
123                 <listitem>
124                     <para>opens the file for reading.</para>
125                 </listitem>
126             </varlistentry>
127             <varlistentry>
128                 <term>rb</term>
129                 <listitem>
130                     <para>opens a binary file for reading.</para>
131                 </listitem>
132             </varlistentry>
133             <varlistentry>
134                 <term>rt</term>
135                 <listitem>
136                     <para>opens a text file for reading.</para>
137                 </listitem>
138             </varlistentry>
139             <varlistentry>
140                 <term>w</term>
141                 <listitem>
142                     <para>
143                         creates a new file for writing, or opens and truncates a file
144                         to zero length.
145                     </para>
146                 </listitem>
147             </varlistentry>
148             <varlistentry>
149                 <term>wb</term>
150                 <listitem>
151                     <para>
152                         creates a new binary file for writing, or opens and truncates
153                         a file to zero length.
154                     </para>
155                 </listitem>
156             </varlistentry>
157             <varlistentry>
158                 <term>wt</term>
159                 <listitem>
160                     <para>
161                         creates a text binary file for writing, or opens and truncates 
162                         a file to zero length.
163                     </para>
164                 </listitem>
165             </varlistentry>
166             <varlistentry>
167                 <term>a or ab</term>
168                 <listitem>
169                     <para>
170                         appends (opens a file for writing at the end of the file, or
171                         creates a file for writing).
172                     </para>
173                 </listitem>
174             </varlistentry>
175             <varlistentry>
176                 <term>r+ or r+b</term>
177                 <listitem>
178                     <para>opens a file for update (reading and writing).</para>
179                 </listitem>
180             </varlistentry>
181             <varlistentry>
182                 <term>w+ or w+b</term>
183                 <listitem>
184                     <para>truncates to zero length or creates a file for update.</para>
185                 </listitem>
186             </varlistentry>
187             <varlistentry>
188                 <term>a+ or a+b</term>
189                 <listitem>
190                     <para>
191                         appends (opens a file for update, writing at the end of the
192                         file, or creates a file for writing).
193                     </para>
194                 </listitem>
195             </varlistentry>
196         </variablelist>
197         <para>
198             When you open a file for update, you can perform both input and output 
199             operations on the resulting stream. However, an output operation cannot 
200             be directly followed by an input operation without a file-positioning 
201             operation (<function>mseek</function> function). Also, an input 
202             operation cannot be directly followed by an output operation without an 
203             intervening file positioning operation, unless the input operation 
204             encounters the end of the file.
205         </para>
206         <para>
207             When you open a file for append (that is, when the 
208             <varname>mode</varname> parameter is <literal>a</literal> or 
209             <literal>a+</literal>), it is impossible to overwrite information 
210             already in the file. You can use the <function>mseek</function> 
211             function to reposition the file pointer to any position in the file, 
212             but when output is written to the file, the current file pointer is 
213             ignored. All output is written at the end of the file and the file 
214             pointer is repositioned to the end of the output.
215         </para>
216         <para>
217             To open files in a way compatible with Fortran-like functions use function <function>file</function>.
218         </para>
219     </refsection>
220     <refsection>
221     </refsection>
222     <refsection>
223         <programlisting role="example"><![CDATA[
224 // open a SCI+'/ACKNOWLEDGEMENTS' as text and read only
225 fd_r = mopen(SCI+'/ACKNOWLEDGEMENTS', 'rt')
226
227 // read five lines of fd_r
228 mgetl(fd_r, 5)
229
230 // another way to read file
231 // here read five words
232 mfscanf(5, fd_r, '%s')
233
234 // close file descriptor associated to SCI+'/ACKNOWLEDGEMENTS' as text and read only
235 mclose(fd_r);
236     ]]></programlisting>
237     </refsection>
238     <refsection>
239     </refsection>
240     <refsection>
241         <programlisting role="example"><![CDATA[
242 // open a file as text with write property
243 fd_w = mopen(TMPDIR+'/write.txt', 'wt');
244
245 // write a line in fd_w
246 mputl('This is a line of text', fd_w);
247 mclose(fd_w);
248
249 // read text
250 fd_r2 = mopen(TMPDIR+'/write.txt', 'rt');
251 mgetl(fd_r2)
252 mclose(fd_r2);
253     ]]></programlisting>
254     </refsection>
255     <refsection>
256     </refsection>
257     <refsection>
258         <title>Examples</title>
259         <programlisting role="example"><![CDATA[
260 // read/write a file as binary
261
262 // first we write file
263 fd_wb = mopen(TMPDIR+'/writeread.bin', 'wb')
264
265 // put values as binary
266 mput(2003, 'l', fd_wb);
267 mput(2008, 'i', fd_wb);
268 mput(2012, 's', fd_wb);
269 mput(98, 'c', fd_wb);
270
271 // close file descriptor associated to TMPDIR+'/writeread.bin'
272 mclose(fd_wb);
273
274 // we read file
275 fd_rb = mopen(TMPDIR+'/writeread.bin', 'rb')
276
277 mget(fd_rb, 'l')
278 mget(fd_rb, 'i')
279 mget(fd_rb, 's')
280 mget(fd_rb, 'c')
281
282 mclose(fd_rb) 
283     ]]></programlisting>
284     </refsection>
285     <refsection>
286     </refsection>
287     <refsection role="see also">
288         <title>See Also</title>
289         <simplelist type="inline">
290             <member>
291                 <link linkend="file">file</link>
292             </member>
293             <member>
294                 <link linkend="mclose">mclose</link>
295             </member>
296             <member>
297                 <link linkend="merror">merror</link>
298             </member>
299             <member>
300                 <link linkend="meof">meof</link>
301             </member>
302             <member>
303                 <link linkend="mfprintf">mfprintf</link>
304             </member>
305             <member>
306                 <link linkend="fprintfMat">fprintfMat</link>
307             </member>
308             <member>
309                 <link linkend="mfscanf">mfscanf</link>
310             </member>
311             <member>
312                 <link linkend="fscanfMat">fscanfMat</link>
313             </member>
314             <member>
315                 <link linkend="mget">mget</link>
316             </member>
317             <member>
318                 <link linkend="mgetl">mgetl</link>
319             </member>
320             <member>
321                 <link linkend="mgetstr">mgetstr</link>
322             </member>
323             <member>
324                 <link linkend="mprintf">mprintf</link>
325             </member>
326             <member>
327                 <link linkend="mput">mput</link>
328             </member>
329             <member>
330                 <link linkend="mputl">mputl</link>
331             </member>
332             <member>
333                 <link linkend="mputstr">mputstr</link>
334             </member>
335             <member>
336                 <link linkend="mseek">mseek</link>
337             </member>
338             <member>
339                 <link linkend="mtell">mtell</link>
340             </member>
341             <member>
342                 <link linkend="mdelete">mdelete</link>
343             </member>
344         </simplelist>
345     </refsection>
346 </refentry>