Marshalling

Marshalling is the conversion between a managed value and the bytes a native function expects. A blittable type, an int or a struct of int fields, is passed as it is; a string, a boolean and a reference need a copy and a convention. The Marshal class does the copy by hand when a program manages the memory itself.

A struct on the native heap

Marshal.SizeOf<T>() is the size of the native form, which is not the size of the managed struct. The program allocates a block, writes the struct into it, reads it back and frees the block:

using System.Runtime.InteropServices; Console.WriteLine($"point {Marshal.SizeOf<Point>()}"); Console.WriteLine($"int {Marshal.SizeOf<int>()}"); var point = new Point { X = 3, Y = 4 }; var handle = Marshal.AllocHGlobal(Marshal.SizeOf<Point>()); try { Marshal.StructureToPtr(point, handle, false); var back = Marshal.PtrToStructure<Point>(handle); Console.WriteLine($"back {back.X} {back.Y}"); } finally { Marshal.FreeHGlobal(handle); } [StructLayout(LayoutKind.Sequential)] struct Point { public int X; public int Y; }

dotnet run

point 8
int 4
back 3 4

Two integers, two times four bytes, and the copy returned the values. The try/finally is the rule of unmanaged memory: the block is not collected, so a path that misses FreeHGlobal leaks it. A struct with a reference field is not blittable, and SizeOf of it throws ArgumentException; a struct of primitives is blittable and costs no conversion at all in a P/Invoke call.

Strings across the boundary

A C function takes a pointer to bytes, and a .NET string is UTF-16 with a length. The program converts it to UTF-8 in unmanaged memory, passes the pointer to strlen, reads it back and frees it:

using System.Runtime.InteropServices; var text = Marshal.StringToCoTaskMemUTF8("café"); Console.WriteLine($"bytes {Libc.strlen(text)}"); Console.WriteLine($"back {Marshal.PtrToStringUTF8(text)}"); Marshal.FreeCoTaskMem(text); static class Libc { [DllImport("libc", EntryPoint = "strlen")] public static extern nuint strlen(IntPtr text); }

dotnet run

bytes 5
back café

Five bytes, because the accented letter takes two in UTF-8, and the text came back unchanged. The pair StringToCoTaskMemUTF8 and FreeCoTaskMem is the manual form; a string parameter of a DllImport method, as in the previous lesson, makes the runtime do the same copy and free around the call. A function that writes into the string needs a StringBuilder or a byte buffer instead: a string is immutable, so the runtime cannot hand its buffer to code that writes.

Layout and FieldOffset

LayoutKind.Sequential is the default and puts the fields in order; LayoutKind.Explicit puts each field at an offset the programmer chooses, and two fields may share one:

using System.Runtime.InteropServices; var overlay = new Overlay { Value = 0x01020304 }; Console.WriteLine($"first {overlay.First}"); Console.WriteLine($"value {overlay.Value}"); [StructLayout(LayoutKind.Explicit)] struct Overlay { [FieldOffset(0)] public int Value; [FieldOffset(0)] public byte First; }

dotnet run

first 4
value 16909060

The int 0x01020304 is 16 909 060 in decimal, and its first byte on a little-endian machine is 0x04, which is 4. The two fields alias the same four bytes, which is how a C union is written in C#. The order of the bytes is the order of the machine, so a struct with an explicit layout is a promise about the platform as well as about the C declaration.

The sizes of the primitives

The sizes of the managed types are not always the sizes the native side expects. bool is one byte in a managed array and four in the native default, char is two bytes of UTF-16 and one byte in the ANSI default of the marshal:

using System.Runtime.InteropServices; Console.WriteLine($"bool {Marshal.SizeOf<bool>()}"); Console.WriteLine($"char {Marshal.SizeOf<char>()}"); Console.WriteLine($"long {Marshal.SizeOf<long>()}"); Console.WriteLine($"overlay {Marshal.SizeOf<Overlay>()}"); [StructLayout(LayoutKind.Explicit)] struct Overlay { [FieldOffset(0)] public int Value; [FieldOffset(0)] public byte First; }

dotnet run

bool 4
char 1
long 8
overlay 4

The boolean is four bytes, which is the C BOOL of the Windows API and the int a C function returns; a native function that takes a stdbool needs [MarshalAs(UnmanagedType.I1)]. The char is one byte because the default charset is ANSI; a call that expects UTF-16 passes CharSet.Unicode and gets two. The long is eight on this platform, and the explicit struct stayed four, because two fields at offset zero do not add up.

Exercises

  1. Add a third field to Point and print the new size.
  2. Allocate a string of a hundred bytes with AllocHGlobal and write into it with Marshal.WriteByte.
  3. Make a struct of a bool and an int and read its size.
  4. Pass a char to a native function with CharSet.Unicode and compare the bytes with the ANSI call.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does Marshal.SizeOf<T>() report?

    Answer

    The size of the native form of T

    The native layout can differ from the managed one, which bool shows.

  2. What does this program print? using System.Runtime.InteropServices; Console.WriteLine(Marshal.SizeOf<int>());

    Answer

    4

    An int is four bytes on this platform, as the measured run showed.

  3. What does Marshal.StructureToPtr do?

    Answer

    Copies the fields of a struct into unmanaged memory

    PtrToStructure is the opposite direction, and the program used both.

  4. What does this program print? using System.Runtime.InteropServices; var point = new Point { X = 3, Y = 4 }; var handle = Marshal.AllocHGlobal(Marshal.SizeOf<Point>()); Marshal.StructureToPtr(point, handle, false); var back = Marshal.PtrToStructure<Point>(handle); Console.WriteLine(back.Y); [StructLayout(LayoutKind.Sequential)] struct Point { public int X; public int Y; }

    Answer

    4

    The Y field round-tripped through the native block.

  5. Why is a block from AllocHGlobal freed with FreeHGlobal?

    Answer

    It is unmanaged memory that the garbage collector does not own

    A missed free is a leak, which is why the program used try/finally.

  6. What does this program print? using System.Runtime.InteropServices; var text = Marshal.StringToCoTaskMemUTF8("café"); Console.WriteLine(Libc.strlen(text)); Marshal.FreeCoTaskMem(text); static class Libc { [DllImport("libc", EntryPoint = "strlen")] public static extern nuint strlen(IntPtr text); }

    Answer

    5

    The accented letter takes two bytes in UTF-8, so the string is five bytes.

  7. Why can a string not be passed to a native function that writes into it?

    Answer

    A string is immutable, so its buffer cannot be handed over

    A StringBuilder or a byte buffer is the mutable form for an output parameter.

  8. What does this program print? using System.Runtime.InteropServices; var overlay = new Overlay { Value = 0x01020304 }; Console.WriteLine(overlay.First); [StructLayout(LayoutKind.Explicit)] struct Overlay { [FieldOffset(0)] public int Value; [FieldOffset(0)] public byte First; }

    Answer

    4

    The first byte of 0x01020304 on a little-endian machine is 0x04.

  9. What does Marshal.SizeOf<bool>() give here?

    Answer

    4

    The measured value is the four-byte native BOOL, not the one-byte managed bool.

  10. What does LayoutKind.Explicit with two FieldOffset(0) fields create?

    Answer

    Two fields that share the same bytes, like a C union

    The measured struct read 4 through the byte and the whole int through the int.

The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev