MemoryMappedFile.CreateFromFile Method

Definition

Namespace:

System.IO.MemoryMappedFiles

Assembly:

System.IO.MemoryMappedFiles.dll

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(String)

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

MemoryMappedFile

A memory-mapped file.

Exceptions

ArgumentException

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.

ArgumentNullException

path is null.

IOException

An I/O error occurred.

PathTooLongException

path exceeds the maximum length defined by the operating system.

SecurityException

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

• Memory-Mapped Files

CreateFromFile(String, FileMode)

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

MemoryMappedFile

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

Exceptions

ArgumentException

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.

ArgumentNullException

path is null.

IOException

mode is Create, CreateNew, or Truncate.

-or-

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

-or-

An I/O error occurred.

PathTooLongException

path exceeds the maximum length defined by the operating system.

SecurityException

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

• Memory-Mapped Files

CreateFromFile(String, FileMode, String)

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);

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

MemoryMappedFile

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

Exceptions

ArgumentException

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.

ArgumentNullException

path is null.

IOException

mode is Create, CreateNew, or Truncate.

-or-

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

-or-

An I/O error occurred.

PathTooLongException

path exceeds the maximum length defined by the operating system.

SecurityException

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.

CreateFromFile(String, FileMode, String, Int64)

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);

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

MemoryMappedFile

A memory-mapped file that has the specified characteristics.

Exceptions

ArgumentException

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.

ArgumentNullException

path is null.

ArgumentOutOfRangeException

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.

IOException

An I/O error occurred.

PathTooLongException

path exceeds the maximum length defined by the operating system.

SecurityException

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.

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

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);

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

MemoryMappedFile

A memory-mapped file that has the specified characteristics.

Exceptions

ArgumentException

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.

ArgumentNullException

path is null.

ArgumentOutOfRangeException

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.

IOException

-or-

An I/O error occurred.

PathTooLongException

path exceeds the maximum length defined by the operating system.

SecurityException

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

• Memory-Mapped Files

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

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

MemoryMappedFile

A memory-mapped file that has the specified characteristics.

Exceptions

ArgumentException

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.

ArgumentNullException

fileHandle is null.

ArgumentOutOfRangeException

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.

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

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);

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

MemoryMappedFile

A memory-mapped file that has the specified characteristics.

Exceptions

ArgumentException

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.

ArgumentNullException

fileStream is null.

ArgumentOutOfRangeException

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.