MemoryMappedFile.CreateFromFile Method

Definition

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

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

public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (string path);
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. In Windows, paths must contain fewer than 248 characters, and file names must contain fewer than 260 characters.

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

CreateFromFile(String, FileMode)

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

public static System.IO.MemoryMappedFiles.MemoryMappedFile CreateFromFile (string path, System.IO.FileMode mode);
Parameters
path
String

The path to 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. In Windows, paths must contain fewer than 248 characters, and file names must contain fewer than 260 characters.

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)

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 (string path, System.IO.FileMode mode, string mapName);
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.

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 or mapName 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. In Windows, paths must contain fewer than 248 characters, and file names must contain fewer than 260 characters.

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)

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 (string path, System.IO.FileMode mode, string mapName, long capacity);
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.

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 or mapName 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. In Windows, paths must contain fewer than 248 characters, and file names must contain fewer than 260 characters.

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)

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 (string path, System.IO.FileMode mode, string mapName, long capacity, System.IO.MemoryMappedFiles.MemoryMappedFileAccess access);
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.

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.

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 or mapName 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. In Windows, paths must contain fewer than 248 characters, and file names must contain fewer than 260 characters.

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(FileStream, String, Int64, MemoryMappedFileAccess, HandleInheritability, Boolean)

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, string mapName, long capacity, System.IO.MemoryMappedFiles.MemoryMappedFileAccess access, System.IO.HandleInheritability inheritability, bool leaveOpen);
Parameters
fileStream
FileStream

The file stream of the existing file.

mapName
String

A name to assign to the memory-mapped file.

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.

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, string mapName, long capacity, System.IO.MemoryMappedFiles.MemoryMappedFileAccess access, System.IO.MemoryMappedFiles.MemoryMappedFileSecurity memoryMappedFileSecurity, System.IO.HandleInheritability inheritability, bool leaveOpen);
Parameters
fileStream
FileStream

The fileStream to the file to map.

mapName
String

A name to assign to the memory-mapped file.

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.

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 or mapname 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.