memmapfile
Create memory map to a file
Description
maps
an existing file, m
= memmapfile(filename
)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.
specifies
the properties of m
= memmapfile(filename
,Name,Value
)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 Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
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
— Write permission
false
(default) | true
Write permission, specified as true
or
false
. If you specify false
, the mapped region
is read-only. If you specify true
, the mapped region has both read
and write permissions.
Example: 'Writable',true
Data Types: logical
Offset
— Distance from start of file
0 (default) | nonnegative integer
Distance from start of file to start of mapped region, specified as a nonnegative integer. This value is zero-based, a 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, specified as a character vector, string scalar, or
n
-by-3 cell array.
If the region you are mapping contains data of only one type, specify the Format
value as a character vector or string scalar identifying the type. For example, if
your data consists of only 16-bit signed integers, specify 'int16'
.
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'
If the region you are mapping requires you to specify an array shape to the data
in the mapped file, as well as a field name to reference this array, specify the
Format
value as a 1-by-3 cell array.
The first cell value, specified as a character vector or string scalar, assigns the data type to apply to the mapped region.
The second cell value, specified as a 1-by-n array, assigns the array dimensions to apply to the mapped region.
The third cell value, specified as a character vector or string scalar, assigns the field name to use in the
Data
structure array of the memory map. For 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 each segment's format using the rows of an n-by-3 cell
array. For example, {'uint64',[30 4 10],'x'; 'uint32',[30 4
6],'y'}
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,
specified as Inf
or a positive integer. If you specify
Inf
, 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 |
---|---|
| Path and name of the mapped file |
| Type of access allowed to the mapped region |
| Number of bytes from the start of the file to the start of the mapped region |
| Format of the contents of the mapped region, including data type, array size, and field name by which to access the data |
| Number of times to apply the pattern specified by the Format property
to the mapped region of the file |
| 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, callm.Data
.If
Data
is a scalar (1-by-1) structure array, callm.Data.
, wherefieldname
fieldname
is the name of a field.If
Data
is a nonscalar structure array, callm.Data(
whereindex
).fieldname
index
is the index for the element in the structure array, andfieldname
is the name of a field. For example, to access the file data in thetemperature
field of the first element ofData
, callm.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 likefopen
andfwrite
.
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.
Version History
Introduced before R2006a
See Also
Comando MATLAB
Hai fatto clic su un collegamento che corrisponde a questo comando MATLAB:
Esegui il comando inserendolo nella finestra di comando MATLAB. I browser web non supportano i comandi MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)