1.\" $OpenBSD: mquery.2,v 1.12 2021/01/20 19:44:48 otto Exp $ 2.\" 3.\" Copyright (c) 2003 Artur Grabowski <art@openbsd.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.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. The name of the author may not be used to endorse or promote products 13.\" derived from this software without specific prior written permission. 14.\" 15.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 16.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 17.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 18.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 19.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 20.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 21.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 22.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 23.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 24.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd $Mdocdate: January 20 2021 $ 27.Dt MQUERY 2 28.Os 29.Sh NAME 30.Nm mquery 31.Nd provide mapping hints to applications 32.Sh SYNOPSIS 33.In sys/mman.h 34.Ft void * 35.Fn mquery "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" 36.Sh DESCRIPTION 37The 38.Fn mquery 39system call checks the existing memory mappings of a process and returns 40hints to the caller about where to put a memory mapping. 41This hint can be later used when performing memory mappings with the 42.Xr mmap 2 43system call with 44.Dv MAP_FIXED 45in the flags. 46The 47.Fa addr 48argument should be a memory location that which the caller specifies the 49preferred address. 50The 51.Fa size 52argument specifies the requested size of the memory area the caller 53is looking for. 54The 55.Fa fd 56and 57.Fa off 58arguments specify the file that will be mapped and the offset in it, 59this is the same as the corresponding arguments to 60.Xr mmap 2 . 61.Pp 62The behavior of the function depends on the 63.Fa flags 64argument. 65If set to 66.Dv MAP_FIXED 67the pointer 68.Fa addr 69is used as a fixed hint and 70.Fn mquery 71will return 72.Dv MAP_FAILED 73and set 74.Va errno 75to 76.Er ENOMEM 77if there is not 78.Fa size 79bytes free after that address. 80Otherwise it will return the hint addr. 81If no flags are set 82.Fn mquery 83will use 84.Fa addr 85as a starting point in memory and will search forward to find 86a memory area with 87.Fa size 88bytes free and that will be suitable for creating a mapping for the 89file and offset specified in the 90.Fa fd 91and 92.Fa off 93arguments. 94When no such area can be found 95.Fn mquery 96will return 97.Dv MAP_FAILED 98and set 99.Va errno 100to indicate the error. 101.Sh RETURN VALUES 102When a memory range satisfying the request is found 103.Fn mquery 104returns the available address. 105Otherwise, 106.Dv MAP_FAILED 107is returned and 108.Va errno 109is set to indicate the error. 110.Sh ERRORS 111.Fn mquery 112will fail if: 113.Bl -tag -width Er 114.It Bq Er EINVAL 115.Dv MAP_FIXED 116was specified and the requested memory area is unavailable. 117.It Bq Er ENOMEM 118There was not enough memory left after the hint specified. 119.It Bq Er EBADF 120.Fa fd 121is not a valid open file descriptor. 122.El 123.Sh SEE ALSO 124.Xr mmap 2 125.Sh STANDARDS 126The 127.Fn mquery 128function should not be used in portable applications. 129.Sh HISTORY 130The 131.Fn mquery 132function first appeared in 133.Ox 3.4 . 134