-.TH MMAP 2 ""
-.UC 7
-.SH NAME
-mmap \- map files or devices into memory
-.SH SYNOPSIS
-.nf
-.B caddr_t
-mmap(addr, len, prot, flags, fd, pos)
-.B caddr_t addr;
-.B int len, prot, flags, fd;
-.B off_t pos;
-.fi
-.SH DESCRIPTION
-.PP
-The \fImmap\fP system call
-causes the pages starting at \fIaddr\fP and continuing
-for at most \fIlen\fP bytes to be mapped from the object represented by
-descriptor \fIfd\fP, starting at byte offset \fIpos\fP.
-The starting address of the region is returned;
-for the convenience of the system,
-it may differ from that supplied
-unless the MAP_FIXED flag is given,
-in which case the exact address will be used or the call will fail.
-The \fIaddr\fP, \fIlen\fP, and \fIpos\fP parameters
-must all be multiples of the pagesize.
-A successful \fImmap\fP will delete any previous mapping
-in the allocated address range.
-.PP
-The system supports sharing of data between processes
-by allowing pages to be mapped into memory. These mapped
-pages may be \fIshared\fP with other processes or \fIprivate\fP
-to the process.
-Protection and sharing options are defined in \fI<sys/mman.h>\fP as:
-.DS
-.ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u
-/* protections are chosen from these bits, or-ed together */
-#define PROT_READ 0x04 /* pages can be read */
-#define PROT_WRITE 0x02 /* pages can be written */
-#define PROT_EXEC 0x01 /* pages can be executed */
-.DE
-.DS
-.ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u
-/* flags contain mapping type, sharing type and options */
-/* mapping type; choose one */
-#define MAP_FILE 0x0001 /* mapped from a file or device */
-#define MAP_ANON 0x0002 /* allocated from memory, swap space */
-#define MAP_TYPE 0x000f /* mask for type field */
-.DE
-.DS
-.ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u
-/* sharing types; choose one */
-#define MAP_SHARED 0x0010 /* share changes */
-#define MAP_PRIVATE 0x0000 /* changes are private */
-.DE
-.DS
-.ta \w'#define\ \ 'u +\w'MAP_HASSEMAPHORE\ \ 'u +\w'0x0080\ \ 'u
-/* other flags */
-#define MAP_FIXED 0x0020 /* map addr must be exactly as requested */
-#define MAP_INHERIT 0x0040 /* region is retained after exec */
-#define MAP_HASSEMAPHORE 0x0080 /* region may contain semaphores */
-.DE
-.PP
-The parameter \fIprot\fP specifies the accessibility
-of the mapped pages.
-The parameter \fIflags\fP specifies
-the type of object to be mapped,
-mapping options, and
-whether modifications made to
-this mapped copy of the page
-are to be kept \fIprivate\fP, or are to be \fIshared\fP with
-other references.
-Possible types include MAP_FILE,
-mapping a regular file or character-special device memory,
-and MAP_ANON, which maps memory not associated with any specific file.
-The file descriptor used for creating MAP_ANON regions is used only
-for naming, and may be given as \-1 if no name
-is associated with the region.\(dg
-.FS
-\(dg 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, MAP_SWAP,
-in which the file descriptor argument specifies a file
-or device to which swapping should be done.
-.FE
-The MAP_INHERIT flag allows a region to be inherited after an \fIexec\fP.
-The MAP_HASSEMAPHORE flag allows special handling for
-regions that may contain semaphores.
-.SH "SEE ALSO"
-msync.2, munmap.2, mprotect.2, madvise.2, mincore.2
+.Dd ""
+.Dt MMAP 2
+.Os BSD 4
+.Sh NAME
+.Nm mmap
+.Nd map files or devices into memory
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/mman.h>
+.Ft caddr_t
+.Fn mmap "caddr_t addr" "int len" "int prot" "int flags" "int fd" "off_t offset"
+.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
+.Fa fd ,
+starting at byte offset
+.Fa offset .
+If
+.Fa offset
+or
+.Fa len
+is not a multiple of the pagesize, the mapped region may extend past the
+specified range.
+.Pp
+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.)
+If
+.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.
+.Pp
+The protections (region accessibility) are specified in the
+.Fa prot
+argument by
+.Em or Ap ing
+the following values:
+.Pp
+.Bl -tag -width MAP_FIXEDX
+.It Dv PROT_EXEC
+Pages may be executed.
+.It Dv PROT_READ
+Pages may be read.
+.It Dv PROT_WRITE
+Pages may be written.
+.El
+.Pp
+The
+.Fa flags
+parameter specifies the type of the mapped object, mapping options and
+whether modifications made to the mapped copy of the page are private
+to the process or are to be shared with other references.
+Sharing, mapping type and options are specified in the
+.Fa flags
+argument by
+.Em or Ap ing
+the following values:
+.Pp
+.Bl -tag -width MAP_FIXEDX
+.It Dv MAP_ANON
+Map anonymous memory not associated with any specific file.
+The file descriptor used for creating MAP_ANON regions is used only for
+naming, and may be specified as \-1 if no name is associated with the
+region.
+.It Dv MAP_FILE
+Mapped from a regular file or character-special device memory.
+.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 MAP_FIXED is specified,
+.Fa addr
+must be a multiple of the pagesize.
+Use of this option is discouraged.
+.It Dv MAP_HASSEMAPHORE
+Notify the kernel that the region may contain semaphores and that special
+handling may be necessary.
+.It Dv MAP_INHERIT
+Permit regions to be inherited across
+.Xr exec 2
+system calls.
+.It Dv MAP_PRIVATE
+Modifications are private.
+.It Dv MAP_SHARED
+Modifications are shared.
+.El
+.Pp
+The
+.Xr close 2
+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, 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
+returns a pointer to the mapped region.
+Otherwise, a value of -1 is returned and
+.Va errno
+is set to indicate the error.
+.Sh ERRORS
+.Fn Mmap
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EACCES
+The flag PROT_READ was specified as part of the
+.Fa prot
+parameter and
+.Fa fd
+was not open for reading.
+The flags PROT_WRITE, MAP_SHARED and MAP_WRITE were specified as part
+of the
+.Fa flags
+and
+.Fa prot
+parameters and
+.Fa fd
+was not open for writing.
+.It Bq Er EBADF
+.Fa Fd
+is not a valid open file descriptor.
+.It Bq Er EINVAL
+One of MAP_ANON or MAP_FILE was not specified as part of the
+.Fa flags
+parameter.
+MAP_FIXED was specified and the
+.I addr
+parameter was not page aligned.
+.Fa Fd
+did not reference a regular or character special file.
+.It Bq Er ENOMEM
+MAP_FIXED was specified and the
+.Fa addr
+parameter wasn't available.
+MAP_ANON was specified an insufficient memory was available.
+.Sh "SEE ALSO"
+.Xr getpagesize 2 ,
+.Xr msync 2 ,
+.Xr munmap 2 ,
+.Xr mprotect 2 ,
+.Xr madvise 2 ,
+.Xr mincore 2
projects / unix-history / commitdiff