1.\" $OpenBSD: mquery.2,v 1.11 2014/07/02 22:22:35 matthew 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: July 2 2014 $ 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 97and set 98.Va errno 99to indicate the error. 100.Sh RETURN VALUES 101When a memory range satisfying the request is found 102.Fn mquery 103returns the available address. 104Otherwise, 105.Dv MAP_FAILED 106is returned and 107.Va errno 108is set to indicate the error. 109.Sh ERRORS 110.Fn mquery 111will fail if: 112.Bl -tag -width Er 113.It Bq Er EINVAL 114.Dv MAP_FIXED 115was specified and the requested memory area is unavailable. 116.It Bq Er ENOMEM 117There was not enough memory left after the hint specified. 118.It Bq Er EBADF 119.Fa fd 120is not a valid open file descriptor. 121.El 122.Sh SEE ALSO 123.Xr mmap 2 124.Sh STANDARDS 125The 126.Fn mquery 127function should not be used in portable applications. 128.Sh HISTORY 129The 130.Fn mquery 131function first appeared in 132.Ox 3.4 . 133