mmap(2) updated

Add that len=0 will yield failure with EINVAL.
While here, rephrase some of the text.
Get rid of MAP_SWAP: its future came and went but nothing came of it.

Lots of hackroom input; including feedback from jmc.

1 files changed, 72 insertions, 50 deletions

diff --git a/lib/libc/sys/mmap.2 b/lib/libc/sys/mmap.2
index 99d2bbfd6d4..c7c953e0ea8 100644
--- a/lib/libc/sys/mmap.2
+++ b/lib/libc/sys/mmap.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mmap.2,v 1.38 2011/04/11 17:46:19 tedu Exp $
+.\"	$OpenBSD: mmap.2,v 1.39 2012/04/12 12:53:27 ariane Exp $
 .\"	$NetBSD: mmap.2,v 1.5 1995/06/24 10:48:59 cgd Exp $
 .\"
 .\" Copyright (c) 1991, 1993
@@ -30,7 +30,7 @@
 .\"
 .\"	@(#)mmap.2	8.1 (Berkeley) 6/4/93
 .\"
-.Dd $Mdocdate: April 11 2011 $
+.Dd $Mdocdate: April 12 2012 $
 .Dt MMAP 2
 .Os
 .Sh NAME
@@ -44,33 +44,57 @@
 .Sh DESCRIPTION
 The
 .Nm mmap
-function causes the pages starting at
-.Fa addr
-and continuing for at most
-.Fa len
-bytes to be mapped from the object described by
+function causes the contents of
 .Fa fd ,
-starting at byte offset
-.Fa offset .
-If
-.Fa offset
-or
+starting at
+.Fa offset ,
+to be mapped in memory at the given
+.Fa addr .
+The mapping will extend at least
 .Fa len
-is not a multiple of the pagesize, the mapped region may extend past the
-specified range.
+bytes, subject to page alignment restrictions.
 .Pp
+The
+.Fa addr
+argument describes the address where the system should place the mapping.
+If the
+.Dv MAP_FIXED
+flag is specified, the allocation will happen at the specified address,
+replacing any previously established mappings in its range.
+Otherwise, the mapping will be placed at the available spot at
+.Fa addr ;
+failing that it will be placed "close by".
 If
 .Fa addr
-is non-zero, it is used as a hint to the system.
-(As a convenience to the system, the actual address of the region may differ
-from the address supplied.)
+is
+.Dv NULL
+the system can pick any address.
+Except for
+.Dv MAP_FIXED
+mappings, the system will never replace existing mappings.
+.Pp
+The
+.Fa len
+argument describes the minimum amount of bytes the mapping will span.
+Since
+.Nm
+maps pages into memory,
+.Fa len
+may be rounded up to hit a page boundary.
 If
+.Fa len
+is 0, the mapping will fail with
+.Dv EINVAL .
+.Pp
+If an
+.Fa fd
+and
+.Fa offset
+are specified, the resulting address may end up not on a page boundary,
+in order to align the page offset in the
 .Fa addr
-is zero, an address will be selected by the system.
-The actual starting address of the region is returned.
-A successful
-.Fa mmap
-deletes any previous mapping in the allocated address range.
+to the page offset in
+.Fa offset .
 .Pp
 The protections (region accessibility) are specified in the
 .Fa prot
@@ -106,16 +130,18 @@ region.
 Mapped from a regular file or character-special device memory.
 (This is the default mapping type, and need not be specified.)
 .It Dv MAP_FIXED
-Do not permit the system to select a different address than the one
-specified.
-If the specified address cannot be used,
-.Nm mmap
-will fail.
-If
-.Dv MAP_FIXED
-is specified,
-.Fa addr
-must be a multiple of the pagesize.
+Demand that the mapping is placed at
+.Fa addr ,
+rather than having the system select a location.
+.Fa addr ,
+.Fa len
+and
+.Fa offset
+(in the case of
+.Fa fd
+mappings)
+must be multiples of the page size.
+Existing mappings in the address range will be replaced.
 Use of this option is discouraged.
 .It Dv MAP_HASSEMAPHORE
 Notify the kernel that the region may contain semaphores and that special
@@ -130,13 +156,11 @@ Modifications are private.
 Modifications are shared.
 .It Dv MAP_TRYFIXED
 Attempt to use the hint provided by
-.Fa addr
-even if the kernel would normally prefer a different address, but do not
-fail if the address is not available.
-This option is provided for compatibility with other operating systems
-and its use in
-.Ox
-is discouraged.
+.Fa addr .
+This is the default mapping type and need not be specified.
+Use of
+.Dv MAP_TRYFIXED
+is discouraged, as it is a non-portable extension.
 .It Dv MAP_COPY
 Modifications are private and, unlike
 .Dv MAP_PRIVATE ,
@@ -151,14 +175,6 @@ The
 function does not unmap pages; see
 .Xr munmap 2
 for further information.
-.Pp
-The current design does not allow a process to specify the location of
-swap space.
-In the future we may define an additional mapping type,
-.Dv MAP_SWAP ,
-in which
-the file descriptor argument specifies a file or device to which swapping
-should be done.
 .Sh RETURN VALUES
 Upon successful completion,
 .Nm mmap
@@ -207,13 +223,19 @@ is not a valid open file descriptor.
 .Dv MAP_FIXED
 was specified and the
 .Fa addr
-parameter was not page aligned or
+parameter was not page aligned.
+.It Bq Er EINVAL
 .Fa addr
 and
-.Fa size
-specify a region that would extend beyond the end of the address space.
+.Fa len
+specified a region that would extend beyond the end of the address space.
+.It Bq Er EINVAL
 .Fa fd
 did not reference a regular or character special file.
+.It Bq Er EINVAL
+The allocation
+.Fa len
+was 0.
 .It Bq Er ENOMEM
 .Dv MAP_FIXED
 was specified and the