bsd/man/man2/mmap.2

   1 .\"     $NetBSD: mmap.2,v 1.5 1995/06/24 10:48:59 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)mmap.2      8.1 (Berkeley) 6/4/93
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt MMAP 2
  38 .Os BSD 4
  39 .Sh NAME
  40 .Nm mmap
  41 .Nd map files or devices into memory
  42 .Sh SYNOPSIS
  43 .Fd #include <sys/types.h>
  44 .Fd #include <sys/mman.h>
  45 .Ft void *
  46 .Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset"
  47 .Sh DESCRIPTION
  48 The
  49 .Nm mmap
  50 function causes the pages starting at
  51 .Fa addr
  52 and continuing for at most
  53 .Fa len
  54 bytes to be mapped from the object described by
  55 .Fa fd ,
  56 starting at byte offset
  57 .Fa offset .
  58 If
  59 .Fa offset
  60 or
  61 .Fa len
  62 is not a multiple of the pagesize, the mapped region may extend past the
  63 specified range.
  64 .Pp
  65 If
  66 .Fa addr
  67 is non-zero, it is used as a hint to the system.
  68 (As a convenience to the system, the actual address of the region may differ
  69 from the address supplied.)
  70 If
  71 .Fa addr
  72 is zero, an address will be selected by the system.
  73 The actual starting address of the region is returned.
  74 A successful
  75 .Fa mmap
  76 deletes any previous mapping in the allocated address range.
  77 .Pp
  78 The protections (region accessibility) are specified in the
  79 .Fa prot
  80 argument by
  81 .Em or Ns 'ing
  82 the following values:
  83 .Pp
  84 .Bl -tag -width MAP_FIXEDX
  85 .It Dv PROT_EXEC
  86 Pages may be executed.
  87 .It Dv PROT_READ
  88 Pages may be read.
  89 .It Dv PROT_WRITE
  90 Pages may be written.
  91 .El
  92 .Pp
  93 The
  94 .Fa flags
  95 parameter specifies the type of the mapped object, mapping options and
  96 whether modifications made to the mapped copy of the page are private
  97 to the process or are to be shared with other references.
  98 Sharing, mapping type and options are specified in the
  99 .Fa flags
 100 argument by
 101 .Em or Ns 'ing
 102 the following values:
 103 .Pp
 104 .Bl -tag -width MAP_FIXEDX
 105 .It Dv MAP_ANON
 106 Map anonymous memory not associated with any specific file.
 107 The file descriptor used for creating
 108 .Dv MAP_ANON
 109 regions is used only for
 110 naming, and may be specified as \-1 if no name is associated with the
 111 region.
 112 .It Dv MAP_FILE
 113 Mapped from a regular file or character-special device memory.  (This is
 114 the default mapping type, and need not be specified.)
 115 .It Dv MAP_FIXED
 116 Do not permit the system to select a different address than the one
 117 specified.
 118 If the specified address cannot be used,
 119 .Nm mmap
 120 will fail.
 121 If MAP_FIXED is specified,
 122 .Fa addr
 123 must be a multiple of the pagesize.
 124 Use of this option is discouraged.
 125 .It Dv MAP_HASSEMAPHORE
 126 Notify the kernel that the region may contain semaphores and that special
 127 handling may be necessary.
 128 .It Dv MAP_PRIVATE
 129 Modifications are private.
 130 .It Dv MAP_SHARED
 131 Modifications are shared.
 132 .El
 133 .Pp
 134 The
 135 .Xr close 2
 136 function does not unmap pages, see
 137 .Xr munmap 2
 138 for further information.
 139 .Pp
 140 The current design does not allow a process to specify the location of
 141 swap space.
 142 In the future we may define an additional mapping type,
 143 .Dv MAP_SWAP ,
 144 in which
 145 the file descriptor argument specifies a file or device to which swapping
 146 should be done.
 147 .Sh RETURN VALUES
 148 Upon successful completion,
 149 .Nm mmap
 150 returns a pointer to the mapped region.
 151 Otherwise, a value of -1 is returned and
 152 .Va errno
 153 is set to indicate the error.
 154 .Sh ERRORS
 155 .Fn Mmap
 156 will fail if:
 157 .Bl -tag -width Er
 158 .It Bq Er EACCES
 159 The flag
 160 .Dv PROT_READ
 161 was specified as part of the
 162 .Fa prot
 163 parameter and
 164 .Fa fd
 165 was not open for reading.
 166 The flags
 167 .Dv PROT_WRITE
 168 and
 169 .Dv MAP_SHARED
 170 were specified as part
 171 of the
 172 .Fa flags
 173 and
 174 .Fa prot
 175 parameters and
 176 .Fa fd
 177 was not open for writing.
 178 .It Bq Er EBADF
 179 .Fa fd
 180 is not a valid open file descriptor.
 181 .It Bq Er EINVAL
 182 .Dv MAP_FIXED
 183 was specified and the
 184 .I addr
 185 parameter was not page aligned.
 186 .Fa fd
 187 did not reference a regular or character special file.
 188 .It Bq Er ENOMEM
 189 .Dv MAP_FIXED
 190 was specified and the
 191 .Fa addr
 192 parameter wasn't available.
 193 .Dv MAP_ANON
 194 was specified and insufficient memory was available.
 195 .El
 196 .Sh "SEE ALSO"
 197 .Xr getpagesize 2 ,
 198 .Xr msync 2 ,
 199 .Xr munmap 2 ,
 200 .Xr mprotect 2 ,
 201 .Xr madvise 2 ,
 202 .Xr mincore 2 ,
 203 .Xr mlock 2