MATLAB Function Reference

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.

There are three different ways you can specify a value for the Format property. See the following sections in the MATLAB^® Programming Fundamentals documentation for more information on this:

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

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

Example 1

To construct a map for the file records.dat that resides in your current working directory, 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: 4778x1 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.x;

whos A
  Name      Size                     Bytes  Class

  A        4x10x18                   2880   uint32 array

Grand total is 720 elements using 2880 bytes 

Example 5

Map a 24 kilobyte file containing data of 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.

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

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

Example 6

Map a file region identical to that of the previous example, except repeat the pattern of int16, uint32, and single data types only three times within the mapped region of the file. Allow write access to the file by setting the Writable property to true:

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

See Also

disp(memmapfile), get(memmapfile)

median (timeseries)

memory