Revision of help pages for module "fileio" (en_US and ru_RU).
[scilab.git] / scilab / modules / fileio / help / en_US / mget.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  * ...
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:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:id="mget" xml:lang="en">
15     <refnamediv>
16         <refname>mget</refname>
17         <refpurpose>reads byte or word in a given binary format and converts to
18             a double type
19         </refpurpose>
20     </refnamediv>
21     <refnamediv xml:id="mgeti">
22         <refname>mgeti</refname>
23         <refpurpose>
24             reads byte or word in a given binary format and returns an int type
25         </refpurpose>
26     </refnamediv>
27     <refsynopsisdiv>
28         <title>Calling Sequence</title>
29         <synopsis>
30             x = mget([n, type, fd])
31             x = mgeti([n, type, fd])
32         </synopsis>
33     </refsynopsisdiv>
34     <refsection>
35         <title>Arguments</title>
36         <variablelist>
37             <varlistentry>
38                 <term>n</term>
39                 <listitem>
40                     <para>a positive scalar: the number of items to be read.</para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>fd</term>
45                 <listitem>
46                     <para>
47                         a scalar: a file descriptor returned by the function <function>mopen</function>. <literal>-1</literal> 
48                         stands for last opened file. Default value is 
49                         <literal>-1</literal>.
50                     </para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>type</term>
55                 <listitem>
56                     <para>
57                         a string: the binary format used to write all the entries of 
58                         <varname>x</varname>.
59                     </para>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>x</term>
64                 <listitem>
65                     <para>a vector of floating point or integer numbers.</para>
66                 </listitem>
67             </varlistentry>
68         </variablelist>
69     </refsection>
70     <refsection>
71         <title>Description</title>
72         <para>
73             The <function>mget</function> function reads data in the input
74             specified by the stream parameter <varname>fd</varname> and returns a
75             vector of floating point data. 
76         </para>
77         
78         <para>
79             The <function>mgeti</function> function reads data in the input 
80             specified by the stream parameter <varname>fd</varname> and returns a 
81             vector of integer data.
82         </para>
83         <para>
84             Data is read at the position at which the file pointer is currently
85             pointing and advances the indicator appropriately.
86         </para>
87         <para>
88             The <varname>type</varname> parameter is a conversion specifier
89             which may be set to any of the following flag characters (with default 
90             value <literal>"l"</literal>):
91         </para>
92         <para>
93             <note>
94                 On Windows, default behavior is to skip byte 13 (<literal>0x0D</literal>). 
95                 <function>mopen</function> should be called with the 
96                 <literal>'b'</literal> option, e.g. 
97                 <code>fd1 = mopen(file1,'rb')</code>, so that all bytes will be read 
98                 without exception.
99             </note>
100         </para>
101         <para>Data type:</para>
102         <variablelist>
103             <varlistentry>
104                 <term>d</term>
105                 <listitem>
106                     <para>double</para>
107                 </listitem>
108             </varlistentry>
109             <varlistentry>
110                 <term>f</term>
111                 <listitem>
112                     <para>float</para>
113                 </listitem>
114             </varlistentry>
115             <varlistentry>
116                 <term>l</term>
117                 <listitem>
118                     <para>long</para>
119                 </listitem>
120             </varlistentry>
121             <varlistentry>
122                 <term>i</term>
123                 <listitem>
124                     <para>int</para>
125                 </listitem>
126             </varlistentry>
127             <varlistentry>
128                 <term>s</term>
129                 <listitem>
130                     <para>short</para>
131                 </listitem>
132             </varlistentry>
133             <varlistentry>
134                 <term>c</term>
135                 <listitem>
136                     <para>character</para>
137                 </listitem>
138             </varlistentry>
139         </variablelist>
140         <para>Optional flag:</para>
141         <variablelist>
142             <varlistentry>
143                 <term>u..</term>
144                 <listitem>
145                     <para>unsigned (in combination with one of the above types)</para>
146                 </listitem>
147             </varlistentry>
148             <varlistentry>
149                 <term>..l</term>
150                 <listitem>
151                     <para>
152                         little endian (in combination with one of the above types)
153                     </para>
154                 </listitem>
155             </varlistentry>
156             <varlistentry>
157                 <term>..b</term>
158                 <listitem>
159                     <para>
160                         big endian (in combination with one of the above types)
161                     </para>
162                 </listitem>
163             </varlistentry>
164         </variablelist>
165         <para>
166             Bytes read is automatically swapped if necessary (by checking 
167             <literal>little=endian</literal> status).
168         </para>
169         <para>
170             This default swapping behavior can be suprressed by adding a flag in      
171             the <function>mopen</function> function.
172         </para>
173         <para>
174             Formats <literal>"l"</literal>, <literal>"d"</literal> and 
175             <literal>"f"</literal> are only valid with the 
176             <function>mget</function> function.
177         </para>
178     </refsection>
179     <refsection>
180         <title>Examples</title>
181         <programlisting role="example"><![CDATA[ 
182 file1 = fullfile(TMPDIR,'test1.bin');
183 file2 = fullfile(TMPDIR,'test2.bin');
184 fd1=mopen(file1,'wb');
185 fd2=mopen(file2,'wb');
186 mput(1996,'ull',fd1);
187 mput(1996,'ull',fd2);
188 mclose(fd1);
189 mclose(fd2);
190
191 fd1=mopen(file1,'rb');
192 if 1996<>mget(1,'ull',fd1)
193   write(%io(2),'Bug');
194 end
195
196 fd2=mopen(file2,'rb');
197 if 1996<>mget(1,'ull',fd2)
198   write(%io(2),'Bug');
199 end
200
201 mclose(fd1);
202 mclose(fd2);
203  ]]></programlisting>
204     </refsection>
205     <refsection role="see also">
206         <title>See Also</title>
207         <simplelist type="inline">
208             <member>
209                 <link linkend="mclose">mclose</link>
210             </member>
211             <member>
212                 <link linkend="meof">meof</link>
213             </member>
214             <member>
215                 <link linkend="mfprintf">mfprintf</link>
216             </member>
217             <member>
218                 <link linkend="fprintfMat">fprintfMat</link>
219             </member>
220             <member>
221                 <link linkend="mfscanf">mfscanf</link>
222             </member>
223             <member>
224                 <link linkend="fscanfMat">fscanfMat</link>
225             </member>
226             <member>
227                 <link linkend="mgetl">mgetl</link>
228             </member>
229             <member>
230                 <link linkend="mgetstr">mgetstr</link>
231             </member>
232             <member>
233                 <link linkend="mopen">mopen</link>
234             </member>
235             <member>
236                 <link linkend="mprintf">mprintf</link>
237             </member>
238             <member>
239                 <link linkend="mput">mput</link>
240             </member>
241             <member>
242                 <link linkend="mputl">mputl</link>
243             </member>
244             <member>
245                 <link linkend="mputstr">mputstr</link>
246             </member>
247             <member>
248                 <link linkend="mseek">mseek</link>
249             </member>
250             <member>
251                 <link linkend="mtell">mtell</link>
252             </member>
253             <member>
254                 <link linkend="mdelete">mdelete</link>
255             </member>
256         </simplelist>
257     </refsection>
258 </refentry>