<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ --> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <title>Binary I/O (GNU Octave (version 5.1.0))</title> <meta name="description" content="Binary I/O (GNU Octave (version 5.1.0))"> <meta name="keywords" content="Binary I/O (GNU Octave (version 5.1.0))"> <meta name="resource-type" content="document"> <meta name="distribution" content="global"> <meta name="Generator" content="makeinfo"> <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.indentedblock {margin-right: 0em} blockquote.smallindentedblock {margin-right: 0em; font-size: smaller} blockquote.smallquotation {font-size: smaller} div.display {margin-left: 3.2em} div.example {margin-left: 3.2em} div.lisp {margin-left: 3.2em} div.smalldisplay {margin-left: 3.2em} div.smallexample {margin-left: 3.2em} 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.nolinebreak {white-space: nowrap} span.roman {font-family: initial; font-weight: normal} span.sansserif {font-family: sans-serif; font-weight: normal} ul.no-bullet {list-style: none} --> </style> <link rel="stylesheet" type="text/css" href="octave.css"> </head> <body lang="en"> <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> [<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><em><var>val</var> =</em> <strong>fread</strong> <em>(<var>fid</var>)</em></dt> <dt><a name="index-fread-1"></a><em><var>val</var> =</em> <strong>fread</strong> <em>(<var>fid</var>, <var>size</var>)</em></dt> <dt><a name="index-fread-2"></a><em><var>val</var> =</em> <strong>fread</strong> <em>(<var>fid</var>, <var>size</var>, <var>precision</var>)</em></dt> <dt><a name="index-fread-3"></a><em><var>val</var> =</em> <strong>fread</strong> <em>(<var>fid</var>, <var>size</var>, <var>precision</var>, <var>skip</var>)</em></dt> <dt><a name="index-fread-4"></a><em><var>val</var> =</em> <strong>fread</strong> <em>(<var>fid</var>, <var>size</var>, <var>precision</var>, <var>skip</var>, <var>arch</var>)</em></dt> <dt><a name="index-fread-5"></a><em>[<var>val</var>, <var>count</var>] =</em> <strong>fread</strong> <em>(…)</em></dt> <dd><p>Read binary data from the file specified by the file descriptor <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>"uint8"</code> (default)</dt> <dd><p>8-bit unsigned integer. </p> </dd> <dt><code>"int8"</code></dt> <dt><code>"integer*1"</code></dt> <dd><p>8-bit signed integer. </p> </dd> <dt><code>"uint16"</code></dt> <dt><code>"ushort"</code></dt> <dt><code>"unsigned short"</code></dt> <dd><p>16-bit unsigned integer. </p> </dd> <dt><code>"int16"</code></dt> <dt><code>"integer*2"</code></dt> <dt><code>"short"</code></dt> <dd><p>16-bit signed integer. </p> </dd> <dt><code>"uint"</code></dt> <dt><code>"uint32"</code></dt> <dt><code>"unsigned int"</code></dt> <dt><code>"ulong"</code></dt> <dt><code>"unsigned long"</code></dt> <dd><p>32-bit unsigned integer. </p> </dd> <dt><code>"int"</code></dt> <dt><code>"int32"</code></dt> <dt><code>"integer*4"</code></dt> <dt><code>"long"</code></dt> <dd><p>32-bit signed integer. </p> </dd> <dt><code>"uint64"</code></dt> <dd><p>64-bit unsigned integer. </p> </dd> <dt><code>"int64"</code></dt> <dt><code>"integer*8"</code></dt> <dd><p>64-bit signed integer. </p> </dd> <dt><code>"single"</code></dt> <dt><code>"float"</code></dt> <dt><code>"float32"</code></dt> <dt><code>"real*4"</code></dt> <dd><p>32-bit floating point number. </p> </dd> <dt><code>"double"</code></dt> <dt><code>"float64"</code></dt> <dt><code>"real*8"</code></dt> <dd><p>64-bit floating point number. </p> </dd> <dt><code>"char"</code></dt> <dt><code>"char*1"</code></dt> <dd><p>8-bit single character. </p> </dd> <dt><code>"uchar"</code></dt> <dt><code>"unsigned char"</code></dt> <dd><p>8-bit unsigned character. </p> </dd> <dt><code>"schar"</code></dt> <dt><code>"signed char"</code></dt> <dd><p>8-bit signed character. </p> </dd> </dl> <p>The default precision is <code>"uint8"</code>. </p> <p>The <var>precision</var> argument may also specify an optional repeat count. For example, ‘<samp>32*single</samp>’ 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, ‘<samp>int16=>int32</samp>’ 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 ‘<samp>*TYPE</samp>’ is shorthand for ‘<samp>TYPE=>TYPE</samp>’. </p> <p>The conversion and repeat counts may be combined. For example, the specification ‘<samp>32*single=>single</samp>’ 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, "3*single=>single", 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>"native"</code> or <code>"n"</code></dt> <dd><p>The format of the current machine. </p> </dd> <dt><code>"ieee-be"</code> or <code>"b"</code></dt> <dd><p>IEEE big endian. </p> </dd> <dt><code>"ieee-le"</code> or <code>"l"</code></dt> <dd><p>IEEE little endian. </p></dd> </dl> <p>If no <var>arch</var> is given the value used in the call to <code>fopen</code> which created the file descriptor is used. Otherwise, the value specified with <code>fread</code> overrides that of <code>fopen</code> and determines the data format. </p> <p>The output argument <var>val</var> contains the data read from the file. </p> <p>The optional return value <var>count</var> contains the number of elements read. </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><em></em> <strong>fwrite</strong> <em>(<var>fid</var>, <var>data</var>)</em></dt> <dt><a name="index-fwrite-1"></a><em></em> <strong>fwrite</strong> <em>(<var>fid</var>, <var>data</var>, <var>precision</var>)</em></dt> <dt><a name="index-fwrite-2"></a><em></em> <strong>fwrite</strong> <em>(<var>fid</var>, <var>data</var>, <var>precision</var>, <var>skip</var>)</em></dt> <dt><a name="index-fwrite-3"></a><em></em> <strong>fwrite</strong> <em>(<var>fid</var>, <var>data</var>, <var>precision</var>, <var>skip</var>, <var>arch</var>)</em></dt> <dt><a name="index-fwrite-4"></a><em><var>count</var> =</em> <strong>fwrite</strong> <em>(…)</em></dt> <dd><p>Write data in binary form to the file specified by the file descriptor <var>fid</var>, returning the number of values <var>count</var> 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> [<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>