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