Learn more about MATLAB

memmapfile - Construct memmapfile object

Syntax

m = memmapfile(filename) m = memmapfile(filename, prop1, value1, prop2, value2, ...)

Description

m = memmapfile(filename) constructs an object of the memmapfile class that maps file filename to memory using the default property values. The filename input is a quoted string that specifies the path and name of the file to be mapped into memory. filename must include a filename extension if the name of the file being mapped has an extension. The filename argument cannot include any wildcard characters (e.g., * or ?), is case sensitive on The Open Group UNIX platforms, but is not case sensitive on Microsoft Windows platforms.

m = memmapfile(filename, prop1, value1, prop2, value2, ...) constructs an object of the memmapfile class that maps file filename into memory and sets the properties of that object that are named in the argument list (prop1, prop2, etc.) to the given values (value1, value2, etc.). All property name arguments must be quoted strings (e.g., 'Writable'). Any properties that are not specified are given their default values.

Optional properties are shown in the table below and are described in the sections that follow.

Property	Description	Data Type	Default
`Format`	Format of the contents of the mapped region, including data type, array shape, and variable or field name by which to access the data	`char` array or N-by-3 `cell` array	`uint8`
`Offset`	Number of bytes from the start of the file to the start of the mapped region. This number is zero-based. That is, offset 0 represents the start of the file.	`double`	`0`
`Repeat`	Number of times to apply the specified format to the mapped region of the file	`double`	`Inf`
`Writable`	Type of access allowed to the mapped region	`logical`	false

There are three different ways you can specify a value for the Format property. See the following sections in the MATLAB Data Import and Export documentation for more information:

Any of the following data types can be used when you specify a Format value. The default type is uint8.

Format String	Data Type Description
`'int8'`	Signed 8-bit integers
`'int16'`	Signed 16-bit integers
`'int32'`	Signed 32-bit integers
`'int64'`	Signed 64-bit integers
`'uint8'`	Unsigned 8-bit integers
`'uint16'`	Unsigned 16-bit integers
`'uint32'`	Unsigned 32-bit integers
`'uint64'`	Unsigned 64-bit integers
`'single'`	32-bit floating-point
`'double'`	64-bit floating-point

Remarks

You can only map 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.

Once memmapfile locates the file, MATLAB stores the absolute pathname for the file internally, and then uses this stored path to locate the file from that point on. This enables you to work in other directories outside your current work directory and retain access to the mapped file.

Once a memmapfile object has been constructed, you can change the value of any of its properties. Use the objname.property syntax in assigning the new value. To set a new offset value for memory map object m, type

m.Offset = 2048;

Property names are not case sensitive. For example, MATLAB considers m.Offset to be the same as m.offset.

Examples

To run the following examples, create a file in your current folder called records.dat. Example 2 expects that records.dat contains 5000 double-precision values. The following code shows one method to create this file:

randData = gallery('uniformdata', [5000, 1], 0, 'double');

fid = fopen('records.dat','w');
fwrite(fid, randData, 'double');
fclose(fid);

Example 1

To construct a map for records.dat, type the following:

m = memmapfile('records.dat');

MATLAB constructs an instance of the memmapfile class, assigns it to the variable m, and maps the entire records.dat file to memory, setting all properties of the object to their default values. 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.

Example 2

To construct a map using nondefault values for the Offset, Format, and Writable properties, type the following, enclosing all property names in single quotation marks:

m = memmapfile('records.dat',         ...
               'Offset', 1024,        ...
               'Format', 'uint32',    ...
               'Writable', true);

Type the object name to see the current settings for all properties:

m

m =
    Filename: 'd:\matlab\mfiles\records.dat'
    Writable: true
      Offset: 1024
      Format: 'uint32'
      Repeat: Inf
        Data: 9744x1 uint32 array

Example 3

Construct a memmapfile object for the entire file records.dat and set the Format property for that object to uint64. Any read or write operations made via the memory map will read and write the file contents as a sequence of unsigned 64-bit integers:

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

Example 4

Construct a memmapfile object for a region of records.dat such that the contents of the region are handled by MATLAB as a 4-by-10-by-18 array of unsigned 32-bit integers, and can be referenced in the structure of the returned object using the field name x:

m = memmapfile('records.dat',    ...
               'Offset', 1024,   ...
               'Format', {'uint32' [4 10 18] 'x'});

A = m.Data(1).x;

whos A
  Name      Size                     Bytes  Class

  A        4x10x18                   2880   uint32 array

Example 5

Map a file to three different data types: int16, uint32, and single. The int16 data is mapped as a 2-by-2 matrix that can be accessed using the field name model. The uint32 data is a scalar value accessed as field serialno. The single data is a 1-by-3 matrix named expenses. Repeat the pattern 1000 times.

Each of the fields belongs to the 1000-by-1 structure array m.Data:

m = memmapfile('records.dat',                   ...
               'Format', {                      ...
                  'int16'  [2 2] 'model';       ...
                  'uint32' [1 1] 'serialno';    ...
                  'single' [1 3] 'expenses'},   ...
               'Repeat', 1000);