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
- Add a third field to Point and print the new size.
- Allocate a string of a hundred bytes with AllocHGlobal and write into it with Marshal.WriteByte.
- Make a struct of a bool and an int and read its size.
- 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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
What does Marshal.SizeOf<bool>() give here?
Answer
4
The measured value is the four-byte native BOOL, not the one-byte managed bool.
-
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