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 43The 44.Fn shm_map 45and 46.Fn shm_unmap 47functions provide an API for mapping shared memory objects into the kernel. 48Shared memory objects are created by 49.Xr shm_open 2 . 50These objects can then be passed into the kernel via file descriptors. 51.Pp 52A shared memory object cannot be shrunk while it is mapped into the kernel. 53This is to avoid invalidating any pages that may be wired into the kernel's 54address space. 55Shared memory objects can still be grown while mapped into the kernel. 56.Pp 57To simplify the accounting needed to enforce the above requirement, 58callers of this API are required to unmap the entire region mapped by 59.Fn shm_map 60when calling 61.Fn shm_unmap . 62Unmapping only a portion of the region is not permitted. 63.Pp 64The 65.Fn shm_map 66function locates the shared memory object associated with the open file 67.Fa fp . 68It maps the region of that object described by 69.Fa offset 70and 71.Fa size 72into the kernel's address space. 73If it succeeds, 74.Fa *memp 75will be set to the start of the mapping. 76All pages for the range will be wired into memory upon successful return. 77.Pp 78The 79.Fn shm_unmap 80function unmaps a region previously mapped by 81.Fn shm_map . 82The 83.Fa mem 84argument should match the value previously returned in 85.Fa *memp , 86and the 87.Fa size 88argument should match the value passed to 89.Fn shm_map . 90.Pp 91Note that 92.Fn shm_map 93will not hold an extra reference on the open file 94.Fa fp 95for the lifetime of the mapping. 96Instead, 97the calling code is required to do this if it wishes to use 98.Fn shm_unmap 99on the region in the future. 100.Sh RETURN VALUES 101The 102.Fn shm_map 103and 104.Fn shm_unmap 105functions return zero on success or an error on failure. 106.Sh EXAMPLES 107The following function accepts a file descriptor for a shared memory 108object. 109It maps the first sixteen kilobytes of the object into the kernel, 110performs some work on that address, 111and then unmaps the address before returning. 112.Bd -literal -offset indent 113int 114shm_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 137The 138.Fn shm_map 139function returns the following errors on failure: 140.Bl -tag -width Er 141.It Bq Er EINVAL 142The open file 143.Fa fp 144is not a shared memory object. 145.It Bq Er EINVAL 146The requested region described by 147.Fa offset 148and 149.Fa size 150extends beyond the end of the shared memory object. 151.It Bq Er ENOMEM 152Insufficient address space was available. 153.It Bq Er EACCES 154The shared memory object could not be mapped due to a protection error. 155.It Bq Er EINVAL 156The shared memory object could not be mapped due to some other VM error. 157.El 158.Pp 159The 160.Fn shm_unmap 161function returns the following errors on failure: 162.Bl -tag -width Er 163.It Bq Er EINVAL 164The open file 165.Fa fp 166is not a shared memory object. 167.It Bq Er EINVAL 168The address range described by 169.Fa mem 170and 171.Fa size 172is not a valid address range. 173.It Bq Er EINVAL 174The address range described by 175.Fa mem 176and 177.Fa size 178is not backed by the shared memory object associated with the open file 179.Fa fp , 180or 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 185This API was first introduced in 186.Fx 10.0 . 187