Part 2 of 7 · 2 min read
mmap
In plain words: Reading a book through a library window is one way to use it, and photocopying it page by page onto your desk is another. The call read is the photocopy: it copies bytes from the file into a buffer that the program owns. The call mmap is the window: it makes the file itself appear in the address space, and the program reads it with ordinary pointer operations. The analogy stops in one place: the window shows pages as they are asked for, and no copy is made until an access needs one.
The call takes six arguments, listed in the table below the example, and returns the address of the new mapping. A program that counts the lines of a file:
int fd = open(argv[1], O_RDONLY);
struct stat st;
fstat(fd, &st);
char *p = mmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
if (p == MAP_FAILED) { perror("mmap"); return 1; }
close(fd); /* the mapping stays valid */
long lines = 0;
for (off_t i = 0; i < st.st_size; i++) if (p[i] == '\n') lines++;
munmap(p, st.st_size);
On a file made by seq 1 100000, the program printed 100000 lines in 588895 bytes, the same as wc -lc. The parameters:
| Parameter | Meaning |
|---|---|
addr |
the wanted address, usually NULL so that the kernel chooses |
length |
the number of bytes to map |
prot |
the allowed use: PROT_READ, PROT_WRITE, PROT_EXEC, or a combination |
flags |
the kind of mapping (section 2) |
fd, offset |
the file and the position in it, where offset must be a multiple of the page size |
The call returns the constant MAP_FAILED on error, and the program must check it. The descriptor can be closed after the call, since the mapping holds its own reference to the file. The program also checks for an empty file, because mmap with length 0 fails. A map of an empty file is a common mistake.
Memory-mapped file
A memory-mapped file is a file whose contents are made part of a process's address space by mmap, so that the process reads and writes the file through memory accesses, and the kernel loads pages from the file when they are first touched.
Example: after mmap of nums.txt, the expression p[0] is the first byte of the file.
Read it as
mmap does not read the file. It only records that this range of addresses belongs to that file. The reading happens page by page, at the page faults.
Check yourself:
1. What does mmap return on failure?
2. Why can the descriptor be closed after the call?
3. When does the file's data really enter memory?