MATLAB Function Reference

memmapfile

Construct memory map object

Syntax

• m = memmapfile(filename)
  m = memmapfile(filename, pname1, pval1, pname2, pval2, ...)
  

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 UNIX platforms, but is not case sensitive on Windows.

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 Programming documentation for more information on this:

• Mapping a Single Data Type
• Formatting the Mapped Data to an Array
• Mapping Multiple Data Types and Arrays

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

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

memory

© 1994-2005 The MathWorks, Inc.