1.\" $OpenBSD: mquery.2,v 1.9 2008/06/30 05:59:19 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: June 30 2008 $ 27.Dt MQUERY 2 28.Os 29.Sh NAME 30.Nm mquery 31.Nd provide mapping hints to applications 32.Sh SYNOPSIS 33.Fd #include <sys/types.h> 34.Fd #include <sys/mman.h> 35.Ft void * 36.Fn mquery "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset" 37.Sh DESCRIPTION 38The 39.Nm mquery 40system call checks the existing memory mappings of a process and returns 41hints to the caller about where to put a memory mapping. 42This hint can be later used when performing memory mappings with the 43.Fn mmap 44system call with 45.Dv MAP_FIXED 46in the flags. 47The 48.Fa addr 49argument should be a memory location that which the caller specifies the 50preferred address. 51The 52.Fa size 53argument specifies the requested size of the memory area the caller 54is looking for. 55The 56.Fa fd 57and 58.Fa off 59arguments specify the file that will be mapped and the offset in it, 60this is the same as the corresponding arguments to 61.Fn mmap . 62.Pp 63The behavior of the function depends on the 64.Fa flags 65argument. 66If set to 67.Dv MAP_FIXED 68the pointer 69.Fa addr 70is used as a fixed hint and 71.Fn mquery 72will return 73.Dv MAP_FAILED 74and set 75.Va errno 76to 77.Dv ENOMEM 78if there is not 79.Fa size 80bytes free after that address. 81Otherwise it will return the hint addr. 82If no flags are set 83.Fn mquery 84will use 85.Fa addr 86as a starting point in memory and will search forward to find 87a memory area with 88.Fa size 89bytes free and that will be suitable for creating a mapping for the 90file and offset specified in the 91.Fa fd 92and 93.Fa off 94arguments. 95When no such area can be found 96.Fn mquery 97will return 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