memmapfile

Create memory map to a file

Syntax

m = memmapfile(filename)

m = memmapfile(filename,Name,Value)

Description

m = memmapfile(filename) maps an existing file, filename, to memory and returns the memory map, m.

Memory-mapping is a mechanism that maps a portion of a file, or an entire file, on disk to a range of memory addresses within the MATLAB^® address space. Then, MATLAB can access files on disk in the same way it accesses dynamic memory, accelerating file reading and writing. Memory-mapping allows you to work with data in a file as if it were a MATLAB array.

m = memmapfile(filename,Name,Value) specifies the properties of m using one or more name-value pair arguments. For example, you can specify the format of the data in the file.

Examples

Map Entire File of uint8 Data

At the command prompt, create a sample file in your current folder called records.dat, containing 10 uint8 values.

myData = uint8(1:10)';

fileID = fopen('records.dat','w');
fwrite(fileID, myData,'uint8');
fclose(fileID);

Create a map for records.dat. When using memmapfile, the default data format is uint8 so the file name is the only required input argument in this case.

m = memmapfile('records.dat')

m = 

    Filename: 'd:\matlab\records.dat'
    Writable: false
      Offset: 0
      Format: 'uint8'
      Repeat: Inf
        Data: 10x1 uint8 array

MATLAB maps the entire records.dat file to memory, setting all properties of the memory map to their default values. The memory map is assigned to the variable, m. In this example, the command maps the entire file as a sequence of unsigned 8-bit integers and gives the caller read-only access to its contents.

View the mapped data by accessing the Data property of m.

m.Data

ans =

    1
    2
    3
    4
    5
    6
    7
    8
    9
   10

Map Entire File of Double-Precision Data

Create a memory map for double-precision data. The syntax is similar when specifying other data types.

At the command prompt, create a sample file in your current folder called records.dat, containing 10 double values.

myData = (1:10)';

fileID = fopen('records.dat','w');
fwrite(fileID,myData,'double');
fclose(fileID);

Create a memory map for records.dat, and set the Format property for the output to 'double'.

m = memmapfile('records.dat','Format','double') ;

The memmapfile, m, contains the following properties: Filename, Writable, Offset, Format, Repeat, and Data. To display any one property, for example Format, type m.Format in the command window.

m.Format

ans = 
'double'

The Data property contains the 10 double-precision values in records.dat.

Map and Change Part of a File

Create a memory map for a large array of int32 data. Specify write access, and nondefault Format and Offset values.

At the command prompt, create a sample file in your current folder called records.dat, containing 10,000 int32 values.

myData = int32([1:10000]);

fileID = fopen('records.dat','w');
fwrite(fileID,myData,'int32');
fclose(fileID);

Create a memory map for records.dat, and set the Format property for the output to int32. Also, set the Offset property to disregard the first 9000 bytes in the file, and the Writable property to permit write access.

m = memmapfile('records.dat',...
               'Offset',9000,...
               'Format','int32',...
               'Writable',true);

An Offset value of 9000 indicates that the first 9000 bytes of records.dat are not mapped.

Type the name of the memory map to see the current settings for all properties.

m

m =
    Filename: 'd:\matlab\records.dat'
    Writable: true
      Offset: 9000
      Format: 'int32'
      Repeat: Inf
        Data: 7750x1 int32 array

The Format property indicates that any read or write operation made via the memory map reads and writes the file contents as a sequence of signed 32-bit integers. The Data property contains only 7750 elements because the first 9000 bytes of records.dat, representing the first 2250 values in the file, are not mapped.

View the first five elements of the mapped data by accessing the Data property of m.

m.Data(1:5)

ans =

        2251
        2252
        2253
        2254
        2255

Map Region of File to Specific Array Shape

Create a memory map for a region of a file containing 100 double-precision values.

At the command prompt, create a sample file in your current folder called mybinary.bin, containing 100 double-precision values.

rng('default')
randData = rand([100,1]);

fileID = fopen('mybinary.bin','w');
fwrite(fileID,randData,'double');
fclose(fileID);

Map the first 75 values in mybinary.bin to a 5-by-5-by-3 array of double-precision values that can be referenced in the structure of the memory map using the field name x. Specify these parameters with the Format name-value pair argument.

m = memmapfile('mybinary.bin',...
               'Format',{'double',[5 5 3],'x'})

m = 

    Filename: 'd:\matlab\mybinary.bin'
    Writable: false
      Offset: 0
      Format: {'double' [5 5 3] 'x'}
      Repeat: Inf
        Data: 1x1 struct array with fields:
                x

The Data property is a structure array that contains the mapped values in the field, x.

Assign the mapped data to a variable, A. Because the Data property is a structure array, you must index into the field, x, to access the data.

A = m.Data.x;

View information about A.

whos A

  Name      Size             Bytes  Class     Attributes

  A         5x5x3              600  double                       

Map Segments of File to Multiple Arrays

Map segments of a file with different array shapes and data types to memory.

At the command prompt, create a sample file in your current folder called mybinary.bin. Write uint16 data and double-precision data representing sample pressure, temperature, and volume values into the file. In this case, each of the uint16 arrays are 50-by-1 and the double-precision arrays are 5-by-10. k is a sample scaling factor.

rng('default')
k = 8.21;
pres1 = randi([1,300],[50,1],'uint16');
temp1 = randi([1,300],[50,1],'uint16');
vol1 = double(reshape(k*temp1./pres1,5,10));
pres2 = randi([5,500],[50,1],'uint16');
temp2 = randi([5,500],[50,1],'uint16');
vol2 = double(reshape(k*temp2./pres2,5,10));

fileID = fopen('mybinary.bin','w');
fwrite(fileID,pres1,'uint16');
fwrite(fileID,temp1,'uint16');
fwrite(fileID,vol1,'double');
fwrite(fileID,pres2,'uint16');
fwrite(fileID,temp2,'uint16');
fwrite(fileID,vol2,'double');
fclose(fileID);

Map the file to arrays accessible by unique names. Define a field, pressure, containing a 50-by-1 array of uint16 values, followed by a field, temperature, containing 50-by-1 uint16 values. Define a field, volume, containing a 5-by-10 array of double-precision values. Use a cell array to define the format of the mapped region and repeat the pattern twice.

m = memmapfile('mybinary.bin',...
'Format',{'uint16',[50 1],'pressure';...
'uint16',[50,1],'temperature';...
'double',[5,10],'volume'},'Repeat',2)

m = 

    Filename: 'd:\matlab\mybinary.bin'
    Writable: false
      Offset: 0
      Format: {'uint16' [50 1] 'pressure'
               'uint16' [50 1] 'temperature'
               'double' [5 10] 'volume'}
      Repeat: 2
        Data: 2x1 struct array with fields:
         pressure
      temperature
           volume

The Data property of the memory map, m, is a 2-by-1 structure array because the Format is applied twice.

Copy the Data property to a variable, A. Then, view the last block of double data, which you can access using the field name, volume.

A = m.Data;
myVolume = A(2).volume

myVolume =

     2    13    32     5     5    16     4    22     3     8
     2     9    53    38    13    19    23    85     2   120
    29    10     6     1     2     5     6    58    20    11
     7    15     4     1     5    18     1     4    14     8
     9     8     4     2     0     9     8     6     3     3

Input Arguments

filename — Name of file to map

character vector | string scalar

Name of the file to map including the file extension, specified as a character vector or string scalar. The filename argument cannot include any wildcard characters (for example, * or ?).

Example: 'myFile.dat'

Data Types: char | string

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: m = memmapfile('myFile.dat','Format','int32','Offset',255) maps int32 data in the file, myFile.dat, to memory starting from the 256th byte.

'Writable' — Type of access allowed to mapped region

false (default) | true

Type of access allowed to the mapped region, specified as the comma-separated pair consisting of 'Writable' and either true or false. If the Writable property is set to false, the mapped region is read-only. If true, then write access is allowed.

Example: 'Writable',true

Data Types: logical

'Offset' — Number of bytes from start of file to start of mapped region

0 (default) | nonnegative integer

Number of bytes from the start of the file to the start of the mapped region, specified as the comma-separated pair consisting of 'Offset' and a nonnegative integer. This value is zero-based. That is, an Offset value of 0 represents the start of the file.

Example: 'Offset',1024

Data Types: double

'Format' — Format of mapped region

'uint8' (default) | character vector | string scalar | n-by-3 cell array

Format of the mapped region contents, specified as the comma-separated pair consisting of 'Format' and a single character vector or string scalar, or an n-by-3 cell array.

• If the file region you are mapping contains data of only one type, specify the Format value as a character vector or string scalar identifying that type.
  Example:'int16'

• To specify an array shape to apply to the data read or written to the mapped file, and a field name to reference this array, specify the Format value as a 1-by-3 cell array. The first cell contains a character vector or string scalar identifying the data type to apply to the mapped region. The second cell contains the array dimensions to apply to the region. The third cell specifies the field name to use in the Data structure array of the memory map. Specify the field name as a string scalar or a character vector.
  Example: {'uint64',[30 4 10],'x'}

• If the region you are mapping is composed of segments of varying data types or array shapes, you can specify an individual format for each segment using an n-by-3 cell array, where n is the number of segments.
  Example: {'uint64',[30 4 10],'x'; 'uint32',[30 4 6],'y'}

You can use any of the following data types when you specify a Format value:

• 'int8'

• 'int16'

• 'int32'

• 'int64'

• 'uint8'

• 'uint16'

• 'uint32'

• 'uint64'

• 'single'

• 'double'

Data Types: char | string | cell

'Repeat' — Number of times to apply Format parameter

Inf (default) | positive integer

Number of times to apply the Format parameter to the mapped region of the file, specified as the comma-separated pair consisting of 'Repeat' and a positive integer. If the value of Repeat is Inf, then memmapfile applies the Format parameter until the end of the file.

Example: 'Repeat',2000

Data Types: double

Output Arguments

m — Memory map

memmapfile object

Memory map, returned as a memmapfile object with the following properties.

Property	Description
Filename	Path and name of the mapped file
Writable	Type of access allowed to the mapped region
Offset	Number of bytes from the start of the file to the start of the mapped region
Format	Format of the contents of the mapped region, including data type, array size, and field name by which to access the data
Repeat	Number of times to apply the pattern specified by the Format property to the mapped region of the file
Data	Memory-mapped data from the file. Data can be a numeric array or a structure array with field names specified in the Format property

The values for any property (except for Data) are set at the time you call memmapfile, using name-value pair arguments.

Access any property of m with dot notation similar to accessing fields of a structure array. For example, to access the memory-mapped data in the Data property, do one of the following:

• If Data is a numeric array, call m.Data.

• If Data is a scalar (1-by-1) structure array, call m.Data.fieldname, where fieldname is the name of a field.

• If Data is a nonscalar structure array, call m.Data(index).fieldname where index is the index for the element in the structure array, and fieldname is the name of a field. For example, to access the file data in the temperature field of the first element of Data, call m.Data(1).temperature.

After you create a memory map, m, you can change the value of any of its properties, except for Data. To assign a new value, use dot notation. For example, to set a new Offset value for m, type:

m.Offset = 2048;

Tips

• You can map only an existing file. You cannot create a new file and map that file to memory in one operation. Use the MATLAB file I/O functions to create the file before attempting to map it to memory.

• After memmapfile locates the file, MATLAB stores the file’s absolute pathname internally, and then uses this stored path to locate the file from that point on. As a result, you can work in other directories outside your current work directory and retain access to the mapped file.

• memmapfile does not expand or append to a mapped file. Use instead standard file I/O functions like fopen and fwrite.

Algorithms

The actual mapping of a file to the MATLAB address space does not take place when you construct a memmapfile object. A memory map, based on the information currently stored in the mapped object, is generated the first time you reference or modify the Data property for that object.