Submitted by: bruce, davidg, dyson

add a BUG section for mmap with current limitation
section SYNOPSIS completed

lib/libc/sys/madvise.2

@@ -38,6 +38,8 @@
 .Nm madvise
 .Nd give advise about use of memory
 .Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/mman.h>
 .Fn madvise "caddr_t addr" "int len" "int behav"
 .Sh DESCRIPTION
 The

lib/libc/sys/mincore.2

@@ -38,6 +38,8 @@
 .Nm mincore
 .Nd get advise about use of memory
 .Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/mman.h>
 .Fn mincore "caddr_t addr" "int len" "char *vec"
 .Sh DESCRIPTION
 The

lib/libc/sys/mmap.2

@@ -207,4 +207,22 @@ was specified and insufficient memory was available.
 .Xr munmap 2 ,
 .Xr mprotect 2 ,
 .Xr madvise 2 ,
-.Xr mincore 2
+.Xr mincore 2 ,
+.Xr mlock 2 ,
+.Xr munlock 2
+
+.Sh BUGS
+.Ar len
+is limit to 2GB.  Mmapping slightly more than 2GB doesn't work, but
+mapping a window of size (filesize % 2GB) for file sizes of slightly
+less than 2G, 4GB, 6GB and 8GB.
+
+The limit is imposed for a variety of reasons. Most of them have to do
+with FreeBSD not wanting to use 64 bit offsets in the VM system due to
+the extreme performance penalty. So FreeBSD use 32bit page indexes and
+this gives FreeBSD a maximum of 8TB filesizes. It's actually bugs in
+the filesystem code that causes the limit to be further restricted to
+1TB (loss of precision when doing blockno calculations).
+
+Another reason for the 2GB limit is that filesystem metadata can
+reside at negative offsets.

lib/libc/sys/mprotect.2

@@ -38,6 +38,8 @@
 .Nm mprotect
 .Nd control the protection of pages
 .Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/mman.h>
 .Fn mprotect "caddr_t addr" "int len" "int prot"
 .Sh DESCRIPTION
 The

lib/libc/sys/msync.2

@@ -38,6 +38,8 @@
 .Nm msync
 .Nd synchronize a mapped region
 .Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/mman.h>
 .Fn msync "caddr_t addr" "int len" "int flags"
 .Sh DESCRIPTION
 The

lib/libc/sys/munmap.2

@@ -38,6 +38,8 @@
 .Nm munmap
 .Nd remove a mapping
 .Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/mman.h>
 .Fn munmap "caddr_t addr" "size_t len"
 .Sh DESCRIPTION
 The