diff options
Diffstat (limited to 'lib/libc/sys/mmap.2')
| -rw-r--r-- | lib/libc/sys/mmap.2 | 364 |
1 files changed, 364 insertions, 0 deletions
diff --git a/lib/libc/sys/mmap.2 b/lib/libc/sys/mmap.2 new file mode 100644 index 0000000..da31179 --- /dev/null +++ b/lib/libc/sys/mmap.2 @@ -0,0 +1,364 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)mmap.2 8.4 (Berkeley) 5/11/95 +.\" $FreeBSD$ +.\" +.Dd April 21, 2006 +.Dt MMAP 2 +.Os +.Sh NAME +.Nm mmap +.Nd allocate memory, or map files or devices into memory +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/mman.h +.Ft void * +.Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" +.Sh DESCRIPTION +The +.Fn mmap +system call 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 len +is not a multiple of the pagesize, the mapped region may extend past the +specified range. +Any such extension beyond the end of the mapped object will be zero-filled. +.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 Ns 'ing +the following values: +.Pp +.Bl -tag -width PROT_WRITE -compact +.It Dv PROT_NONE +Pages may not be accessed. +.It Dv PROT_READ +Pages may be read. +.It Dv PROT_WRITE +Pages may be written. +.It Dv PROT_EXEC +Pages may be executed. +.El +.Pp +The +.Fa flags +argument 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 Ns 'ing +the following values: +.Bl -tag -width MAP_HASSEMAPHORE +.It Dv MAP_ANON +Map anonymous memory not associated with any specific file. +The file descriptor used for creating +.Dv MAP_ANON +must be \-1. +The +.Fa offset +argument is ignored. +.\".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, +.Fn mmap +will fail. +If +.Dv MAP_FIXED +is specified, +.Fa addr +must be a multiple of the pagesize. +If a +.Dv MAP_FIXED +request is successful, the mapping established by +.Fn mmap +replaces any previous mappings for the process' pages in the range from +.Fa addr +to +.Fa addr ++ +.Fa len . +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 +This flag never operated as advertised and is no longer supported. +Please refer to +.Xr minherit 2 +for further information. +.It Dv MAP_NOCORE +Region is not included in a core file. +.It Dv MAP_NOSYNC +Causes data dirtied via this VM map to be flushed to physical media +only when necessary (usually by the pager) rather than gratuitously. +Typically this prevents the update daemons from flushing pages dirtied +through such maps and thus allows efficient sharing of memory across +unassociated processes using a file-backed shared memory map. +Without +this option any VM pages you dirty may be flushed to disk every so often +(every 30-60 seconds usually) which can create performance problems if you +do not need that to occur (such as when you are using shared file-backed +mmap regions for IPC purposes). +Note that VM/file system coherency is +maintained whether you use +.Dv MAP_NOSYNC +or not. +This option is not portable +across +.Ux +platforms (yet), though some may implement the same behavior +by default. +.Pp +.Em WARNING ! +Extending a file with +.Xr ftruncate 2 , +thus creating a big hole, and then filling the hole by modifying a shared +.Fn mmap +can lead to severe file fragmentation. +In order to avoid such fragmentation you should always pre-allocate the +file's backing store by +.Fn write Ns ing +zero's into the newly extended area prior to modifying the area via your +.Fn mmap . +The fragmentation problem is especially sensitive to +.Dv MAP_NOSYNC +pages, because pages may be flushed to disk in a totally random order. +.Pp +The same applies when using +.Dv MAP_NOSYNC +to implement a file-based shared memory store. +It is recommended that you create the backing store by +.Fn write Ns ing +zero's to the backing file rather than +.Fn ftruncate Ns ing +it. +You can test file fragmentation by observing the KB/t (kilobytes per +transfer) results from an +.Dq Li iostat 1 +while reading a large file sequentially, e.g.\& using +.Dq Li dd if=filename of=/dev/null bs=32k . +.Pp +The +.Xr fsync 2 +system call will flush all dirty data and metadata associated with a file, +including dirty NOSYNC VM data, to physical media. +The +.Xr sync 8 +command and +.Xr sync 2 +system call generally do not flush dirty NOSYNC VM data. +The +.Xr msync 2 +system call is obsolete since +.Bx +implements a coherent file system buffer cache. +However, it may be +used to associate dirty VM pages with file system buffers and thus cause +them to be flushed to physical media sooner rather than later. +.It Dv MAP_PRIVATE +Modifications are private. +.It Dv MAP_SHARED +Modifications are shared. +.It Dv MAP_STACK +.Dv MAP_STACK +implies +.Dv MAP_ANON , +and +.Fa offset +of 0. +The +.Fa fd +argument +must be -1 and +.Fa prot +must include at least +.Dv PROT_READ +and +.Dv PROT_WRITE . +This option creates +a memory region that grows to at most +.Fa len +bytes in size, starting from the stack top and growing down. +The +stack top is the starting address returned by the call, plus +.Fa len +bytes. +The bottom of the stack at maximum growth is the starting +address returned by the call. +.El +.Pp +The +.Xr close 2 +system call 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, +.Fn mmap +returns a pointer to the mapped region. +Otherwise, a value of +.Dv MAP_FAILED +is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn mmap +system call +will fail if: +.Bl -tag -width Er +.It Bq Er EACCES +The flag +.Dv PROT_READ +was specified as part of the +.Fa prot +argument and +.Fa fd +was not open for reading. +The flags +.Dv MAP_SHARED +and +.Dv PROT_WRITE +were specified as part of the +.Fa flags +and +.Fa prot +argument and +.Fa fd +was not open for writing. +.It Bq Er EBADF +The +.Fa fd +argument +is not a valid open file descriptor. +.It Bq Er EINVAL +.Dv MAP_FIXED +was specified and the +.Fa addr +argument was not page aligned, or part of the desired address space +resides out of the valid address space for a user process. +.It Bq Er EINVAL +The +.Fa len +argument +was negative. +.It Bq Er EINVAL +.Dv MAP_ANON +was specified and the +.Fa fd +argument was not -1. +The +.Fa offset +argument +was not page-aligned. +(See +.Sx BUGS +below.) +.It Bq Er ENODEV +.Dv MAP_ANON +has not been specified and +.Fa fd +did not reference a regular or character special file. +.It Bq Er ENOMEM +.Dv MAP_FIXED +was specified and the +.Fa addr +argument was not available. +.Dv MAP_ANON +was specified and insufficient memory was available. +The system has reached the per-process mmap limit specified in the +.Va vm.max_proc_mmap +sysctl. +.El +.Sh SEE ALSO +.Xr madvise 2 , +.Xr mincore 2 , +.Xr minherit 2 , +.Xr mlock 2 , +.Xr mprotect 2 , +.Xr msync 2 , +.Xr munlock 2 , +.Xr munmap 2 , +.Xr getpagesize 3 , +.Xr make.conf 5 +.Sh BUGS +The +.Fa len +argument +is limited to the maximum file size or available userland address +space. +Files may not be able to be made more than 1TB large on 32 bit systems +due to file systems restrictions and bugs, but address space is far more +restrictive. +Larger files may be possible on 64 bit systems. +.Pp +The previous documented limit of 2GB was a documentation bug. +That limit has not existed since +.Fx 2.2 . +.Pp +Note that an attempt to +.Fn mmap +zero bytes has no effect and succeeds, while an attempt to +.Fn munmap +zero bytes will return +.Bq Er EINVAL . |
