- * (see {!Unix.openfile}). One or more objects can then be
- * shared in this file using {!Unix.share}.
+ * (for example you could create this using {!Unix.openfile} and
+ * passing the flags [O_RDWR], [O_TRUNC], [O_CREAT]).
+ * One or more objects can then be shared in this file
+ * using {!Unix.share}.
+ *
+ * For new files, [baseaddr] specifies the virtual address to
+ * map the file. Specifying [Nativeint.zero] ([0n]) here lets [mmap(2)]
+ * choose this, but on some platforms (notably Linux/AMD64)
+ * [mmap] chooses very unwisely, tending to map the memory
+ * just before [libc] with hardly any headroom to grow. If
+ * you encounter this sort of problem (usually a segfault or
+ * illegal instruction inside libc), then look at [/proc/PID/maps]
+ * and choose a more suitable address.
+ *
+ * If the file was created previously, then the [baseaddr] is
+ * ignored. The underlying [mmalloc] library will map the
+ * file in at the same place as before.