share/man/man9/shm_map.9

   1 .\"
   2 .\" Copyright (c) 2011 Advanced Computing Technologies LLC
   3 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
   4 .\" 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 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd December 14, 2011
  30 .Dt SHM_MAP 9
  31 .Os
  32 .Sh NAME
  33 .Nm shm_map , shm_unmap
  34 .Nd "map shared memory objects into the kernel's address space"
  35 .Sh SYNOPSIS
  36 .In sys/types.h
  37 .In sys/mman.h
  38 .Ft int
  39 .Fn shm_map "struct file *fp" "size_t size" "off_t offset" "void **memp"
  40 .Ft int
  41 .Fn shm_unmap "struct file *fp" "void *mem" "size_t size"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn shm_map
  45 and
  46 .Fn shm_unmap
  47 functions provide an API for mapping shared memory objects into the kernel.
  48 Shared memory objects are created by
  49 .Xr shm_open 2 .
  50 These objects can then be passed into the kernel via file descriptors.
  51 .Pp
  52 A shared memory object cannot be shrunk while it is mapped into the kernel.
  53 This is to avoid invalidating any pages that may be wired into the kernel's
  54 address space.
  55 Shared memory objects can still be grown while mapped into the kernel.
  56 .Pp
  57 To simplify the accounting needed to enforce the above requirement,
  58 callers of this API are required to unmap the entire region mapped by
  59 .Fn shm_map
  60 when calling
  61 .Fn shm_unmap .
  62 Unmapping only a portion of the region is not permitted.
  63 .Pp
  64 The
  65 .Fn shm_map
  66 function locates the shared memory object associated with the open file
  67 .Fa fp .
  68 It maps the region of that object described by
  69 .Fa offset
  70 and
  71 .Fa size
  72 into the kernel's address space.
  73 If it succeeds,
  74 .Fa *memp
  75 will be set to the start of the mapping.
  76 All pages for the range will be wired into memory upon successful return.
  77 .Pp
  78 The
  79 .Fn shm_unmap
  80 function unmaps a region previously mapped by
  81 .Fn shm_map .
  82 The
  83 .Fa mem
  84 argument should match the value previously returned in
  85 .Fa *memp ,
  86 and the
  87 .Fa size
  88 argument should match the value passed to
  89 .Fn shm_map .
  90 .Pp
  91 Note that
  92 .Fn shm_map
  93 will not hold an extra reference on the open file
  94 .Fa fp
  95 for the lifetime of the mapping.
  96 Instead,
  97 the calling code is required to do this if it wishes to use
  98 .Fn shm_unmap
  99 on the region in the future.
 100 .Sh RETURN VALUES
 101 The
 102 .Fn shm_map
 103 and
 104 .Fn shm_unmap
 105 functions return zero on success or an error on failure.
 106 .Sh EXAMPLES
 107 The following function accepts a file descriptor for a shared memory
 108 object.
 109 It maps the first sixteen kilobytes of the object into the kernel,
 110 performs some work on that address,
 111 and then unmaps the address before returning.
 112 .Bd -literal -offset indent
 113 int
 114 shm_example(int fd)
 115 {
 116         struct file *fp;
 117         void *mem;
 118         int error;
 119
 120         error = fget(curthread, fd, CAP_MMAP, &fp);
 121         if (error)
 122                 return (error);
 123         error = shm_map(fp, 16384, 0, &mem);
 124         if (error) {
 125                 fdrop(fp, curthread);
 126                 return (error);
 127         }
 128
 129         /* Do something with 'mem'. */
 130
 131         error = shm_unmap(fp, mem, 16384);
 132         fdrop(fp, curthread);
 133         return (error);
 134 }
 135 .Ed
 136 .Sh ERRORS
 137 The
 138 .Fn shm_map
 139 function returns the following errors on failure:
 140 .Bl -tag -width Er
 141 .It Bq Er EINVAL
 142 The open file
 143 .Fa fp
 144 is not a shared memory object.
 145 .It Bq Er EINVAL
 146 The requested region described by
 147 .Fa offset
 148 and
 149 .Fa size
 150 extends beyond the end of the shared memory object.
 151 .It Bq Er ENOMEM
 152 Insufficient address space was available.
 153 .It Bq Er EACCES
 154 The shared memory object could not be mapped due to a protection error.
 155 .It Bq Er EINVAL
 156 The shared memory object could not be mapped due to some other VM error.
 157 .El
 158 .Pp
 159 The
 160 .Fn shm_unmap
 161 function returns the following errors on failure:
 162 .Bl -tag -width Er
 163 .It Bq Er EINVAL
 164 The open file
 165 .Fa fp
 166 is not a shared memory object.
 167 .It Bq Er EINVAL
 168 The address range described by
 169 .Fa mem
 170 and
 171 .Fa size
 172 is not a valid address range.
 173 .It Bq Er EINVAL
 174 The address range described by
 175 .Fa mem
 176 and
 177 .Fa size
 178 is not backed by the shared memory object associated with the open file
 179 .Fa fp ,
 180 or the address range does not cover the entire mapping of the object.
 181 .El
 182 .Sh SEE ALSO
 183 .Xr shm_open 2
 184 .Sh HISTORY
 185 This API was first introduced in
 186 .Fx 10.0 .