Memory Safety, or Why mmap Is Unsafe

April 28, 2025 :: 3913 words

I’ve recently been diving into unsafe rust, and I’ve been fascinated with how things interact. One of the most interesting aspects, to me, are memory safety, and ownership.

Now, I’m going to make a major disclaimer here: I am by no means an expert in Rust, or memory safety, or even low-level programming. While I have been writing Rust for a while, I haven’t delved into the unsafety aspects of the language. This post will be an attempt to explain why I haven’t.

The Star of the Show: mmap

Before I go too far into Rust and memory unsafety, I first want to talk about the use of the mmap(2) syscall. I’m going to copy the signature verbatum, and describe some of its uses, before we move forward. In case you’re alaready familiar with mmap, feel free to skip ahead.

mmap(2) (and its corresponding munmap(2) syscall) are used to map a file or device into memory.

void *mmap(void *addr, size_t length, int prot, int flags, int fd, off_t offset);
int munmap(void *addr, size_t length);

At its core, mmap maps the file described by fd from the offset in offset at the address addr, valid for length bytes. This allows us to read from and write to the file described by fd as-if it were just in memory. (The file descriptor can be freely closed after the mapping is created.) If addr is null, the kernel will choose an address for us (and return it). If it errors, it’ll return a special value (not NULL), and set errno.

The mmap call supports many flags in flags, but there are three that we’re really interested in:

MAP_SHARED/MAP_SHARED_VALIDATE: These flags allow us to share the mapped memory with other processes. MAP_SHARED allows us to share the memory with other processes, while MAP_SHARED_VALIDATE validates all of the other flags that we pass. (MAP_SHARED just ignores invalid flags.)
MAP_PRIVATE: This flag creates “a private copy-on-write mapping.” Updates to the mapping do not carry over to the file, or to other processes; they are private to the process. However, according to the manual, “it is unspecified whether changes made to the file after the mmap() call are visible in the mapped region.
MAP_ANON/MAP_ANONYMOUS: The mapping is not backed by any file. fd is ignored, but for compatibility reasons, it’s suggested to pass -1. (The offset argument should also be set to 0.)

Creating an Anonymous Private Mapping

We’ll start in C, so that we can translate it over to Rust later. For this example, we’ll create an anonymous private mapping. This is useful for allocating memory - we create a request to the operating system for a chunk of memory that we can use for our own purposes. Many allocators (e.g., malloc) sometimes use mmap to allocate memory. I will gloss over the details of pages for this post, since we don’t need to know what they are for now.

For this example, we’ll create a buffer of 32 bytes, and write the "foo" string to it, before printing. This is a very simple example, but it’s just a way to demonstrate how mmap works. Behold!

#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
int main() {
  void *addr = mmap(NULL, 32, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANON, -1, 0); // (1)
  if (addr == MAP_FAILED) { // (2)
    perror("mmap");
    exit(EXIT_FAILURE);
  char *bytes = addr;
  bytes[0] = 'f';
  bytes[1] = 'o';
  bytes[2] = 'o';
  bytes[3] = '\0';
  printf("%s\n", bytes); // (3)
  if (munmap(addr, 32) == -1) { // (4)
    perror("munmap");
    exit(EXIT_FAILURE);
  return 0;

First, for (1), we create the mmap mapping; since we do not care where the allocation is in our address space is¹, we’ll let the system choose the address for us by passing NULL as the first parameter - and it’ll return where it is allocated to us. Since we want to be able to read and write to the memory, we pass PROT_READ | PROT_WRITE as the second parameter. And since this is a private allocation with no backing file, we’ll pass MAP_ANON as the fourth parameter with MAP_PRIVATE to make it private. With no backing file, we’ll pass -1 as the fifth parameter and 0 as the sixth parameter.

If the allocation failed for some reason, in (2), mmap will have returned MAP_FAILED². If this happens, we should handle the error by printing an error message and exiting the program. (Note that perror checks the value of errno and prints a message based on the value of errno.)

We’ll then put the string in the buffer - individually assigning the characters to not overcomplicate things - and use printf to print the string.

Finally, we unmap the memory. After that point, any memory accesses to the mapped region will be invalid and result in undefined behavior. Fun!

$ cc -Wall -Wextra private.c -o private
$ ./private

And it works as expected!

Creating a Shared Mapping for a File

Now, we’re going to use mmap to create a shared mapping for a file. This is a bit more involved, but it’s the same basic concept:

#define _GNU_SOURCE
#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/mman.h>
#include <fcntl.h>
#include <sys/stat.h>
int main() {
  int fd = open("example.txt", O_RDWR | O_CREAT, 0644); // (1)
  if(fd == -1) {
    perror("open");
    exit(EXIT_FAILURE);
  if(fallocate(fd, 0, 0, 4) == -1) { // (2)
    perror("fallocate");
    exit(EXIT_FAILURE);
  struct stat st;
  if(fstat(fd, &st) == -1) {
    perror("fstat");
    exit(EXIT_FAILURE);
  void *addr = mmap(NULL, st.st_size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); // (3)
  if (addr == MAP_FAILED) {
    perror("mmap");
    exit(EXIT_FAILURE);
  char *bytes = addr;
  bytes[0] = 'f';
  bytes[1] = 'o';
  bytes[2] = 'o';
  bytes[3] = '\0';
  printf("%s\n", bytes);
  if (munmap(addr, 32) == -1) {
    perror("munmap");
    exit(EXIT_FAILURE);
  return 0;

It’s very similar to what we were previously doing, but there’s a few changes:

We’re now opening the file. We need to ensure that the file exists; so if it doesn’t, we’ll need to create it.
However, if we just created the file, the file may be empty; in order to write 4 bytes to it, we need to ensure that the file is at least 4 bytes long; this call to fallocate ensures that. If the file is longer, this call does nothing. If we don’t do this, one of two things happen:
- If the file has nothing in it, i.e., is size 0, the call to mmap will fail with EINVAL. (Since Linux 2.6.12, the manual says. Neat!)
- If the file has not enough space in it, we’ll get undefined behavior when we try to write past the end of the file³.
Then, we perform the mmap. We’ll map the entire file, from start to end, into memory; as a shared mapping. If we do not use MAP_SHARED here, any modifications we make to the mapped memory will not be reflected in the file.

At the end, this is what we get:

$ cc shared.c -o shared
$ ./shared
$ hexdump -C example.txt

Cool. Now we’ve got a solid idea of what we’re working with.

Let’s Try This in Rust

Let’s try to bring this over to Rust. There already exists multiple crates to handle interacting with mmap, but we won’t use it here yet because it’s spoilers.

We’ll use libc. libc contains libc::mmap (and libc::mmap64, for 64-bit file offsets, which we don’t need right now). Let’s take a look at the signature for libc::mmap:

pub unsafe extern "C" fn mmap(
    addr: *mut c_void,
    len: size_t,
    prot: c_int,
    flags: c_int,
    fd: c_int,
    offset: off_t,
) -> *mut c_void;

This makes sense; all of these match the arguments we need to pass to mmap, and they all have the same types as the corresponding arguments in the C function.

We’ll create a very small wrapper around it to handle the error checking and returning a Result:

#![allow(unsafe_code)]
use libc::{c_int, c_void, off_t, size_t};
use std::ptr::NonNull;
pub unsafe fn mmap(
    addr: *mut c_void,
    len: size_t,
    prot: c_int,
    flags: c_int,
    fd: c_int,
    offset: off_t,
) -> Result<NonNull<c_void>, std::io::Error> {
    let addr = libc::mmap(addr, len, prot, flags, fd, offset);
    if addr == libc::MAP_FAILED {
        Err(std::io::Error::last_os_error())
    } else {
        Ok(NonNull::new_unchecked(addr))
pub unsafe fn munmap(addr: NonNull<c_void>, len: size_t) -> Result<(), std::io::Error> {
    let result = libc::munmap(addr.as_ptr(), len);
    if result == -1 {
        Err(std::io::Error::last_os_error())
    } else {
        Ok(())

io::Error::last_os_error() reads the last value of errno and creates a new io::Error from it, which is perfect for our needs. However, we are always going to be passing in std::ptr::null() as the first argument to mmap; doing anything else would complicate things.

Anonymous Private Mapping in Rust

Let’s keep things simple and just… copy over what we did for the first anonymous private mapping example:

use std::ffi::CStr;
#[allow(unsafe_code)]
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let map = unsafe { // (1)
        self::sys::mmap(
            std::ptr::null_mut(),
            libc::PROT_READ | libc::PROT_WRITE,
            libc::MAP_ANON | libc::MAP_PRIVATE,
        let bytes_ptr = map.as_ptr().cast::<u8>(); // (2)
        let slice_ptr = std::ptr::slice_from_raw_parts_mut(bytes_ptr, 32); // (3)
        let slice = unsafe { &mut *slice_ptr };
        slice[0..4].copy_from_slice(b"foo\0"); // (4)
        let string = CStr::from_bytes_until_nul(&slice[..])?.to_str()?; // (5)
        println!("{string}");
    unsafe { self::sys::munmap(map, 32) }?; // (6)
    Ok(())

This… is already intimidating. But we’ll step through it.

One of the things that I like to do is document everything - for every use of unsafe - what makes it unsafe, and why we can use it safely. Let’s start from the top.

At (1), we’re calling mmap. We haven’t yet introduced references, so we don’t have to worry about any invariants with those. Holding pointers isn’t unsafe; calling std::ptr::null() isn’t unsafe, as long as we don’t dereference it. We know that when mmap returns successfully, it returns a an allocation, starting at the address returned, and continuing for the specified length in bytes. mmap cannot return a NULL pointer, and the API we wrote captures that; the pointer uses std::ptr::NonNull (which is a fancy *mut T with features). However, for reasons we’ll get into later, we do need the allocation to be both readable and writable⁴.

Surprisingly, the cast at (2) can be dangerous! The return result of mmap returns *mut c_void, so we need to cast that into something to be useable. Here, we’re just casting it into u8. This isn’t marked as unsafe because we’re not yet dereferencing it - it would be unsafe if this were to dereference the pointer. Consider instead if we were to cast it into a bool, for example. bool only has two valid bit patterns - it is “undefined behavior for an object with the boolean type to have any other bit pattern.” However, we don’t have any guarantee what the underlying value would be⁵! If we cast it into a bool and then try to read the first one, that could potentially be undefined behavior - unsafe!

Another thing to be concerned about here is alignment. Certain types have alignment requirements, where the address of the values of the types needs to be a multiple of the alignment. For example, u64 requires an alignment of 8 bytes, meaning that the address of a u64 must be a multiple of 8. In our case, mmap returns a page-aligned address, which means that the address is a multiple of the page size (typically 4096 bytes).

Finally, this is where the magic happens. At (3), we convert the raw pointer into a pointer to a slice. Recall that in Rust, a a pointer to a slice is actually a fat pointer, which contains both the pointer to the data, and the length of pointed-to data. Casting our pointer into a slice pointer is not unsafe - it’s not unsafe yet because we haven’t done anything with it yet!

It becomes unsafe the moment we convert our pointer to a reference, as we now have to abide by the rules of references. Let’s go through a few of them, and keep in mind this is by no means an exhaustive list:

It must be aligned. u8 has an alignment of 1 byte, so it is always aligned; even still, mmap returns a page-aligned address, which means that any value that has an alignment smaller than a page size is guaranteed to be aligned.
It must be non-null. We know this to be true, because mmap does not return null pointers.
It must be dereferencable for the type it points to. The documentation states that if size_of_val(t) > 0, then t must be dereferencable for size_of_val(t) bytes. Here, size_of_val(t) would correspond to the number of elements in the slice, times the size of the element in the slice; len * size_of::<u8>(). Since the allocation was 32 bytes, and size_of::<u8>() == 1, and len is 32, the slice is dereferencable for 32 bytes, satisfying this constraint.
The pointer must point to a valid value of the type it points to. In our case, the pointer points to a u8, so it must point to a valid u8. Thankfully, for u8, there are no invalid bit patterns, so this constraint is satisfied.
Aliasing. Rust has aliasing rules; while a &mut reference exists, no other reference to that data can exist; and while a & reference exists, no other mutable reference to that data can exist. Here, we’re creating the first (mutable) reference to the data; we had not created any other references to that data.
Lifetimes. Rust has rules around lifetimes, but since we’re freely casting into a reference, we have to constrain the lifetime. The reference cannot outlive the allocation. In this case, the reference to map cannot live past point (6), when the allocation is de-allocated. We’ve ensured that by enclosing the reference in a scope that ends before point (6).

That covers our bases! It should be safe to cast this pointer to a reference. We’ll then copy the data into that slice at (4), then at (5) we’ll convert our “C-string” (nul-terminated) to a &str. While we could unsafely cast the pointer to a &str, we’ll instead use the CStr type from the standard library to safely convert the pointer to a &str.

Ok, so far, so good.

Shared File Mapping in Rust

Since the anonymous, private mapping went so well, this should be easy, right? Unfortunately, Rust doesn’t natively have a way to call fallocate, nor to determine the size of the file (apart from seeking to the end of the file and asking for your current position), so we’ll add those to the sys module:

// ...previous functions
use std::os::fd::AsRawFd;
pub fn fstat<F: AsRawFd>(file: F) -> Result<libc::stat, std::io::Error> {
    let mut buf = std::mem::MaybeUninit::zeroed();
    let result = unsafe {
        libc::fstat(file.as_raw_fd(), buf.as_mut_ptr())
    if result == -1 {
        Err(std::io::Error::last_os_error())
    } else {
        Ok(unsafe { buf.assume_init() })
pub fn fallocate<F: AsRawFd>(
    file: F,
    mode: c_int,
    offset: off_t,
    len: off_t,
) -> Result<(), std::io::Error> {
    let result = unsafe {
        libc::fallocate(file.as_raw_fd(), mode, offset, len)
    if result == -1 {
        Err(std::io::Error::last_os_error())
    } else {
        Ok(())

Annoying, but there are crates out there that do this sort of thing for us; we’re avoiding them for the time being.

Now onto the actual display:

use std::ffi::CStr;
use std::os::fd::AsRawFd as _;
#[allow(unsafe_code)]
fn main() -> Result<(), Box<dyn std::error::Error>> {
    let file = std::fs::OpenOptions::new()
        .read(true)
        .write(true)
        .create(true)
        .truncate(true)
        .open("example.txt")?; // (1)
    self::sys::fallocate(file.as_raw_fd(), 0, 0, 32)?; // (2)
    let stat = self::sys::fstat(file.as_raw_fd())?; // (3)
    let map = unsafe {
        // (4)
        self::sys::mmap(
            std::ptr::null_mut(),
            usize::try_from(stat.st_size)?,
            libc::PROT_READ | libc::PROT_WRITE,
            libc::MAP_SHARED,
            file.as_raw_fd(),
        let bytes_ptr = map.as_ptr().cast::<u8>();
        let slice_ptr = std::ptr::slice_from_raw_parts_mut(bytes_ptr, 32);
        let slice = unsafe { &mut *slice_ptr }; // (5)
        slice[0..4].copy_from_slice(b"foo\0");
        let string = CStr::from_bytes_until_nul(&slice[..])?.to_str()?;
        println!("{string}");
    unsafe { self::sys::munmap(map, 32) }?; // (6)
    Ok(())

This is very similar to the previous instance. We open the file at (1), fallocate on (2), load the file size at (3), mmap at (4), mutate at (5), and unmap at (6).

However, this version holds a critical safety issue that the previous variant didn’t. Can you spot it?

The issue in this version is libc::MAP_SHARED. If we read the documentation for MAP_SHARED again:

Share this mapping. Updates to the mapping are visible to other processes mapping the same region, and (in the case of file-backed mappings) are carried through to the underlying file.

In other words, if process A updates their mapping of the file, it should be visible to process B. Or in other words, process A is able to mutate an object in process B’s memory.

Conceptually, we can think of this as the kernel holding a mutable reference to the memory returned by mmap⁶. While the kernel holds a mutable reference, we cannot create any sort of reference to any part of the memory region[^atomic-memory] - which leaves us with no way to read/write to that memory region in safe Rust!

It’s not just MAP_SHARED, either; if you don’t use MAP_ANONYMOUS, and another process uses the same memory region as your process, it leads to the same problem.

It’s a non-starter.

What Now

Unfortunately, there’s not much of a way around it. If you add invariants around how the file is accessed - use OS abstractions to prevent concurrent fil access, and file permissions, etc. - you can try to convince yourself that it will be fine. But Linux doesn’t have mandatory file locking, and many different concurrency issues could make it easy to trip yourself up. It’s possible to use it as a interprocess communication mechanism, but there are plenty of other forms of interprocess communication that don’t involve so many footguns (UNIX sockets, named/unnamed pipes, TCP/IP sockets)…

Plus, using mmap to map files into memory hides errors that occur when reading or writing to the file - and with very little guarantee that what you’re writing will make it to disk⁷!

Maybe next time I’ll write about fsync…

You probably shouldn’t be messing with this unless you know what you’re doing. While the first parameter does allow you to specify where you want the mapping to be, it’s generally better to let the system choose the address for you - lest you accidentally clobber something else in your address space. And there’s no real good way to determine where everything is in your address space in a way that prevents race conditions. ↩
Note that mmap doesn’t have to fail only because the OS ran out of memory - it’s entirely possible that even when mmap returns, the OS hasn’t even actually allocated the memory yet. (And when you first access the map, it may trigger an OOM error.) It can fail because too much memory has been mmaped, or you passed invalid data (I love the man docs on this - it says it can return EINVAL if “we don’t like addr, length, or offset”). ↩
While this is undefined behavior, it may not actually cause a SEGFAULT or SEGBUS. The manual states that it would SEGBUS if we attempt to access a page of the buffer that lies outside of the end of the file, but since our file is so small, it fits in one page. In the Notes section, it specifically states “the remaining bytes in the partial page at the end of the mapping are zeroed when mapped, and modifications to that region are not written out to the file.” ↩
Something that I haven’t been able to determine is whether or not it does actually need to be writable to construct a &mut reference to it; i.e., whether or not PROT_WRITE is required to hold a &mut reference to it. I suspect, given the declared safety constraints, that it is not actually required - &mut requires that (a) it is dereferencable, and (b) no other mutable reference to the allocation exists. Since, with PROT_READ, we can read from the &mut, I could see the argument that (a) is satisfied, even if you can’t write to it. This ties back into the idea that &mut is really just a way to express an exclusive hold on the memory region, rather than actually mutating the memory region. But since nothing I’ve read clearly indicated it, I’ll refrain from making the assumption. ↩
Ok, technically, mmap by default clears uninitialized pages - according to the man page, Linux 2.6.33 added the MAP_UNINITIALIZED flag, which causes mmap to not clear the page. This is only respected if the Linux kernel is configured to allow it. Let’s say someone mmaps a random anonymous page, and the kernel sets up a region of RAM to back that page. If the kernel did not clear the page, then the process could read whatever was left in that region - even if that region had previously held secrets that shouldn’t be shared! Thus, the kernel is often configured not to allow it. The manual doesn’t specify what “clearing” means, so it could just mean setting the bytes to an arbitrary value - but most likely it just means setting all of the bytes to null bytes. …which would be a valid bit pattern for a Rust bool. Lucky! ↩
This… is a little more unclear. The mmap crate, archived in 2022, bypasses this issue by washing its hands of it; it returns a raw pointer for you to deal with. memmap/memmap2 makes creating a file-backed memory map unsafe, but doesn’t say what about it is unsafe. rustix gives you a raw pointer. However, it is a fact that the contents of the memory region can change due to out-of-process (or even in-process) memory accesses, as enabled by the kernel. Assumptions that the memory can’t change if we don’t change it aren’t valid. read_volatile/write_volatile may help (volatile prevents the compiler from optimizing access to memory, especially since the “memory” can change from under us), but it won’t help prevent read/write tears when another process (or our process) changes the region in the file while we’re reading/writing to it. (Unless, of course, you’re doing an atomic read/write). Regardless, it’s unsafe. [^atomic-memory]: Again, this may be fine for certain types - for example, if your target platform guarantees atomic read/writes, then you could cast the pointer to e.g. &[AtomicU8], and load each byte atomically… this can be used to communicate across multiple threads using atomic load/store instructions, but those already have an expectation of interior mutability - which is the issue at hand. ↩
Unless you use msync(2), but again, this hides any number of I/O errors while trying to persist the changes to disk, and you’ll be none the wiser. ↩