MATLAB Function Reference

fread

Read binary data from file

Syntax

• A = fread(fid)
  A = fread(fid, count)
  A = fread(fid, count, precision)
  A = fread(fid, count, precision, skip)
  A = fread(fid, count, precision, skip, machineformat)
  [A, count] = fread(...)
  

Description

A = fread(fid) reads data in binary format from the file specified by fid into matrix A. Open the file using fopen before calling fread. The fid argument is the integer file identifier obtained from the fopen operation. MATLAB reads the file from beginning to end, and then positions the file pointer at the end of the file (see feof for details).

Note    fread is intended primarily for binary data. When reading text files, use the fgetl function.

A = fread(fid, count) reads the number of elements specified by count. At the end of the fread, MATLAB sets the file pointer to the next byte to be read. A subsequent fread will begin at the location of the file pointer. See Specifying the Number of Elements, below.

Note    In the following syntaxes, the count and skip arguments are optional. For example, fread(fid, precision) is a valid syntax.

A = fread(fid, count, precision) reads the file according to the data format specified by the string precision. This argument commonly contains a data type specifier such as int or float, followed by an integer giving the size in bits. See Specifying Precision and Specifying Output Precision, below.

A = fread(fid, count, 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. See Specifying a Skip Value, below.

A = fread(fid, count, precision, skip, machineformat) treats the data read as having a format given by machineformat. You can obtain the machineformat argument from the output of the fopen function. See Specifying Machine Format, below.

[A, count] = fread(...) returns the data read from the file in A, and the number of elements successfully read in count.

Specifying the Number of Elements

Valid options for count 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. If using inf results in an "out of memory" error, specify a numeric count value.
[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.

Specifying Precision

Any of the strings in the following table, either the MATLAB version or their C or Fortran equivalent, can be used for precision. If precision is not specified, MATLAB uses the default, which 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)

Specifying Output Precision

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, 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
  

For example, '*uint16' is the same as 'uint16=>uint16'.

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.

Specifying a Skip Value

When skip is used, the precision string can contain a positive integer repetition factor of the form 'N*', which prefixes 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 count 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.

Specifying Machine Format

machineformat is one of the following strings:

'cray' or 'c'	Cray floating point with big-endian byte ordering
'ieee-be' or 'b'	IEEE floating point with big-endian byte ordering
'ieee-le' or 'l'	IEEE floating point with little-endian byte ordering
'ieee-be.l64' or 's'	IEEE floating point with big-endian byte ordering and 64-bit long data type
'ieee-le.l64' or 'a'	IEEE floating point with little-endian byte ordering and 64-bit long data type
'native' or 'n'	Numeric format of the machine on which MATLAB is running (the default)
'vaxd' or 'd'	VAX D floating point and VAX ordering
'vaxg' or 'g'	VAX G floating point and VAX ordering

Remarks

When reading character strings from files, pass the output of fread to the MATLAB native2unicode function to ensure that characters display correctly:

• str = native2unicode(fread(fid));
  

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

Example 1

The file alphabet.txt contains the 26 letters of the English alphabet, all capitalized. Open the file for read access with fopen, and read the first five elements into output c. Because a precision has not been specified, MATLAB uses the default precision of uchar, and the output is numeric:

• fid = fopen('alphabet.txt', 'r');
  c = fread(fid, 5)'
  c =
      65    66    67    68    69
  fclose(fid);
  

This time, specify that you want each element read as an unsigned 8-bit integer and output as a character. (Using a precision of 'char=>char' or '*char' will produce the same result):

• fid = fopen('alphabet.txt', 'r');
  c = fread(fid, 5, 'uint8=>char')'
  c =
      ABCDE
  fclose(fid);
  

When you leave out the optional count argument, MATLAB reads the file to the end, A through Z:

• fid = fopen('alphabet.txt', 'r');
  c = fread(fid, '*char')'
  c =
      ABCDEFGHIJKLMNOPQRSTUVWXYZ
  fclose(fid);
  

The fopen function positions the file pointer at the start of the file. So the first fread in this example reads the first five elements in the file, and then repositions the file pointer at the beginning of the next element. For this reason, the next fread picks up where the previous fread left off, at the character F.

• fid = fopen('alphabet.txt', 'r');
  c1 = fread(fid, 5, '*char');
  c2 = fread(fid, 8, '*char');
  c3 = fread(fid, 5, '*char');
  fclose(fid);
  
  sprintf('%c', c1, ' * ', c2, ' * ', c3)
  ans =
     ABCDE * FGHIJKLM * NOPQR
  

Skip two elements between each read by specifying a skip argument of 2:

• fid = fopen('alphabet.txt', 'r');
  c = fread(fid, 'char', 2);    % Skip 2 bytes per read
  fclose(fid);
  
  sprintf('%c', c)
  ans =
     ADGJMPSVY
  

Example 2

This command displays the complete M-file containing this fread help entry:

• type fread.m
  

To simulate this command using fread, enter the following:

• fid = fopen('fread.m', 'r');
  F = fread(fid, '*char')';
  fclose(fid);
  

In the example, the fread command assumes the default size, 'inf', and precision '*uchar' (the same as 'char=>char'). fread reads the entire file. To display the result as readable text, the column vector is transposed to a row vector.

Example 3

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 is done before the command is finished. If the last block read is not a full block, then fread does not finish with a skip.

See fopen for information about reading big and little-endian files.

Example 4

Invoke the fopen function with just an fid input argument to obtain the machine format for the file. You can see that this file was written in IEEE floating point with little-endian byte ordering ('ieee-le') format:

• fid = fopen('A1.dat', 'r');
  
  [fname, mode, mformat] = fopen(fid);
  mformat
  mformat =
     ieee-le
  

Use the MATLAB format function (not related to the machine format type) to have MATLAB display output using hexadecimal:

• format hex
  

Now use the machineformat input with fread to read the data from the file using the same format:

• x = fread(fid, 6, 'uint64', 'ieee-le')
  x =
     4260800000002000
     0000000000000000
     4282000000180000
     0000000000000000
     42ca5e0000258000
     42f0000464d45200
  fclose(fid);
  

Change the machine format to IEEE floating point with big-endian byte ordering ('ieee-be') and verify that you get different results:

• fid = fopen('A1.dat', 'r');
  x = fread(fid, 6, 'uint64', 'ieee-be')
  x =
     4370000008400000
     0000000000000000
     4308000200100000
     0000000000000000
     4352c0002f0d0000
     43c022a6a3000000
  fclose(fid);
  

See Also

fgetl, fscanf, fwrite, fprintf, fopen, fclose, fseek, ftell, feof

frameedit

freqspace

© 1994-2005 The MathWorks, Inc.