FileStreamOptions.PreallocationSize Property

Definition

Namespace:

System.IO

Assembly:

System.Runtime.dll

Source:

FileStreamOptions.cs

The initial allocation size in bytes for the file. A positive value is effective only when a regular file is being created or overwritten (Create or CreateNew). Negative values are not allowed. In other cases (including the default 0 value), it's ignored. This value is a hint and is not a strong guarantee. It is not supported on Web Assembly (WASM) and FreeBSD (the value is ignored). For Windows, Linux and macOS we will try to preallocate the disk space to fill the requested allocation size. If that turns out to be impossible, the operation is going to throw an exception. The final file length (EOF) will be determined by the number of bytes written to the file.

public:
 property long PreallocationSize { long get(); void set(long value); };

public long PreallocationSize { get; set; }

member this.PreallocationSize : int64 with get, set

Public Property PreallocationSize As Long

Property Value

Int64

A non-negative number that represents the initial allocation size in bytes for the file.

Exceptions

ArgumentOutOfRangeException

When value is negative.

Examples

The following code example demonstrates how to use PreallocationSize when working with FileStream objects:

using System.IO;

public static class PreallocationSizeExample
{
    public static void Main()
    {
        string destinationPath = "destination.dll";

        var openForReading = new FileStreamOptions { Mode = FileMode.Open };
        using var source = new FileStream(typeof(PreallocationSizeExample).Assembly.Location, openForReading);

        var createForWriting = new FileStreamOptions
        {
            Mode = FileMode.CreateNew,
            Access = FileAccess.Write,
            PreallocationSize = source.Length // specify size up-front
        };
        using var destination = new FileStream(destinationPath, createForWriting);

        source.CopyTo(destination); // copies the contents of the assembly file into the destination file
    }
}

Imports System.IO

Module PreallocationSizeExample

    Sub Main()

        Dim destinationPath As String = "destination.dll"
        Dim openForReading = New FileStreamOptions With {
            .Mode = FileMode.Open
        }

        Using source = New FileStream(GetType(PreallocationSizeExample).Assembly.Location, openForReading)

            Dim createForWriting = New FileStreamOptions With {
                .Mode = FileMode.CreateNew,
                .Access = FileAccess.Write,
                .PreallocationSize = source.Length ' specify size up-front
            }

            Using destination = New FileStream(destinationPath, createForWriting)
                source.CopyTo(destination) ' copies the contents of the assembly file into the destination file
            End Using

        End Using

    End Sub

End Module

Remarks

PreallocationSize can only be requested for write mode (Access must be set to Write) and when creating new files (Mode must be set to either Create or to CreateNew). Otherwise, the FileStream constructor will throw an exception.

If the operating system, platform or file system does not support preallocation, then PreallocationSize is ignored. This is the case for Web Assembly (WASM) and FreeBSD.

If there is not enough disk space or the file system does not support files of given size (example: 5 GB file on FAT32), an exception is thrown.

The file length is determined by how many bytes were written to the file.

When the file is closed and not all of the allocated space is written to, what happens to the remaining space is platform dependent. On Windows, this space is no longer reserved for the file. On other platforms, such as Linux and macOS, it remains allocated to the file.

For example, assume 2 GB is preallocated for a file, but only 1 GB is written. After closing the file, the file length is 1 GB on all operating systems. On Windows, the allocated size is also 1 GB, but on Linux and macOS, the allocated size is still 2 GB.

It's permissible to write more than what was initially preallocated. As long as there is enough disk space, the operation should succeed.