Mapping Example

Let’s consider a simple example program that uses mmap() to print a file chosen by the user to standard out:

  #include <stdio.h>
  #include <sys/types.h>
  #include <sys/stat.h>
  #include <fcntl.h>
  #include <unistd.h>
  #include <sys/mman.h>

  int main (int argc, char *argv[])
  {
          struct stat sb;
          off_t len;
          char *p;
          int fd;

          if (argc < 2) {
                  fprintf (stderr, "usage:
%s <file>\n", argv[0]);
                  return 1;
          }

          fd = open (argv[1], O_RDONLY);
          if (fd == -1) {
                  perror ("open");
                  return 1;
          }

          if (fstat (fd, &sb) == -1) {
                  perror ("fstat");
                  return 1;
          }

          if (!S_ISREG (sb.st_mode)) {
                  fprintf (stderr, "%s is not a file\n", argv[1]);
                  return 1;
          }

          p = mmap (0, sb.st_size, PROT_READ, MAP_SHARED, fd, 0);
          if (p == MAP_FAILED) {
                  perror ("mmap");
                  return 1;
          }

          if (close (fd) == -1) {
                  perror ("close");
                  return 1;
          }

          for (len = 0; len < sb.st_size; len++)
                  putchar (p[len]);

          if (munmap (p, sb.st_size) == -1) {
                  perror ("munmap");
                  return 1;
          }

          return 0;
  }

The only unfamiliar system call in this example should be fstat() , which we will cover in Chapter 7. All you need to know at this point is that fstat() returns infor mation about a given file. The S_ISREG() macro can check some of this information, so that we can ensure that the given file is a regular file (as opposed to a device file or a directory) before we map it. The behavior of nonregular files when mapped depends on the backing device. Some device files are mmap-able; other nonregular files are not mmap-able, and will set errno to EACCESS .

The rest of the example should be straightforward. The program is passed a filename as an argument. It opens the file, ensures it is a regular file, maps it, closes it, prints the file byte-by-byte to standard out, and then unmaps the file from memory.

Advantages of mmap()

Manipulating files via mmap() has a handful of advantages over the standard read() and write() system calls. Among them are:

1. Reading from and writing to a memory-mapped file avoids the extraneous copy that occurs when using the read() or write() system calls, where the data must be copied to and from a user-space buffer.
   
2. Aside from any potential page faults, reading from and writing to a memory-mapped file does not incur any system call or context switch overhead. It is as simple as accessing memory.
   
3. When multiple processes map the same object into memory, the data is shared among all the processes. Read-only and shared writable mappings are shared in their entirety; private writable mappings have their not-yet-COW (copy-on-write) pages shared.
   
4. Seeking around the mapping involves trivial pointer manipulations. There is no need for the lseek() system call.

For these reasons, mmap() is a smart choice for many applications.

Disadvantages of mmap()

There are a few points to keep in mind when using mmap():

1. Memory mappings are always an integer number of pages in size. Thus, the difference between the size of the backing file and an integer number of pages is “wasted” as slack space. For small files, a significant percentage of the mapping may be wasted. For example, with 4 KB pages, a 7 byte mapping wastes 4,089 bytes.
   
2. The memory mappings must fit into the process’ address space. With a 32-bit address space, a very large number of various-sized mappings can result in fragmentation of the address space, making it hard to find large free contiguous regions. This problem, of course, is much less apparent with a 64-bit address space.
   
3. There is overhead in creating and maintaining the memory mappings and associated data structures inside the kernel. This overhead is generally obviated by the elimination of the double copy mentioned in the previous section, particularly for larger and frequently accessed files.

For these reasons, the benefits of mmap() are most greatly realized when the mapped file is large (and thus any wasted space is a small percentage of the total mapping), or when the total size of the mapped file is evenly divisible by the page size (and thus there is no wasted space).