License Header change: Removed the LICENSE_END before beta
[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>Calling Sequence</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         
81         <para>
82             The <function>mgeti</function> function reads data in the input
83             specified by the stream parameter <varname>fd</varname> and returns a
84             vector of integer data.
85         </para>
86         <para>
87             Data is read at the position at which the file pointer is currently
88             pointing and advances the indicator appropriately.
89         </para>
90         <para>
91             The <varname>type</varname> parameter is a conversion specifier
92             which may be set to any of the following flag characters (with default
93             value <literal>"l"</literal>):
94         </para>
95         <para>
96             <note>
97                 On Windows, default behavior is to skip byte 13 (<literal>0x0D</literal>).
98                 <function>mopen</function> should be called with the
99                 <literal>'b'</literal> option, e.g.
100                 <code>fd1 = mopen(file1,'rb')</code>, so that all bytes will be read
101                 without exception.
102             </note>
103         </para>
104         <para>Data type:</para>
105         <variablelist>
106             <varlistentry>
107                 <term>d</term>
108                 <listitem>
109                     <para>double</para>
110                 </listitem>
111             </varlistentry>
112             <varlistentry>
113                 <term>f</term>
114                 <listitem>
115                     <para>float</para>
116                 </listitem>
117             </varlistentry>
118             <varlistentry>
119                 <term>l</term>
120                 <listitem>
121                     <para>long long int</para>
122                 </listitem>
123             </varlistentry>
124             <varlistentry>
125                 <term>i</term>
126                 <listitem>
127                     <para>int or long int</para>
128                 </listitem>
129             </varlistentry>
130             <varlistentry>
131                 <term>s</term>
132                 <listitem>
133                     <para>short</para>
134                 </listitem>
135             </varlistentry>
136             <varlistentry>
137                 <term>c</term>
138                 <listitem>
139                     <para>character</para>
140                 </listitem>
141             </varlistentry>
142         </variablelist>
143         <para>Optional flag:</para>
144         <variablelist>
145             <varlistentry>
146                 <term>u..</term>
147                 <listitem>
148                     <para>unsigned (in combination with one of the above types)</para>
149                 </listitem>
150             </varlistentry>
151             <varlistentry>
152                 <term>..l</term>
153                 <listitem>
154                     <para>
155                         little endian (in combination with one of the above types)
156                     </para>
157                 </listitem>
158             </varlistentry>
159             <varlistentry>
160                 <term>..b</term>
161                 <listitem>
162                     <para>
163                         big endian (in combination with one of the above types)
164                     </para>
165                 </listitem>
166             </varlistentry>
167         </variablelist>
168         <para>
169             Bytes read is automatically swapped if necessary (by checking
170             <literal>little=endian</literal> status).
171         </para>
172         <para>
173             This default swapping behavior can be supressed by adding a flag in
174             the <function>mopen</function> function.
175         </para>
176         <para>
177             Formats <literal>"l"</literal>, <literal>"d"</literal> and
178             <literal>"f"</literal> are only valid with the
179             <function>mget</function> function.
180         </para>
181     </refsection>
182     <refsection>
183         <title>Examples</title>
184         <programlisting role="example"><![CDATA[
185 file1 = fullfile(TMPDIR,'test1.bin');
186 file2 = fullfile(TMPDIR,'test2.bin');
187 fd1=mopen(file1,'wb');
188 fd2=mopen(file2,'wb');
189 mput(1996,'ull',fd1);
190 mput(1996,'ull',fd2);
191 mclose(fd1);
192 mclose(fd2);
193
194 fd1=mopen(file1,'rb');
195 if 1996<>mget(1,'ull',fd1)
196   write(%io(2),'Bug');
197 end
198
199 fd2=mopen(file2,'rb');
200 if 1996<>mget(1,'ull',fd2)
201   write(%io(2),'Bug');
202 end
203
204 mclose(fd1);
205 mclose(fd2);
206  ]]></programlisting>
207     </refsection>
208     <refsection role="see also">
209         <title>See Also</title>
210         <simplelist type="inline">
211             <member>
212                 <link linkend="mclose">mclose</link>
213             </member>
214             <member>
215                 <link linkend="meof">meof</link>
216             </member>
217             <member>
218                 <link linkend="mfprintf">mfprintf</link>
219             </member>
220             <member>
221                 <link linkend="fprintfMat">fprintfMat</link>
222             </member>
223             <member>
224                 <link linkend="mfscanf">mfscanf</link>
225             </member>
226             <member>
227                 <link linkend="fscanfMat">fscanfMat</link>
228             </member>
229             <member>
230                 <link linkend="mgetl">mgetl</link>
231             </member>
232             <member>
233                 <link linkend="mgetstr">mgetstr</link>
234             </member>
235             <member>
236                 <link linkend="mopen">mopen</link>
237             </member>
238             <member>
239                 <link linkend="mprintf">mprintf</link>
240             </member>
241             <member>
242                 <link linkend="mput">mput</link>
243             </member>
244             <member>
245                 <link linkend="mputl">mputl</link>
246             </member>
247             <member>
248                 <link linkend="mputstr">mputstr</link>
249             </member>
250             <member>
251                 <link linkend="mseek">mseek</link>
252             </member>
253             <member>
254                 <link linkend="mtell">mtell</link>
255             </member>
256             <member>
257                 <link linkend="mdelete">mdelete</link>
258             </member>
259         </simplelist>
260     </refsection>
261 </refentry>