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