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         <title>Examples</title>
 224         <programlisting role="example"><![CDATA[
 225 // open a SCI+'/ACKNOWLEDGEMENTS' as text and read only
 226 fd_r = mopen(SCI+'/ACKNOWLEDGEMENTS', 'rt')
 227
 228 // read five lines of fd_r
 229 mgetl(fd_r, 5)
 230
 231 // another way to read file
 232 // here read five words
 233 mfscanf(5, fd_r, '%s')
 234
 235 // close file descriptor associated to SCI+'/ACKNOWLEDGEMENTS' as text and read only
 236 mclose(fd_r);
 237     ]]></programlisting>
 238     </refsection>
 239     <refsection>
 240     </refsection>
 241     <refsection>
 242         <programlisting role="example"><![CDATA[
 243 // open a file as text with write property
 244 fd_w = mopen(TMPDIR+'/write.txt', 'wt');
 245
 246 // write a line in fd_w
 247 mputl('This is a line of text', fd_w);
 248 mclose(fd_w);
 249
 250 // read text
 251 fd_r2 = mopen(TMPDIR+'/write.txt', 'rt');
 252 mgetl(fd_r2)
 253 mclose(fd_r2);
 254     ]]></programlisting>
 255     </refsection>
 256     <refsection>
 257     </refsection>
 258     <refsection>
 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>