File: Binary-I_002fO.html

package info (click to toggle)
octave 3.8.2-4
links: PTS, VCS
area: main
in suites: jessie, jessie-kfreebsd
size: 84,396 kB
ctags: 45,547
sloc: cpp: 293,356; ansic: 42,041; fortran: 23,669; sh: 13,629; objc: 7,890; yacc: 7,093; lex: 3,442; java: 2,125; makefile: 1,589; perl: 1,009; awk: 974; xml: 34
file content (282 lines) | stat: -rw-r--r-- 11,252 bytes
parent folder | download | duplicates (3)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Octave: Binary I/O</title>

<meta name="description" content="GNU Octave: Binary I/O">
<meta name="keywords" content="GNU Octave: Binary I/O">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="C_002dStyle-I_002fO-Functions.html#C_002dStyle-I_002fO-Functions" rel="up" title="C-Style I/O Functions">
<link href="Temporary-Files.html#Temporary-Files" rel="next" title="Temporary Files">
<link href="String-Input-Conversions.html#String-Input-Conversions" rel="prev" title="String Input Conversions">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Binary-I_002fO"></a>
<div class="header">
<p>
Next: <a href="Temporary-Files.html#Temporary-Files" accesskey="n" rel="next">Temporary Files</a>, Previous: <a href="String-Input-Conversions.html#String-Input-Conversions" accesskey="p" rel="prev">String Input Conversions</a>, Up: <a href="C_002dStyle-I_002fO-Functions.html#C_002dStyle-I_002fO-Functions" accesskey="u" rel="up">C-Style I/O Functions</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Binary-I_002fO-1"></a>
<h4 class="subsection">14.2.16 Binary I/O</h4>

<p>Octave can read and write binary data using the functions <code>fread</code>
and <code>fwrite</code>, which are patterned after the standard C functions
with the same names.  They are able to automatically swap the byte order
of integer data and convert among the supported floating point formats
as the data are read.
</p>
<a name="XREFfread"></a><dl>
<dt><a name="index-fread"></a>Built-in Function: <em>[<var>val</var>, <var>count</var>] =</em> <strong>fread</strong> <em>(<var>fid</var>, <var>size</var>, <var>precision</var>, <var>skip</var>, <var>arch</var>)</em></dt>
<dd><p>Read binary data of type <var>precision</var> from the specified file ID
<var>fid</var>.
</p>
<p>The optional argument <var>size</var> specifies the amount of data to read
and may be one of
</p>
<dl compact="compact">
<dt><code>Inf</code></dt>
<dd><p>Read as much as possible, returning a column vector.
</p>
</dd>
<dt><code><var>nr</var></code></dt>
<dd><p>Read up to <var>nr</var> elements, returning a column vector.
</p>
</dd>
<dt><code>[<var>nr</var>, Inf]</code></dt>
<dd><p>Read as much as possible, returning a matrix with <var>nr</var> rows.  If the
number of elements read is not an exact multiple of <var>nr</var>, the last
column is padded with zeros.
</p>
</dd>
<dt><code>[<var>nr</var>, <var>nc</var>]</code></dt>
<dd><p>Read up to <code><var>nr</var> * <var>nc</var></code> elements, returning a matrix with
<var>nr</var> rows.  If the number of elements read is not an exact multiple
of <var>nr</var>, the last column is padded with zeros.
</p></dd>
</dl>

<p>If <var>size</var> is omitted, a value of <code>Inf</code> is assumed.
</p>
<p>The optional argument <var>precision</var> is a string specifying the type of
data to read and may be one of
</p>
<dl compact="compact">
<dt><code>&quot;schar&quot;</code></dt>
<dt><code>&quot;signed char&quot;</code></dt>
<dd><p>Signed character.
</p>
</dd>
<dt><code>&quot;uchar&quot;</code></dt>
<dt><code>&quot;unsigned char&quot;</code></dt>
<dd><p>Unsigned character.
</p>
</dd>
<dt><code>&quot;int8&quot;</code></dt>
<dt><code>&quot;integer*1&quot;</code></dt>
<dd>
<p>8-bit signed integer.
</p>
</dd>
<dt><code>&quot;int16&quot;</code></dt>
<dt><code>&quot;integer*2&quot;</code></dt>
<dd><p>16-bit signed integer.
</p>
</dd>
<dt><code>&quot;int32&quot;</code></dt>
<dt><code>&quot;integer*4&quot;</code></dt>
<dd><p>32-bit signed integer.
</p>
</dd>
<dt><code>&quot;int64&quot;</code></dt>
<dt><code>&quot;integer*8&quot;</code></dt>
<dd><p>64-bit signed integer.
</p>
</dd>
<dt><code>&quot;uint8&quot;</code></dt>
<dd><p>8-bit unsigned integer.
</p>
</dd>
<dt><code>&quot;uint16&quot;</code></dt>
<dd><p>16-bit unsigned integer.
</p>
</dd>
<dt><code>&quot;uint32&quot;</code></dt>
<dd><p>32-bit unsigned integer.
</p>
</dd>
<dt><code>&quot;uint64&quot;</code></dt>
<dd><p>64-bit unsigned integer.
</p>
</dd>
<dt><code>&quot;single&quot;</code></dt>
<dt><code>&quot;float32&quot;</code></dt>
<dt><code>&quot;real*4&quot;</code></dt>
<dd><p>32-bit floating point number.
</p>
</dd>
<dt><code>&quot;double&quot;</code></dt>
<dt><code>&quot;float64&quot;</code></dt>
<dt><code>&quot;real*8&quot;</code></dt>
<dd><p>64-bit floating point number.
</p>
</dd>
<dt><code>&quot;char&quot;</code></dt>
<dt><code>&quot;char*1&quot;</code></dt>
<dd><p>Single character.
</p>
</dd>
<dt><code>&quot;short&quot;</code></dt>
<dd><p>Short integer (size is platform dependent).
</p>
</dd>
<dt><code>&quot;int&quot;</code></dt>
<dd><p>Integer (size is platform dependent).
</p>
</dd>
<dt><code>&quot;long&quot;</code></dt>
<dd><p>Long integer (size is platform dependent).
</p>
</dd>
<dt><code>&quot;ushort&quot;</code></dt>
<dt><code>&quot;unsigned short&quot;</code></dt>
<dd><p>Unsigned short integer (size is platform dependent).
</p>
</dd>
<dt><code>&quot;uint&quot;</code></dt>
<dt><code>&quot;unsigned int&quot;</code></dt>
<dd><p>Unsigned integer (size is platform dependent).
</p>
</dd>
<dt><code>&quot;ulong&quot;</code></dt>
<dt><code>&quot;unsigned long&quot;</code></dt>
<dd><p>Unsigned long integer (size is platform dependent).
</p>
</dd>
<dt><code>&quot;float&quot;</code></dt>
<dd><p>Single precision floating point number (size is platform dependent).
</p></dd>
</dl>

<p>The default precision is <code>&quot;uchar&quot;</code>.
</p>
<p>The <var>precision</var> argument may also specify an optional repeat
count.  For example, &lsquo;<samp>32*single</samp>&rsquo; causes <code>fread</code> to read
a block of 32 single precision floating point numbers.  Reading in
blocks is useful in combination with the <var>skip</var> argument.
</p>
<p>The <var>precision</var> argument may also specify a type conversion.
For example, &lsquo;<samp>int16=&gt;int32</samp>&rsquo; causes <code>fread</code> to read 16-bit
integer values and return an array of 32-bit integer values.  By
default, <code>fread</code> returns a double precision array.  The special
form &lsquo;<samp>*TYPE</samp>&rsquo; is shorthand for &lsquo;<samp>TYPE=&gt;TYPE</samp>&rsquo;.
</p>
<p>The conversion and repeat counts may be combined.  For example, the
specification &lsquo;<samp>32*single=&gt;single</samp>&rsquo; causes <code>fread</code> to read
blocks of single precision floating point values and return an array
of single precision values instead of the default array of double
precision values.
</p>
<p>The optional argument <var>skip</var> specifies the number of bytes to skip
after each element (or block of elements) is read.  If it is not
specified, a value of 0 is assumed.  If the final block read is not
complete, the final skip is omitted.  For example,
</p>
<div class="example">
<pre class="example">fread (f, 10, &quot;3*single=&gt;single&quot;, 8)
</pre></div>

<p>will omit the final 8-byte skip because the last read will not be
a complete block of 3 values.
</p>
<p>The optional argument <var>arch</var> is a string specifying the data format
for the file.  Valid values are
</p>
<dl compact="compact">
<dt><code><code>&quot;native&quot;</code></code></dt>
<dd><p>The format of the current machine.
</p>
</dd>
<dt><code>&quot;ieee-be&quot;</code></dt>
<dd><p>IEEE big endian.
</p>
</dd>
<dt><code>&quot;ieee-le&quot;</code></dt>
<dd><p>IEEE little endian.
</p></dd>
</dl>

<p>The data read from the file is returned in <var>val</var>, and the number of
values read is returned in <code>count</code>
</p>
<p><strong>See also:</strong> <a href="#XREFfwrite">fwrite</a>, <a href="Line_002dOriented-Input.html#XREFfgets">fgets</a>, <a href="Line_002dOriented-Input.html#XREFfgetl">fgetl</a>, <a href="Formatted-Input.html#XREFfscanf">fscanf</a>, <a href="Opening-and-Closing-Files.html#XREFfopen">fopen</a>.
</p></dd></dl>


<a name="XREFfwrite"></a><dl>
<dt><a name="index-fwrite"></a>Built-in Function: <em><var>count</var> =</em> <strong>fwrite</strong> <em>(<var>fid</var>, <var>data</var>, <var>precision</var>, <var>skip</var>, <var>arch</var>)</em></dt>
<dd><p>Write data in binary form of type <var>precision</var> to the specified file
ID <var>fid</var>, returning the number of values successfully written to the
file.
</p>
<p>The argument <var>data</var> is a matrix of values that are to be written to
the file.  The values are extracted in column-major order.
</p>
<p>The remaining arguments <var>precision</var>, <var>skip</var>, and <var>arch</var> are
optional, and are interpreted as described for <code>fread</code>.
</p>
<p>The behavior of <code>fwrite</code> is undefined if the values in <var>data</var>
are too large to fit in the specified precision.
</p>
<p><strong>See also:</strong> <a href="#XREFfread">fread</a>, <a href="Simple-Output.html#XREFfputs">fputs</a>, <a href="Formatted-Output.html#XREFfprintf">fprintf</a>, <a href="Opening-and-Closing-Files.html#XREFfopen">fopen</a>.
</p></dd></dl>


<hr>
<div class="header">
<p>
Next: <a href="Temporary-Files.html#Temporary-Files" accesskey="n" rel="next">Temporary Files</a>, Previous: <a href="String-Input-Conversions.html#String-Input-Conversions" accesskey="p" rel="prev">String Input Conversions</a>, Up: <a href="C_002dStyle-I_002fO-Functions.html#C_002dStyle-I_002fO-Functions" accesskey="u" rel="up">C-Style I/O Functions</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>