1.\" 2.\" Copyright (c) 2011 Hudson River Trading 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.Dd December 14, 2011 28.Dt SHM_MAP 9 29.Os 30.Sh NAME 31.Nm shm_map , shm_unmap 32.Nd "map shared memory objects into the kernel's address space" 33.Sh SYNOPSIS 34.In sys/types.h 35.In sys/mman.h 36.Ft int 37.Fn shm_map "struct file *fp" "size_t size" "off_t offset" "void **memp" 38.Ft int 39.Fn shm_unmap "struct file *fp" "void *mem" "size_t size" 40.Sh DESCRIPTION 41The 42.Fn shm_map 43and 44.Fn shm_unmap 45functions provide an API for mapping shared memory objects into the kernel. 46Shared memory objects are created by 47.Xr shm_open 2 . 48These objects can then be passed into the kernel via file descriptors. 49.Pp 50A shared memory object cannot be shrunk while it is mapped into the kernel. 51This is to avoid invalidating any pages that may be wired into the kernel's 52address space. 53Shared memory objects can still be grown while mapped into the kernel. 54.Pp 55To simplify the accounting needed to enforce the above requirement, 56callers of this API are required to unmap the entire region mapped by 57.Fn shm_map 58when calling 59.Fn shm_unmap . 60Unmapping only a portion of the region is not permitted. 61.Pp 62The 63.Fn shm_map 64function locates the shared memory object associated with the open file 65.Fa fp . 66It maps the region of that object described by 67.Fa offset 68and 69.Fa size 70into the kernel's address space. 71If it succeeds, 72.Fa *memp 73will be set to the start of the mapping. 74All pages for the range will be wired into memory upon successful return. 75.Pp 76The 77.Fn shm_unmap 78function unmaps a region previously mapped by 79.Fn shm_map . 80The 81.Fa mem 82argument should match the value previously returned in 83.Fa *memp , 84and the 85.Fa size 86argument should match the value passed to 87.Fn shm_map . 88.Pp 89Note that 90.Fn shm_map 91will not hold an extra reference on the open file 92.Fa fp 93for the lifetime of the mapping. 94Instead, 95the calling code is required to do this if it wishes to use 96.Fn shm_unmap 97on the region in the future. 98.Sh RETURN VALUES 99The 100.Fn shm_map 101and 102.Fn shm_unmap 103functions return zero on success or an error on failure. 104.Sh EXAMPLES 105The following function accepts a file descriptor for a shared memory 106object. 107It maps the first sixteen kilobytes of the object into the kernel, 108performs some work on that address, 109and then unmaps the address before returning. 110.Bd -literal -offset indent 111int 112shm_example(int fd) 113{ 114 struct file *fp; 115 void *mem; 116 int error; 117 118 error = fget(curthread, fd, CAP_MMAP, &fp); 119 if (error) 120 return (error); 121 error = shm_map(fp, 16384, 0, &mem); 122 if (error) { 123 fdrop(fp, curthread); 124 return (error); 125 } 126 127 /* Do something with 'mem'. */ 128 129 error = shm_unmap(fp, mem, 16384); 130 fdrop(fp, curthread); 131 return (error); 132} 133.Ed 134.Sh ERRORS 135The 136.Fn shm_map 137function returns the following errors on failure: 138.Bl -tag -width Er 139.It Bq Er EINVAL 140The open file 141.Fa fp 142is not a shared memory object. 143.It Bq Er EINVAL 144The requested region described by 145.Fa offset 146and 147.Fa size 148extends beyond the end of the shared memory object. 149.It Bq Er ENOMEM 150Insufficient address space was available. 151.It Bq Er EACCES 152The shared memory object could not be mapped due to a protection error. 153.It Bq Er EINVAL 154The shared memory object could not be mapped due to some other VM error. 155.El 156.Pp 157The 158.Fn shm_unmap 159function returns the following errors on failure: 160.Bl -tag -width Er 161.It Bq Er EINVAL 162The open file 163.Fa fp 164is not a shared memory object. 165.It Bq Er EINVAL 166The address range described by 167.Fa mem 168and 169.Fa size 170is not a valid address range. 171.It Bq Er EINVAL 172The address range described by 173.Fa mem 174and 175.Fa size 176is not backed by the shared memory object associated with the open file 177.Fa fp , 178or the address range does not cover the entire mapping of the object. 179.El 180.Sh SEE ALSO 181.Xr shm_open 2 182.Sh HISTORY 183This API was first introduced in 184.Fx 10.0 . 185