Edit

Share via


MemoryMappedFile.CreateFromFile Method

Definition

Creates a memory-mapped file from an existing file.

Overloads

CreateFromFile(String)

Creates a memory-mapped file from a file on disk.

CreateFromFile(String, FileMode)

Creates a memory-mapped file that has the specified access mode from a file on disk.

CreateFromFile(String, FileMode, String)

Creates a memory-mapped file that has the specified access mode and name from a file on disk.

CreateFromFile(String, FileMode, String, Int64)

Creates a memory-mapped file that has the specified access mode, name, and capacity from a file on disk.

CreateFromFile(String, FileMode, String, Int64, MemoryMappedFileAccess)

Creates a memory-mapped file that has the specified access mode, name, capacity, and access type from a file on disk.

CreateFromFile(SafeFileHandle, String, Int64, MemoryMappedFileAccess, HandleInheritability, Boolean)

Creates a memory-mapped file from an existing file using a SafeFileHandle and the specified access mode, name, inheritability, and capacity.

CreateFromFile(FileStream, String, Int64, MemoryMappedFileAccess, HandleInheritability, Boolean)

Creates a memory-mapped file from an existing file with the specified access mode, name, inheritability, and capacity.

CreateFromFile(FileStream, String, Int64, MemoryMappedFileAccess, MemoryMappedFileSecurity, HandleInheritability, Boolean)

Creates a memory-mapped file that has the specified name, capacity, access type, security permissions, inheritability, and disposal requirement from a file on disk.

CreateFromFile(String)

Source:
MemoryMappedFile.cs
Source:
MemoryMappedFile.cs
Source:
MemoryMappedFile.cs

Creates a memory-mapped file from a file on disk.

public:
 static System::IO::MemoryMappedFiles::MemoryMappedFile ^ CreateFromFile(System::String ^ path);
public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (string path);
static member CreateFromFile : string -> System.IO.MemoryMappedFiles.MemoryMappedFile
Public Shared Function CreateFromFile (path As String) As MemoryMappedFile

Parameters

path
String

The path to file to map.

Returns

A memory-mapped file.

Exceptions

path is an empty string, contains only white space, or has one or more invalid characters, as defined by the GetInvalidFileNameChars() method.

-or-

path refers to an invalid device.

path is null.

An I/O error occurred.

path exceeds the maximum length defined by the operating system.

The caller does not have the required permissions for the file.

Examples

The following example uses the CreateFromFile method to create a memory-mapped file, and then creates a memory-mapped view to a portion of an extremely large file.

using System;
using System.IO;
using System.IO.MemoryMappedFiles;
using System.Runtime.InteropServices;

class Program
{
    static void Main(string[] args)
    {
        long offset = 0x10000000; // 256 megabytes
        long length = 0x20000000; // 512 megabytes

        // Create the memory-mapped file.
        using (var mmf = MemoryMappedFile.CreateFromFile(@"c:\ExtremelyLargeImage.data", FileMode.Open,"ImgA"))
        {
            // Create a random access view, from the 256th megabyte (the offset)
            // to the 768th megabyte (the offset plus length).
            using (var accessor = mmf.CreateViewAccessor(offset, length))
            {
                int colorSize = Marshal.SizeOf(typeof(MyColor));
                MyColor color;

                // Make changes to the view.
                for (long i = 0; i < length; i += colorSize)
                {
                    accessor.Read(i, out color);
                    color.Brighten(10);
                    accessor.Write(i, ref color);
                }
            }
        }
    }
}

public struct MyColor
{
    public short Red;
    public short Green;
    public short Blue;
    public short Alpha;

    // Make the view brighter.
    public void Brighten(short value)
    {
        Red = (short)Math.Min(short.MaxValue, (int)Red + value);
        Green = (short)Math.Min(short.MaxValue, (int)Green + value);
        Blue = (short)Math.Min(short.MaxValue, (int)Blue + value);
        Alpha = (short)Math.Min(short.MaxValue, (int)Alpha + value);
    }
}
Imports System.IO
Imports System.IO.MemoryMappedFiles
Imports System.Runtime.InteropServices

Class Program

    Sub Main()
        Dim offset As Long = &H10000000 ' 256 megabytes
        Dim length As Long = &H20000000 ' 512 megabytes

        ' Create the memory-mapped file.
        Using mmf = MemoryMappedFile.CreateFromFile("c:\ExtremelyLargeImage.data", FileMode.Open, "ImgA")
            ' Create a random access view, from the 256th megabyte (the offset)
            ' to the 768th megabyte (the offset plus length).
            Using accessor = mmf.CreateViewAccessor(offset, length)
                Dim colorSize As Integer = Marshal.SizeOf(GetType(MyColor))
                Dim color As MyColor
                Dim i As Long = 0

                ' Make changes to the view.
                Do While (i < length)
                    accessor.Read(i, color)
                    color.Brighten(10)
                    accessor.Write(i, color)
                    i += colorSize
                Loop
            End Using
        End Using
    End Sub
End Class

Public Structure MyColor
    Public Red As Short
    Public Green As Short
    Public Blue As Short
    Public Alpha As Short

    ' Make the view brighter.
    Public Sub Brighten(ByVal value As Short)
        Red = CType(Math.Min(Short.MaxValue, (CType(Red, Integer) + value)), Short)
        Green = CType(Math.Min(Short.MaxValue, (CType(Green, Integer) + value)), Short)
        Blue = CType(Math.Min(Short.MaxValue, (CType(Blue, Integer) + value)), Short)
        Alpha = CType(Math.Min(Short.MaxValue, (CType(Alpha, Integer) + value)), Short)
    End Sub
End Structure

See also

Applies to

CreateFromFile(String, FileMode)

Source:
MemoryMappedFile.cs
Source:
MemoryMappedFile.cs
Source:
MemoryMappedFile.cs

Creates a memory-mapped file that has the specified access mode from a file on disk.

public:
 static System::IO::MemoryMappedFiles::MemoryMappedFile ^ CreateFromFile(System::String ^ path, System::IO::FileMode mode);
public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (string path, System.IO.FileMode mode);
static member CreateFromFile : string * System.IO.FileMode -> System.IO.MemoryMappedFiles.MemoryMappedFile
Public Shared Function CreateFromFile (path As String, mode As FileMode) As MemoryMappedFile

Parameters

path
String

The path to the file to map.

mode
FileMode

Access mode; must be Open.

Returns

A memory-mapped file that has the specified access mode.

Exceptions

path is an empty string, contains only white space, or has one or more invalid characters, as defined by the GetInvalidFileNameChars() method.

-or-

path refers to an invalid device.

-or-

mode is Append.

path is null.

mode is Create, CreateNew, or Truncate.

-or-

mode is OpenOrCreate and the file on disk does not exist.

-or-

An I/O error occurred.

path exceeds the maximum length defined by the operating system.

The caller does not have the required permissions for the file.

Remarks

The mode parameter pertains to the source file on disk. You can use only the Open enumeration value to create the memory-mapped file from the source file on disk.

See also

Applies to

CreateFromFile(String, FileMode, String)

Source:
MemoryMappedFile.cs
Source:
MemoryMappedFile.cs
Source:
MemoryMappedFile.cs

Creates a memory-mapped file that has the specified access mode and name from a file on disk.

public:
 static System::IO::MemoryMappedFiles::MemoryMappedFile ^ CreateFromFile(System::String ^ path, System::IO::FileMode mode, System::String ^ mapName);
public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (string path, System.IO.FileMode mode, string? mapName);
public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (string path, System.IO.FileMode mode, string mapName);
static member CreateFromFile : string * System.IO.FileMode * string -> System.IO.MemoryMappedFiles.MemoryMappedFile
Public Shared Function CreateFromFile (path As String, mode As FileMode, mapName As String) As MemoryMappedFile

Parameters

path
String

The path to the file to map.

mode
FileMode

Access mode; must be Open.

mapName
String

A name to assign to the memory-mapped file, or null for a MemoryMappedFile that you do not intend to share across processes.

Returns

A memory-mapped file that has the specified name and access mode.

Exceptions

path is an empty string, contains only white space, or has one or more invalid characters, as defined by the GetInvalidFileNameChars() method.

-or-

path refers to an invalid device.

-or-

mapName is an empty string.

-or-

mode is Append.

path is null.

mode is Create, CreateNew, or Truncate.

-or-

mode is OpenOrCreate and the file on disk does not exist.

-or-

An I/O error occurred.

path exceeds the maximum length defined by the operating system.

The caller does not have the required permissions for the file.

Remarks

The mode parameter pertains to the source file on disk. You can use only the Open enumeration value to create the memory-mapped file from the source file on disk.

Applies to

CreateFromFile(String, FileMode, String, Int64)

Source:
MemoryMappedFile.cs
Source:
MemoryMappedFile.cs
Source:
MemoryMappedFile.cs

Creates a memory-mapped file that has the specified access mode, name, and capacity from a file on disk.

public:
 static System::IO::MemoryMappedFiles::MemoryMappedFile ^ CreateFromFile(System::String ^ path, System::IO::FileMode mode, System::String ^ mapName, long capacity);
public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (string path, System.IO.FileMode mode, string? mapName, long capacity);
public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (string path, System.IO.FileMode mode, string mapName, long capacity);
static member CreateFromFile : string * System.IO.FileMode * string * int64 -> System.IO.MemoryMappedFiles.MemoryMappedFile
Public Shared Function CreateFromFile (path As String, mode As FileMode, mapName As String, capacity As Long) As MemoryMappedFile

Parameters

path
String

The path to the file to map.

mode
FileMode

Access mode; can be any of the FileMode enumeration values except Append.

mapName
String

A name to assign to the memory-mapped file, or null for a MemoryMappedFile that you do not intend to share across processes.

capacity
Int64

The maximum size, in bytes, to allocate to the memory-mapped file. Specify 0 to set the capacity to the size of the file on disk.

Returns

A memory-mapped file that has the specified characteristics.

Exceptions

path is an empty string, contains only white space, or has one or more invalid characters, as defined by the GetInvalidFileNameChars() method.

-or-

path refers to an invalid device.

-or-

mapName is an empty string.

-or-

mode is Append.

path is null.

capacity is greater than the size of the logical address space.

-or-

capacity is less than zero.

-or-

capacity is less than the file size (but not zero).

-or-

capacity is zero, and the size of the file on disk is also zero.

An I/O error occurred.

path exceeds the maximum length defined by the operating system.

The caller does not have the required permissions for the file.

Remarks

The mode parameter pertains to the source file on disk.

If capacity is larger than the size of the file on disk, the file on disk is increased to match the specified capacity even if no data is written to the memory-mapped file. To prevent this from occurring, specify 0 (zero) for the default capacity, which will internally set capacity to the size of the file on disk.

Applies to

CreateFromFile(String, FileMode, String, Int64, MemoryMappedFileAccess)

Source:
MemoryMappedFile.cs
Source:
MemoryMappedFile.cs
Source:
MemoryMappedFile.cs

Creates a memory-mapped file that has the specified access mode, name, capacity, and access type from a file on disk.

public:
 static System::IO::MemoryMappedFiles::MemoryMappedFile ^ CreateFromFile(System::String ^ path, System::IO::FileMode mode, System::String ^ mapName, long capacity, System::IO::MemoryMappedFiles::MemoryMappedFileAccess access);
public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (string path, System.IO.FileMode mode, string? mapName, long capacity, System.IO.MemoryMappedFiles.MemoryMappedFileAccess access);
public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (string path, System.IO.FileMode mode, string mapName, long capacity, System.IO.MemoryMappedFiles.MemoryMappedFileAccess access);
[System.Security.SecurityCritical]
public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (string path, System.IO.FileMode mode, string mapName, long capacity, System.IO.MemoryMappedFiles.MemoryMappedFileAccess access);
static member CreateFromFile : string * System.IO.FileMode * string * int64 * System.IO.MemoryMappedFiles.MemoryMappedFileAccess -> System.IO.MemoryMappedFiles.MemoryMappedFile
[<System.Security.SecurityCritical>]
static member CreateFromFile : string * System.IO.FileMode * string * int64 * System.IO.MemoryMappedFiles.MemoryMappedFileAccess -> System.IO.MemoryMappedFiles.MemoryMappedFile
Public Shared Function CreateFromFile (path As String, mode As FileMode, mapName As String, capacity As Long, access As MemoryMappedFileAccess) As MemoryMappedFile

Parameters

path
String

The path to the file to map.

mode
FileMode

Access mode; can be any of the FileMode enumeration values except Append.

mapName
String

A name to assign to the memory-mapped file, or null for a MemoryMappedFile that you do not intend to share across processes.

capacity
Int64

The maximum size, in bytes, to allocate to the memory-mapped file. Specify 0 to set the capacity to the size of the file on disk.

access
MemoryMappedFileAccess

One of the enumeration values that specifies the type of access allowed to the memory-mapped file.

Returns

A memory-mapped file that has the specified characteristics.

Attributes

Exceptions

mapName is an empty string.

-or-

access is not an allowed value.

-or-

path specifies an empty file.

-or-

access is specified as Read and capacity is greater than the size of the file indicated by path.

-or-

mode is Append.

path is null.

capacity is greater than the size of the logical address space.

-or-

capacity is less than zero.

-or-

capacity is less than the file size (but not zero).

-or-

capacity is zero, and the size of the file on disk is also zero.

-or-

access is not a defined MemoryMappedFileAccess value.

-or-

The size of the file indicated by path is greater than capacity.

-or-

An I/O error occurred.

path exceeds the maximum length defined by the operating system.

The caller does not have the required permissions for the file.

Remarks

The mode parameter pertains to the source file on disk.

If capacity is larger than the size of the file on disk, the file on disk is increased to match the specified capacity even if no data is written to the memory-mapped file. To prevent this from occurring, specify 0 (zero) for the default capacity, which will internally set capacity to the size of the file on disk.

See also

Applies to

CreateFromFile(SafeFileHandle, String, Int64, MemoryMappedFileAccess, HandleInheritability, Boolean)

Source:
MemoryMappedFile.cs
Source:
MemoryMappedFile.cs

Creates a memory-mapped file from an existing file using a SafeFileHandle and the specified access mode, name, inheritability, and capacity.

public:
 static System::IO::MemoryMappedFiles::MemoryMappedFile ^ CreateFromFile(Microsoft::Win32::SafeHandles::SafeFileHandle ^ fileHandle, System::String ^ mapName, long capacity, System::IO::MemoryMappedFiles::MemoryMappedFileAccess access, System::IO::HandleInheritability inheritability, bool leaveOpen);
public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (Microsoft.Win32.SafeHandles.SafeFileHandle fileHandle, string? mapName, long capacity, System.IO.MemoryMappedFiles.MemoryMappedFileAccess access, System.IO.HandleInheritability inheritability, bool leaveOpen);
static member CreateFromFile : Microsoft.Win32.SafeHandles.SafeFileHandle * string * int64 * System.IO.MemoryMappedFiles.MemoryMappedFileAccess * System.IO.HandleInheritability * bool -> System.IO.MemoryMappedFiles.MemoryMappedFile
Public Shared Function CreateFromFile (fileHandle As SafeFileHandle, mapName As String, capacity As Long, access As MemoryMappedFileAccess, inheritability As HandleInheritability, leaveOpen As Boolean) As MemoryMappedFile

Parameters

fileHandle
SafeFileHandle

The SafeFileHandle to the existing file. Caller is responsible for disposing fileHandle when leaveOpen is true (otherwise, automatically disposed by the MemoryMappedFile).

mapName
String

A name to assign to the memory-mapped file, or null for a MemoryMappedFile that you do not intend to share across processes.

capacity
Int64

The maximum size, in bytes, to allocate to the memory-mapped file. Specify 0 to set the capacity to the size of the file.

access
MemoryMappedFileAccess

One of the enumeration values that specifies the type of access allowed to the memory-mapped file.

This parameter can't be set to Write.

inheritability
HandleInheritability

One of the enumeration values that specifies whether a handle to the memory-mapped file can be inherited by a child process. The default is None.

leaveOpen
Boolean

A value that indicates whether to close the source file handle when the MemoryMappedFile is disposed.

Returns

A memory-mapped file that has the specified characteristics.

Exceptions

mapName is null or an empty string.

-or-

capacity and the length of the file are zero.

-or-

access is set to Write, which is not allowed.

-or-

access is set to Read and capacity is larger than the length of the file.

fileHandle is null.

capacity is less than zero.

-or-

capacity is less than the file size.

-or-

access is not a valid MemoryMappedFileAccess enumeration value.

-or-

inheritability is not a valid HandleInheritability enumeration value.

Applies to

CreateFromFile(FileStream, String, Int64, MemoryMappedFileAccess, HandleInheritability, Boolean)

Source:
MemoryMappedFile.cs
Source:
MemoryMappedFile.cs
Source:
MemoryMappedFile.cs

Creates a memory-mapped file from an existing file with the specified access mode, name, inheritability, and capacity.

public:
 static System::IO::MemoryMappedFiles::MemoryMappedFile ^ CreateFromFile(System::IO::FileStream ^ fileStream, System::String ^ mapName, long capacity, System::IO::MemoryMappedFiles::MemoryMappedFileAccess access, System::IO::HandleInheritability inheritability, bool leaveOpen);
public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (System.IO.FileStream fileStream, string? mapName, long capacity, System.IO.MemoryMappedFiles.MemoryMappedFileAccess access, System.IO.HandleInheritability inheritability, bool leaveOpen);
public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (System.IO.FileStream fileStream, string mapName, long capacity, System.IO.MemoryMappedFiles.MemoryMappedFileAccess access, System.IO.HandleInheritability inheritability, bool leaveOpen);
static member CreateFromFile : System.IO.FileStream * string * int64 * System.IO.MemoryMappedFiles.MemoryMappedFileAccess * System.IO.HandleInheritability * bool -> System.IO.MemoryMappedFiles.MemoryMappedFile
Public Shared Function CreateFromFile (fileStream As FileStream, mapName As String, capacity As Long, access As MemoryMappedFileAccess, inheritability As HandleInheritability, leaveOpen As Boolean) As MemoryMappedFile

Parameters

fileStream
FileStream

The file stream of the existing file.

mapName
String

A name to assign to the memory-mapped file, or null for a MemoryMappedFile that you do not intend to share across processes.

capacity
Int64

The maximum size, in bytes, to allocate to the memory-mapped file. Specify 0 to set the capacity to the size of filestream.

access
MemoryMappedFileAccess

One of the enumeration values that specifies the type of access allowed to the memory-mapped file.

This parameter can't be set to Write.

inheritability
HandleInheritability

One of the enumeration values that specifies whether a handle to the memory-mapped file can be inherited by a child process. The default is None.

leaveOpen
Boolean

A value that indicates whether to close the source file stream when the MemoryMappedFile is disposed.

Returns

A memory-mapped file that has the specified characteristics.

Exceptions

mapName is null or an empty string.

-or-

capacity and the length of the file are zero.

-or-

access is set to Write or Write enumeration value, which is not allowed.

-or-

access is set to Read and capacity is larger than the length of filestream.

fileStream is null.

capacity is less than zero.

-or-

capacity is less than the file size.

-or-

access is not a valid MemoryMappedFileAccess enumeration value.

-or-

inheritability is not a valid HandleInheritability enumeration value.

Applies to

CreateFromFile(FileStream, String, Int64, MemoryMappedFileAccess, MemoryMappedFileSecurity, HandleInheritability, Boolean)

Creates a memory-mapped file that has the specified name, capacity, access type, security permissions, inheritability, and disposal requirement from a file on disk.

public:
 static System::IO::MemoryMappedFiles::MemoryMappedFile ^ CreateFromFile(System::IO::FileStream ^ fileStream, System::String ^ mapName, long capacity, System::IO::MemoryMappedFiles::MemoryMappedFileAccess access, System::IO::MemoryMappedFiles::MemoryMappedFileSecurity ^ memoryMappedFileSecurity, System::IO::HandleInheritability inheritability, bool leaveOpen);
[System.Security.SecurityCritical]
public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (System.IO.FileStream fileStream, string mapName, long capacity, System.IO.MemoryMappedFiles.MemoryMappedFileAccess access, System.IO.MemoryMappedFiles.MemoryMappedFileSecurity memoryMappedFileSecurity, System.IO.HandleInheritability inheritability, bool leaveOpen);
[<System.Security.SecurityCritical>]
static member CreateFromFile : System.IO.FileStream * string * int64 * System.IO.MemoryMappedFiles.MemoryMappedFileAccess * System.IO.MemoryMappedFiles.MemoryMappedFileSecurity * System.IO.HandleInheritability * bool -> System.IO.MemoryMappedFiles.MemoryMappedFile
Public Shared Function CreateFromFile (fileStream As FileStream, mapName As String, capacity As Long, access As MemoryMappedFileAccess, memoryMappedFileSecurity As MemoryMappedFileSecurity, inheritability As HandleInheritability, leaveOpen As Boolean) As MemoryMappedFile

Parameters

fileStream
FileStream

The fileStream to the file to map.

mapName
String

A name to assign to the memory-mapped file, or null for a MemoryMappedFile that you do not intend to share across processes.

capacity
Int64

The maximum size, in bytes, to allocate to the memory-mapped file. Specify 0 to set the capacity to the size of the file on disk.

access
MemoryMappedFileAccess

One of the enumeration values that specifies the type of access allowed to the memory-mapped file.

This parameter can't be set to Write.

memoryMappedFileSecurity
MemoryMappedFileSecurity

The permissions that can be granted for file access and operations on memory-mapped files.

This parameter can be null.

inheritability
HandleInheritability

One of the enumeration values that specifies whether a handle to the memory-mapped file can be inherited by a child process. The default is None.

leaveOpen
Boolean

true to not dispose fileStream after the MemoryMappedFile is closed; false to dispose fileStream.

Returns

A memory-mapped file that has the specified characteristics.

Attributes

Exceptions

mapName is an empty string.

-or-

capacity and the length of the file are zero.

-or-

access is set to the Read or Write enumeration value, which is not allowed.

fileStream is null.

capacity is less than zero.

-or-

capacity is less than the file size.

-or-

access is not a valid MemoryMappedFileAccess enumeration value.

-or-

inheritability is not a valid HandleInheritability enumeration value.

fileStream was closed.

access is set to ReadWrite when fileStream's access is set to Read or Write.

mapName already exists.

Remarks

If capacity is larger than the size of the file on disk, the file on disk is increased to match the specified capacity even if no data is written to the memory-mapped file. To prevent this from occurring, specify 0 (zero) for the default capacity, which will internally set capacity to the size of the file on disk.

See also

Applies to