| 1 | .\" Copyright (c) 1991, 1993 |
| 2 | .\" The Regents of the University of California. All rights reserved. |
| 3 | .\" |
| 4 | .\" Redistribution and use in source and binary forms, with or without |
| 5 | .\" modification, are permitted provided that the following conditions |
| 6 | .\" are met: |
| 7 | .\" 1. Redistributions of source code must retain the above copyright |
| 8 | .\" notice, this list of conditions and the following disclaimer. |
| 9 | .\" 2. Redistributions in binary form must reproduce the above copyright |
| 10 | .\" notice, this list of conditions and the following disclaimer in the |
| 11 | .\" documentation and/or other materials provided with the distribution. |
| 12 | .\" 3. All advertising materials mentioning features or use of this software |
| 13 | .\" must display the following acknowledgement: |
| 14 | .\" This product includes software developed by the University of |
| 15 | .\" California, Berkeley and its contributors. |
| 16 | .\" 4. Neither the name of the University nor the names of its contributors |
| 17 | .\" may be used to endorse or promote products derived from this software |
| 18 | .\" without specific prior written permission. |
| 19 | .\" |
| 20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| 21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| 24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 30 | .\" SUCH DAMAGE. |
| 31 | .\" |
| 32 | .\" @(#)mmap.2 8.4 (Berkeley) 5/11/95 |
| 33 | .\" $FreeBSD: src/lib/libc/sys/mmap.2,v 1.22.2.12 2002/02/27 03:40:13 dd Exp $ |
| 34 | .\" |
| 35 | .Dd November 17, 2001 |
| 36 | .Dt MMAP 2 |
| 37 | .Os |
| 38 | .Sh NAME |
| 39 | .Nm mmap |
| 40 | .Nd allocate memory, or map files or devices into memory |
| 41 | .Sh LIBRARY |
| 42 | .Lb libc |
| 43 | .Sh SYNOPSIS |
| 44 | .In sys/types.h |
| 45 | .In sys/mman.h |
| 46 | .Ft void * |
| 47 | .Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" |
| 48 | .Sh DESCRIPTION |
| 49 | The |
| 50 | .Fn mmap |
| 51 | function causes the pages starting at |
| 52 | .Fa addr |
| 53 | and continuing for at most |
| 54 | .Fa len |
| 55 | bytes to be mapped from the object described by |
| 56 | .Fa fd , |
| 57 | starting at byte offset |
| 58 | .Fa offset . |
| 59 | If |
| 60 | .Fa len |
| 61 | is not a multiple of the pagesize, the mapped region may extend past the |
| 62 | specified range. |
| 63 | Any such extension beyond the end of the mapped object will be zero-filled. |
| 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 PROT_WRITE -compact |
| 85 | .It Dv PROT_NONE |
| 86 | Pages may not be accessed. |
| 87 | .It Dv PROT_READ |
| 88 | Pages may be read. |
| 89 | .It Dv PROT_WRITE |
| 90 | Pages may be written. |
| 91 | .It Dv PROT_EXEC |
| 92 | Pages may be executed. |
| 93 | .El |
| 94 | .Pp |
| 95 | The |
| 96 | .Fa flags |
| 97 | parameter specifies the type of the mapped object, mapping options and |
| 98 | whether modifications made to the mapped copy of the page are private |
| 99 | to the process or are to be shared with other references. |
| 100 | Sharing, mapping type and options are specified in the |
| 101 | .Fa flags |
| 102 | argument by |
| 103 | .Em or Ns 'ing |
| 104 | the following values: |
| 105 | .Bl -tag -width MAP_HASSEMAPHORE |
| 106 | .It Dv MAP_ANON |
| 107 | Map anonymous memory not associated with any specific file. |
| 108 | The file descriptor used for creating |
| 109 | .Dv MAP_ANON |
| 110 | must be \-1. |
| 111 | The |
| 112 | .Fa offset |
| 113 | parameter is ignored. |
| 114 | .\".It Dv MAP_FILE |
| 115 | .\"Mapped from a regular file or character-special device memory. |
| 116 | .It Dv MAP_FIXED |
| 117 | Do not permit the system to select a different address than the one |
| 118 | specified. |
| 119 | If the specified address cannot be used, |
| 120 | .Fn mmap |
| 121 | will fail. |
| 122 | If |
| 123 | .Dv MAP_FIXED |
| 124 | is specified, |
| 125 | .Fa addr |
| 126 | must be a multiple of the pagesize. |
| 127 | Use of this option is discouraged. |
| 128 | .It Dv MAP_HASSEMAPHORE |
| 129 | Notify the kernel that the region may contain semaphores and that special |
| 130 | handling may be necessary. |
| 131 | .It Dv MAP_NOCORE |
| 132 | Region is not included in a core file. |
| 133 | .It Dv MAP_NOSYNC |
| 134 | Causes data dirtied via this VM map to be flushed to physical media |
| 135 | only when necessary (usually by the pager) rather then gratuitously. |
| 136 | Typically this prevents the update daemons from flushing pages dirtied |
| 137 | through such maps and thus allows efficient sharing of memory across |
| 138 | unassociated processes using a file-backed shared memory map. Without |
| 139 | this option any VM pages you dirty may be flushed to disk every so often |
| 140 | (every 30-60 seconds usually) which can create performance problems if you |
| 141 | do not need that to occur (such as when you are using shared file-backed |
| 142 | mmap regions for IPC purposes). Note that VM/filesystem coherency is |
| 143 | maintained whether you use |
| 144 | .Dv MAP_NOSYNC |
| 145 | or not. This option is not portable |
| 146 | across |
| 147 | .Ux |
| 148 | platforms (yet), though some may implement the same behavior |
| 149 | by default. |
| 150 | .Pp |
| 151 | .Em WARNING ! |
| 152 | Extending a file with |
| 153 | .Xr ftruncate 2 , |
| 154 | thus creating a big hole, and then filling the hole by modifying a shared |
| 155 | .Fn mmap |
| 156 | can lead to severe file fragmentation. |
| 157 | In order to avoid such fragmentation you should always pre-allocate the |
| 158 | file's backing store by |
| 159 | .Fn write Ns ing |
| 160 | zero's into the newly extended area prior to modifying the area via your |
| 161 | .Fn mmap . |
| 162 | The fragmentation problem is especially sensitive to |
| 163 | .Dv MAP_NOSYNC |
| 164 | pages, because pages may be flushed to disk in a totally random order. |
| 165 | .Pp |
| 166 | The same applies when using |
| 167 | .Dv MAP_NOSYNC |
| 168 | to implement a file-based shared memory store. |
| 169 | It is recommended that you create the backing store by |
| 170 | .Fn write Ns ing |
| 171 | zero's to the backing file rather then |
| 172 | .Fn ftruncate Ns ing |
| 173 | it. |
| 174 | You can test file fragmentation by observing the KB/t (kilobytes per |
| 175 | transfer) results from an |
| 176 | .Dq Li iostat 1 |
| 177 | while reading a large file sequentially, e.g. using |
| 178 | .Dq Li dd if=filename of=/dev/null bs=32k . |
| 179 | .Pp |
| 180 | The |
| 181 | .Xr fsync 2 |
| 182 | function will flush all dirty data and metadata associated with a file, |
| 183 | including dirty NOSYNC VM data, to physical media. The |
| 184 | .Xr sync 8 |
| 185 | command and |
| 186 | .Xr sync 2 |
| 187 | system call generally do not flush dirty NOSYNC VM data. |
| 188 | The |
| 189 | .Xr msync 2 |
| 190 | system call is obsolete since |
| 191 | .Bx |
| 192 | implements a coherent filesystem buffer cache. However, it may be |
| 193 | used to associate dirty VM pages with filesystem buffers and thus cause |
| 194 | them to be flushed to physical media sooner rather then later. |
| 195 | .It Dv MAP_PRIVATE |
| 196 | Modifications are private. |
| 197 | .It Dv MAP_SHARED |
| 198 | Modifications are shared. |
| 199 | .It Dv MAP_STACK |
| 200 | This option is only available if your system has been compiled with |
| 201 | .Dv VM_STACK |
| 202 | defined when compiling the kernel. |
| 203 | This is the default for |
| 204 | i386 only. |
| 205 | Consider adding |
| 206 | .Li -DVM_STACK |
| 207 | to |
| 208 | .Va COPTFLAGS |
| 209 | in your |
| 210 | .Pa /etc/make.conf |
| 211 | to enable this option for other architechures. |
| 212 | .Dv MAP_STACK |
| 213 | implies |
| 214 | .Dv MAP_ANON , |
| 215 | and |
| 216 | .Fa offset |
| 217 | of 0. |
| 218 | .Fa fd |
| 219 | must be -1 and |
| 220 | .Fa prot |
| 221 | must include at least |
| 222 | .Dv PROT_READ |
| 223 | and |
| 224 | .Dv PROT_WRITE . |
| 225 | This option creates |
| 226 | a memory region that grows to at most |
| 227 | .Fa len |
| 228 | bytes in size, starting from the stack top and growing down. The |
| 229 | stack top is the starting address returned by the call, plus |
| 230 | .Fa len |
| 231 | bytes. The bottom of the stack at maximum growth is the starting |
| 232 | address returned by the call. |
| 233 | .El |
| 234 | .Pp |
| 235 | The |
| 236 | .Xr close 2 |
| 237 | function does not unmap pages, see |
| 238 | .Xr munmap 2 |
| 239 | for further information. |
| 240 | .Pp |
| 241 | The current design does not allow a process to specify the location of |
| 242 | swap space. |
| 243 | In the future we may define an additional mapping type, |
| 244 | .Dv MAP_SWAP , |
| 245 | in which |
| 246 | the file descriptor argument specifies a file or device to which swapping |
| 247 | should be done. |
| 248 | .Sh RETURN VALUES |
| 249 | Upon successful completion, |
| 250 | .Fn mmap |
| 251 | returns a pointer to the mapped region. |
| 252 | Otherwise, a value of |
| 253 | .Dv MAP_FAILED |
| 254 | is returned and |
| 255 | .Va errno |
| 256 | is set to indicate the error. |
| 257 | .Sh ERRORS |
| 258 | .Fn Mmap |
| 259 | will fail if: |
| 260 | .Bl -tag -width Er |
| 261 | .It Bq Er EACCES |
| 262 | The flag |
| 263 | .Dv PROT_READ |
| 264 | was specified as part of the |
| 265 | .Fa prot |
| 266 | parameter and |
| 267 | .Fa fd |
| 268 | was not open for reading. |
| 269 | The flags |
| 270 | .Dv MAP_SHARED |
| 271 | and |
| 272 | .Dv PROT_WRITE |
| 273 | were specified as part of the |
| 274 | .Fa flags |
| 275 | and |
| 276 | .Fa prot |
| 277 | parameters and |
| 278 | .Fa fd |
| 279 | was not open for writing. |
| 280 | .It Bq Er EBADF |
| 281 | .Fa fd |
| 282 | is not a valid open file descriptor. |
| 283 | .It Bq Er EINVAL |
| 284 | .Dv MAP_FIXED |
| 285 | was specified and the |
| 286 | .Fa addr |
| 287 | parameter was not page aligned, or part of the desired address space |
| 288 | resides out of the valid address space for a user process. |
| 289 | .It Bq Er EINVAL |
| 290 | .Fa Len |
| 291 | was negative. |
| 292 | .It Bq Er EINVAL |
| 293 | .Dv MAP_ANON |
| 294 | was specified and the |
| 295 | .Fa fd |
| 296 | parameter was not -1. |
| 297 | .It Bq Er EINVAL |
| 298 | .Dv MAP_ANON |
| 299 | has not been specified and |
| 300 | .Fa fd |
| 301 | did not reference a regular or character special file. |
| 302 | .It Bq Er EINVAL |
| 303 | .Fa Offset |
| 304 | was not page-aligned. |
| 305 | (See |
| 306 | .Sx BUGS |
| 307 | below.) |
| 308 | .It Bq Er ENOMEM |
| 309 | .Dv MAP_FIXED |
| 310 | was specified and the |
| 311 | .Fa addr |
| 312 | parameter wasn't available. |
| 313 | .Dv MAP_ANON |
| 314 | was specified and insufficient memory was available. |
| 315 | The system has reached the per-process mmap limit specified in the |
| 316 | .Va vm.max_proc_mmap |
| 317 | sysctl. |
| 318 | .El |
| 319 | .Sh SEE ALSO |
| 320 | .Xr madvise 2 , |
| 321 | .Xr mincore 2 , |
| 322 | .Xr mlock 2 , |
| 323 | .Xr mprotect 2 , |
| 324 | .Xr msync 2 , |
| 325 | .Xr munlock 2 , |
| 326 | .Xr munmap 2 , |
| 327 | .Xr getpagesize 3 |
| 328 | .Sh BUGS |
| 329 | .Fa len |
| 330 | is limited to 2GB. Mmapping slightly more than 2GB doesn't work, but |
| 331 | it is possible to map a window of size (filesize % 2GB) for file sizes |
| 332 | of slightly less than 2G, 4GB, 6GB and 8GB. |
| 333 | .Pp |
| 334 | The limit is imposed for a variety of reasons. |
| 335 | Most of them have to do |
| 336 | with |
| 337 | .Fx |
| 338 | not wanting to use 64 bit offsets in the VM system due to |
| 339 | the extreme performance penalty. |
| 340 | So |
| 341 | .Fx |
| 342 | uses 32bit page indexes and |
| 343 | this gives |
| 344 | .Fx |
| 345 | a maximum of 8TB filesizes. |
| 346 | It's actually bugs in |
| 347 | the filesystem code that causes the limit to be further restricted to |
| 348 | 1TB (loss of precision when doing blockno calculations). |
| 349 | .Pp |
| 350 | Another reason for the 2GB limit is that filesystem metadata can |
| 351 | reside at negative offsets. |