MATLAB Function Reference

Syntax

• ```[A,count] = fread(fid,size,`precision`)
[A,count] = fread(fid,size,`precision``,`skip)
```

Description

```[A,count] = fread(fid,size,precision) ``` reads binary data from the specified file and writes it into matrix `A`. Optional output argument `count` returns the number of elements successfully read. `fid` is an integer file identifier obtained from `fopen`.

`size` is an optional argument that determines how much data is read. If `size` is not specified, `fread` reads to the end of the file and the file pointer is at the end of the file (see `feof` for details). Valid options are:

 `n ` Reads `n` elements into a column vector. `inf ` Reads to the end of the file, resulting in a column vector containing the same number of elements as are in the file. `[m,n] ` Reads enough elements to fill an `m`-by-`n` matrix, filling in elements in column order, padding with zeros if the file is too small to fill the matrix. `n` can be specified as `inf`, but `m` cannot.

`precision` is a string that specifies the format of the data to be read. It commonly contains a datatype specifier such as `int` or `float`, followed by an integer giving the size in bits. Any of the strings in the following table, either the MATLAB version or their C or Fortran equivalent, may be used. If precision is not specified, the default is `'uchar'`.

 MATLAB C or Fortran Interpretation `'schar' ` `'signed char' ` Signed character; 8 bits `'uchar' ` `'unsigned char' ` Unsigned character; 8 bits `'int8'` `'integer*1'` Integer; 8 bits `'int16'` `'integer*2'` Integer; 16 bits `'int32'` `'integer*4'` Integer; 32 bits `'int64'` `'integer*8'` Integer; 64 bits `'uint8'` `'integer*1'` Unsigned integer; 8 bits `'uint16'` `'integer*2'` Unsigned integer; 16 bits `'uint32'` `'integer*4'` Unsigned integer; 32 bits `'uint64'` `'integer*8'` Unsigned integer; 64 bits `'float32'` `'real*4'` Floating-point; 32 bits `'float64'` `'real*8'` Floating-point; 64 bits `'double'` `'real*8'` Floating-point; 64 bits
.

The following platform dependent formats are also supported but they are not guaranteed to be the same size on all platforms. ``` MATLAB C or Fortran Interpretation 'char' 'char*1' Character; 8 bits 'short' 'short' Integer; 16 bits 'int' 'int' Integer; 32 bits 'long' 'long' Integer; 32 or 64 bits 'ushort' 'unsigned short' Unsigned integer; 16 bits 'uint' 'unsigned int' Unsigned integer; 32 bits 'ulong' 'unsigned long' Unsigned integer; 32 or 64 bits 'float' 'float' Floating-point; 32 bits ```

The following formats map to an input stream of bits rather than bytes.

 MATLAB C or Fortran Interpretation `'bitN'` ` -` Signed integer; `N` bits (`1` `N` `64`) `'ubitN'` ` -` Unsigned integer; `N` bits (`1` `N` `64`)

By default, numeric values are returned in class `double` arrays. To return numeric values stored in classes other than `double`, create your precision argument by first specifying your source format, and then following it with the characters "=>", and finally specifying your destination format. You are not required to use the exact name of a MATLAB class type for destination. (See `class` for details). `fread` translates the name to the most appropriate MATLAB class type. If the source and destination formats are the same, the following shorthand notation can be used.

• ```*source
```

which means

• ```source=>source
```

This table shows some example precision format strings.

 `'uint8=>uint8'` Read in unsigned 8-bit integers and save them in an unsigned 8-bit integer array. `'*uint8'` Shorthand version of the above. `'bit4=>int8'` Read in signed 4-bit integers packed in bytes and save them in a signed 8-bit array. Each 4-bit integer becomes an 8-bit integer. `'double=>real*4'` Read in doubles, convert and save as a 32-bit floating point array.

```[A,count] = fread(fid,size,precision,skip) ``` includes an optional `skip `argument that specifies the number of bytes to skip after each `precision` value is read. If `precision` specifies a bit format, like `'bitN'` or `'ubitN'`, the `skip` argument is interpreted as the number of bits to skip.

When `skip` is used, the `precision` string may contain a positive integer repetition factor of the form `'N*'` which prepends the source format specification, such as `'40*uchar'`.

 Note    Do not confuse the asterisk (*) used in the repetition factor with the asterisk used as precision format shorthand. The format string `'40*uchar'` is equivalent to `'40*uchar=>double'`, not `'40*uchar=>uchar'`.

When `skip` is specified, `fread` reads in, at most, a repetition factor number of values (default is 1), skips the amount of input specified by the `skip` argument, reads in another block of values, again skips input, and so on, until `size` number of values have been read. If a `skip` argument is not specified, the repetition factor is ignored. Use the repetition factor with the `skip` argument to extract data in noncontiguous fields from fixed length records.

If the input stream is bytes and `fread` reaches the end of file (see `feof`) in the middle of reading the number of bytes required for an element, the partial result is ignored. However, if the input stream is bits, then the partial result is returned as the last value. If an error occurs before reaching the end of file, only full elements read up to that point are used.

Examples

For example,

• ```type fread.m
```

displays the complete M-file containing this `fread` help entry. To simulate this command using `fread`, enter the following:

• ```fid = fopen('fread.m','r');
s = char(F')
```

In the example, the `fread` command assumes the default size, `inf`, and the default precision, `'uchar'`. `fread` reads the entire file, converting the unsigned characters into a column vector of class `'double'` (double precision floating point). To display the result as readable text, the `'double'` column vector is transposed to a row vector and converted to class `'char'` using the `char` function.

As another example,

• ```s = fread(fid,120,'40*uchar=>uchar',8);
```

reads in 120 characters in blocks of 40, each separated by 8 characters. Note that the class type of `s` is `'uint8'` since it is the appropriate class corresponding to the destination format, `'uchar'`. Also, since 40 evenly divides 120, the last block read is a full block which means that a final skip will be done before the command is finished. If the last block read is not a full block then `fread` will not finish with a skip.

See `fopen` for information about reading Big and Little Endian files.

`fclose`, `ferror`, `fopen`, `fprintf`, `fread`, `fscanf`, `fseek`, `ftell`, `fwrite`, `feof`