Unsafe Class

Definition

Namespace:

System.Runtime.CompilerServices

Assembly:

System.Runtime.dll

Source:

Unsafe.cs

Contains generic, low-level functionality for manipulating managed and unmanaged pointers.

public ref class Unsafe abstract sealed

public static class Unsafe

type Unsafe = class

Public Class Unsafe

Inheritance

Object

Unsafe

Remarks

Warning

This type is intended for advanced pointer manipulation scenarios. Callers are assumed to be familiar with ECMA-335, Sec. II.14.4 and III.1.1.5, and with the ECMA-335 CLI Specification Addendum.

Most APIs on this type do not perform any argument checking or validation. Incorrect use of these APIs could corrupt process memory or destabilize the .NET runtime.

This type is typically used by low-level library authors who want to write high-performance code and are willing to suppress .NET's typical type safety checks to meet their performance goals.

Consider the following example, which reverses the elements within a Span<T>.

Note

These examples exist simply for demonstration purposes. In real-world applications, developers should instead use helper functions like Reverse, which are better optimized than even these examples.

// A safe, verifiable way to reverse a Span<T>.
static void Reverse<T>(Span<T> span)
{
  while (span.Length > 1)
  {
    T firstElement = span[0];
    T lastElement = span[^1];
    span[0] = lastElement;
    span[^1] = firstElement;
    span = span[1..^1];
  }
}

This method is fully type-safe and the .NET runtime may insert bounds checks to help enforce safety. However, low-level library authors may want to suppress .NET's normal safety checks in order to improve the performance of their own code. Such developers would typically rely on static analysis tools or their own code reviews to help enforce correctness. The Unsafe APIs allow a developer to rewrite this code using unverifiable constructs, as the following example shows.

// A correct but unverifiable way to reverse a Span<T>.
static void Reverse<T>(Span<T> span)
{
  if (span.Length > 1)
  {
    ref T refLeft = ref MemoryMarshal.GetReference(span);
    ref T refRight = ref Unsafe.Add(ref refLeft, span.Length - 1);
    do
    {
      T leftElement = refLeft;
      T rightElement = refRight;
      refLeft = rightElement;
      refRight = leftElement;
      refLeft = ref Unsafe.Add(ref refLeft, 1);
      refRight = ref Unsafe.Subtract(ref refRight, 1);
    } while (Unsafe.IsAddressLessThan(ref refLeft, ref refRight));
  }
}

Since the Unsafe APIs suppress typical type-safety validation, it is up to callers to ensure that the code they're writing is legal. Misuse of these APIs could cause access violations, create GC holes, produce incorrect codegen, or otherwise induce undefined and destabilizing behaviors within the .NET runtime.

Methods

Add<T>(T, Int32)	Adds an offset to the given managed pointer.
Add<T>(T, IntPtr)	Adds an element offset to the given managed pointer.
Add<T>(T, UIntPtr)	Adds an element offset to the given managed pointer.
Add<T>(Void*, Int32)	Adds an element offset to the given unmanaged pointer.
AddByteOffset<T>(T, IntPtr)	Adds a byte offset to the given managed pointer.
AddByteOffset<T>(T, UIntPtr)	Adds a byte offset to the given managed pointer.
AreSame<T>(T, T)	Determines whether the specified managed pointers point to the same location.
As<T>(Object)	Casts the given object to the specified type.
As<TFrom,TTo>(TFrom)	Reinterprets the given managed pointer as a new managed pointer to a value of type TTo.
AsPointer<T>(T)	Converts a managed pointer into an unmanaged pointer.
AsRef<T>(T)	Reinterprets the given read-only reference as a mutable reference.
AsRef<T>(Void*)	Converts an unmanaged pointer into a managed pointer to a value of type T.
BitCast<TFrom,TTo>(TFrom)	Reinterprets the given value of type TFrom as a value of type TTo.
ByteOffset<T>(T, T)	Determines the byte offset from origin to target from the given managed pointers.
Copy<T>(T, Void*)	Copies a value of type T to the given location.
Copy<T>(Void*, T)	Copies a value of type T to the given location.
CopyBlock(Byte, Byte, UInt32)	Copies bytes from the source address to the destination address.
CopyBlock(Void*, Void*, UInt32)	Copies bytes from the source address to the destination address.
CopyBlockUnaligned(Byte, Byte, UInt32)	Copies bytes from the source address to the destination address without assuming architecture dependent alignment of the addresses.
CopyBlockUnaligned(Void*, Void*, UInt32)	Copies bytes from the source address to the destination address without assuming architecture dependent alignment of the addresses.
InitBlock(Byte, Byte, UInt32)	Initializes a block of memory at the given location with a given initial value.
InitBlock(Void*, Byte, UInt32)	Initializes a block of memory at the given location with a given initial value.
InitBlockUnaligned(Byte, Byte, UInt32)	Initializes a block of memory at the given location with a given initial value without assuming architecture dependent alignment of the address.
InitBlockUnaligned(Void*, Byte, UInt32)	Initializes a block of memory at the given location with a given initial value without assuming architecture dependent alignment of the address.
IsAddressGreaterThan<T>(T, T)	Returns a value that indicates whether a specified managed pointer is greater than another specified managed pointer.
IsAddressLessThan<T>(T, T)	Returns a value that indicates whether a specified managed pointer is less than another specified managed pointer.
IsNullRef<T>(T)	Determines if a given managed pointer to a value of type T is a null reference.
NullRef<T>()	Returns a null managed pointer to a value of type T.
Read<T>(Void*)	Reads a value of type T from the given location.
ReadUnaligned<T>(Byte)	Reads a value of type T from the given address without assuming architecture dependent alignment of the source address.
ReadUnaligned<T>(Void*)	Reads a value of type T from the given location without assuming architecture dependent alignment of the source address.
SizeOf<T>()	Returns the size of a value of the given type parameter.
SkipInit<T>(T)	Bypasses definite assignment rules for a given reference.
Subtract<T>(T, Int32)	Subtracts an offset from the given managed pointer.
Subtract<T>(T, IntPtr)	Subtracts an element offset from the given managed pointer.
Subtract<T>(T, UIntPtr)	Subtracts an element offset from the given managed pointer.
Subtract<T>(Void*, Int32)	Subtracts an element offset from the given unmanaged pointer.
SubtractByteOffset<T>(T, IntPtr)	Subtracts a byte offset from the given managed pointer.
SubtractByteOffset<T>(T, UIntPtr)	Subtracts a byte offset from the given managed pointer.
Unbox<T>(Object)	Returns a mutable ref to a boxed value.
Write<T>(Void*, T)	Writes a value of type T to the given location.
WriteUnaligned<T>(Byte, T)	Writes a value of type T to the given location without assuming architecture dependent alignment of the destination address.
WriteUnaligned<T>(Void*, T)	Writes a value of type T to the given location without assuming architecture dependent alignment of the destination address.