MATLAB Function Reference    
fread

Read binary data from file

Syntax

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 thatn double, create your precision argument by first specifying your source format, then following it with the characters "=>", and finally specifying your destination format. You are not reuiqred 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 may be used:

which means:

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. With 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'.

When skip is specified, fread reads in at most a repetition factor number of values (default is 1), does a skip of input specified by the skip argument, reads in another block of values, does a skip of input, and so on, until size number of values have beenread. If precision is a bit format like 'bitN' or 'ubitN', skip is specified in bits. Use the repetition factor with the skip argument to extract data in noncontiguous fields from fixed length records.

If fread reaches the end of the file and the current input stream does not contain enough bits to write out a complete matrix element of the specified precision, fread pads the last byte or element with zero bits until the full value is obtained. If an error occurs, reading is done up to the last full value.

Examples

For example,

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

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,

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 informationabout reading Big and Little Endian files.

See Also

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


 frameedit fread (serial)