bsd/man/man2/munmap.2

   1 .\"
   2 .\" Copyright (c) 2008 Apple Inc.  All rights reserved.
   3 .\"
   4 .\" @APPLE_LICENSE_HEADER_START@
   5 .\"
   6 .\" This file contains Original Code and/or Modifications of Original Code
   7 .\" as defined in and that are subject to the Apple Public Source License
   8 .\" Version 2.0 (the 'License'). You may not use this file except in
   9 .\" compliance with the License. Please obtain a copy of the License at
  10 .\" http://www.opensource.apple.com/apsl/ and read it before using this
  11 .\" file.
  12 .\"
  13 .\" The Original Code and all software distributed under the License are
  14 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18 .\" Please see the License for the specific language governing rights and
  19 .\" limitations under the License.
  20 .\"
  21 .\" @APPLE_LICENSE_HEADER_END@
  22 .\"
  23 .\"
  24 .\"     $NetBSD: munmap.2,v 1.5 1995/02/27 12:35:03 cgd Exp $
  25 .\"
  26 .\" Copyright (c) 1991, 1993
  27 .\"     The Regents of the University of California.  All rights reserved.
  28 .\"
  29 .\" Redistribution and use in source and binary forms, with or without
  30 .\" modification, are permitted provided that the following conditions
  31 .\" are met:
  32 .\" 1. Redistributions of source code must retain the above copyright
  33 .\"    notice, this list of conditions and the following disclaimer.
  34 .\" 2. Redistributions in binary form must reproduce the above copyright
  35 .\"    notice, this list of conditions and the following disclaimer in the
  36 .\"    documentation and/or other materials provided with the distribution.
  37 .\" 3. All advertising materials mentioning features or use of this software
  38 .\"    must display the following acknowledgement:
  39 .\"     This product includes software developed by the University of
  40 .\"     California, Berkeley and its contributors.
  41 .\" 4. Neither the name of the University nor the names of its contributors
  42 .\"    may be used to endorse or promote products derived from this software
  43 .\"    without specific prior written permission.
  44 .\"
  45 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  46 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  47 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  48 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  49 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  50 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  51 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  52 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  53 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  54 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  55 .\" SUCH DAMAGE.
  56 .\"
  57 .\"     @(#)munmap.2    8.2 (Berkeley) 4/15/94
  58 .\"
  59 .Dd October 16, 2008
  60 .Dt MUNMAP 2
  61 .Os
  62 .Sh NAME
  63 .Nm munmap
  64 .Nd remove a mapping
  65 .Sh SYNOPSIS
  66 .Fd #include <sys/mman.h>
  67 .Ft int
  68 .Fo munmap
  69 .Fa "void *addr"
  70 .Fa "size_t len"
  71 .Fc
  72 .Sh DESCRIPTION
  73 The
  74 .Fn munmap
  75 system call
  76 deletes the mappings for the specified address range,
  77 causing further references to addresses within the range
  78 to generate invalid memory references.
  79 .Sh DIRTY PAGE HANDLING
  80 How
  81 .Fn munmap
  82 handles a dirty page, depends on what type of memory is being unmapped:
  83 .Pp
  84 .Bl -tag -width "[System V Shared]"
  85 .It Bq Anonymous
  86 If the memory is anonymous memory and if the last reference is going
  87 away, then the contents are discarded by definition of anonymous memory.
  88 .It Bq System V Shared
  89 If the memory mapping was created using System V shared memory, then
  90 the contents persist until the System V memory region is destroyed or
  91 the system is rebooted.
  92 .It Bq File mapping
  93 If the mapping maps data from a file (MAP_SHARED), then the memory will
  94 eventually be written back to disk if it's dirty.  This will happen
  95 automatically at some point in the future (implementation dependent).
  96 Note: to force the memory to be written back to the disk, use
  97 .Xr msync 2 .
  98 .El
  99 .Pp
 100 If there are still other references to the memory when the munmap is
 101 done, then nothing is done to the memory itself and it may be swapped
 102 out if need be. The memory will continue to persist until the last
 103 reference goes away (except for System V shared memory in which case,
 104 see above).
 105 .Sh RETURN VALUES
 106 Upon successful completion,
 107 .Nm munmap
 108 returns zero.
 109 Otherwise, a value of -1 is returned and
 110 .Va errno
 111 is set to indicate the error.
 112 .Sh ERRORS
 113 .Fn munmap
 114 will fail if:
 115 .Bl -tag -width Er
 116 .\" ===========
 117 .It Bq Er EINVAL
 118 The
 119 .Fa addr
 120 parameter was not page aligned (i.e., a multiple of the page size).
 121 .\" ===========
 122 .It Bq Er EINVAL
 123 The
 124 .Fa len
 125 parameter was negative or zero.
 126 .\" ===========
 127 .It Bq Er EINVAL
 128 Some part of the region being unmapped is not part of the currently
 129 valid address space.
 130 .El
 131 .Sh LEGACY SYNOPSIS
 132 .Fd #include <sys/types.h>
 133 .Fd #include <sys/mman.h>
 134 .Pp
 135 The include file
 136 .In sys/types.h
 137 is necessary.
 138 .Pp
 139 .Ft int
 140 .br
 141 .Fo munmap
 142 .Fa "caddr_t addr"
 143 .Fa "size_t len"
 144 .Fc ;
 145 .Pp
 146 The type of
 147 .Fa addr
 148 has changed.
 149 .Sh "SEE ALSO"
 150 .Xr getpagesize 3 ,
 151 .Xr msync 2 ,
 152 .Xr munmap 2 ,
 153 .Xr mprotect 2 ,
 154 .Xr madvise 2 ,
 155 .Xr mincore 2 ,
 156 .Xr compat 5
 157 .Sh HISTORY
 158 The
 159 .Fn munmap
 160 function first appeared in 4.4BSD.