e4f960eb02ce9dc39b2836ccef0c89cbe68f64ca
[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" xmlns:scilab="http://www.scilab.org" 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 long int</para>
119                     </listitem>
120                 </varlistentry>
121                 <varlistentry>
122                     <term>i</term>
123                     <listitem>
124                         <para>int or long 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>