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_INHERIT
 129 Permit regions to be inherited across
 130 .Xr exec 2
 131 system calls.
 132 .It Dv MAP_PRIVATE
 133 Modifications are private.
 134 .It Dv MAP_SHARED
 135 Modifications are shared.
 136 .El
 137 .Pp
 138 The
 139 .Xr close 2
 140 function does not unmap pages, see
 141 .Xr munmap 2
 142 for further information.
 143 .Pp
 144 The current design does not allow a process to specify the location of
 145 swap space.
 146 In the future we may define an additional mapping type,
 147 .Dv MAP_SWAP ,
 148 in which
 149 the file descriptor argument specifies a file or device to which swapping
 150 should be done.
 151 .Sh RETURN VALUES
 152 Upon successful completion,
 153 .Nm mmap
 154 returns a pointer to the mapped region.
 155 Otherwise, a value of -1 is returned and
 156 .Va errno
 157 is set to indicate the error.
 158 .Sh ERRORS
 159 .Fn Mmap
 160 will fail if:
 161 .Bl -tag -width Er
 162 .It Bq Er EACCES
 163 The flag
 164 .Dv PROT_READ
 165 was specified as part of the
 166 .Fa prot
 167 parameter and
 168 .Fa fd
 169 was not open for reading.
 170 The flags
 171 .Dv PROT_WRITE
 172 and
 173 .Dv MAP_SHARED
 174 were specified as part
 175 of the
 176 .Fa flags
 177 and
 178 .Fa prot
 179 parameters and
 180 .Fa fd
 181 was not open for writing.
 182 .It Bq Er EBADF
 183 .Fa fd
 184 is not a valid open file descriptor.
 185 .It Bq Er EINVAL
 186 .Dv MAP_FIXED
 187 was specified and the
 188 .I addr
 189 parameter was not page aligned.
 190 .Fa fd
 191 did not reference a regular or character special file.
 192 .It Bq Er ENOMEM
 193 .Dv MAP_FIXED
 194 was specified and the
 195 .Fa addr
 196 parameter wasn't available.
 197 .Dv MAP_ANON
 198 was specified and insufficient memory was available.
 199 .El
 200 .Sh "SEE ALSO"
 201 .Xr getpagesize 2 ,
 202 .Xr msync 2 ,
 203 .Xr munmap 2 ,
 204 .Xr mprotect 2 ,
 205 .Xr madvise 2 ,
 206 .Xr mincore 2 ,
 207 .Xr mlock 2