@@ -36,6 +36,7 @@
  .\" Modified 2006-12-04, mtk, various parts rewritten
  .\" 2007-07-10, mtk, Added an example program.
  .\" 2008-11-18, mtk, document MAP_STACK
+.\" 2019-11-25, Terence Kelly <tpkelly@eecs.umich.edu>, Added new example

@@ -900,7 +901,7 @@
  .BR tmpfs (5)
  (for example, when using the POSIX shared memory interface documented in
  .BR shm_overview (7)).
-.SH EXAMPLE
+.SH EXAMPLES
  .\" FIXME . Add an example here that uses an anonymous shared region for
  .\" IPC between parent and child.
  .PP

@@ -985,6 +986,100 @@
      exit(EXIT_SUCCESS);
  }
  .EE
+.PP
+The following program maintains within a memory-mapped file a
+.I persistent data structure
+that outlives invocations of the program.  Compile the program to
+.B a.out
+and use the
+.B truncate
+shell utility to create a sparse file named "pstack" that the program
+will populate with a persistent stack-of-integers data structure.
+Invoke the program with two kinds of command-line arguments:
+integers, which are pushed onto the persistent stack, and the string
+"pop," which causes the top integer on the stack to be printed and
+removed.  In the sample shell session below, note that values pushed
+onto the stack by the first invocation of the program persist beyond
+program exit; the second invocation of the program pops these values.
+.PP
+.in +4n
+.EX
+.B $ truncate -s `getconf PAGESIZE` pstack
+.B $ ./a.out 1 2 3
+.B $ ./a.out pop pop pop pop
+3
+2
+1
+<stack empty>
+.EE
+.in
+.SS Program source
+.EX
+#include <fcntl.h>
+#include <inttypes.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+
+#define handle_error(msg) \\
+    do { perror(msg); exit(EXIT_FAILURE); } while (0)
+
+int
+main(int argc, char *argv[])
+{
+    int fd, a;
+    struct stat sb;
+    size_t len;
+    struct pstack {             /* persistent stack header */
+        int32_t n;              /* number of items in stack */
+        int32_t s[];            /* array containing stack */
+    } *p;                       /* ptr to mmap'd stack file */
+
+    fd = open("pstack", O_RDWR);
+    if (fd == \-1)
+        handle_error("open");
+
+    if (fstat(fd, &sb) != 0)    /* to obtain file size */
+        handle_error("fstat");
+
+    len = (size_t) sb.st_size;
+
+    p = (struct pstack *) mmap(NULL, len, PROT_READ | PROT_WRITE,
+                               MAP_SHARED, fd, 0);
+    if (p == MAP_FAILED)
+        handle_error("mmap");
+
+    for (a = 1; a < argc; a++) {
+        if (strcmp(argv[a], "pop") == 0) {
+            if (p->n <= 0) {
+                printf("<stack empty>\\n");
+                exit(EXIT_FAILURE);
+            } else {
+                printf("%" PRId32 "\\n", p->s[--p->n]);
+            }
+        } else {
+            if (sizeof *p + (size_t) p->n * sizeof p->n >= len) {
+                printf("<stack full>\\n");
+                exit(EXIT_FAILURE);
+            } else {
+                p->s[p->n++] = atoi(argv[a]);
+            }
+        }
+    }
+
+    if (close(fd) != 0)         /* implicit on exit() */
+        handle_error("close");
+
+    if (munmap(p, len) != 0)    /* implicit on exit() */
+        handle_error("munmap");
+
+    exit(EXIT_SUCCESS);
+}
+.EE
  .SH SEE ALSO
  .BR ftruncate (2),
  .BR getpagesize (2),

@@ -1010,6 +1105,13 @@
  .IR /proc/[pid]/smaps .
  .PP
  B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128\(en129 and 389\(en391.
+.PP
+T. Kelly, "Persistent Memory Programming on Conventional Hardware,"
+ACM
+.I
+Queue
+magazine, Vol. 17, No. 4, July/August 2019
+\%https://queue.acm.org/detail.cfm?id=3358957
  .\"
  .\" Repeat after me: private read-only mappings are 100% equivalent to
  .\" shared read-only mappings. No ifs, buts, or maybes. -- Linus