MQUERY(2) | System Calls Manual | MQUERY(2)

# NAME

`mquery` — provide mapping hints to applications

# SYNOPSIS

`#include <sys/mman.h>`

void *
`mquery`(void *addr, size_t len, int prot, int flags, int fd, off_t offset);

# DESCRIPTION

The `mquery`() system call checks the existing memory mappings of a process and returns hints to the caller about where to put a memory mapping. This hint can be later used when performing memory mappings with the mmap(2) system call with `MAP_FIXED` in the flags. The addr argument should be a memory location that which the caller specifies the preferred address. The size argument specifies the requested size of the memory area the caller is looking for. The fd and off arguments specify the file that will be mapped and the offset in it, this is the same as the corresponding arguments to mmap(2).

The behavior of the function depends on the flags argument. If set to `MAP_FIXED`, the pointer addr is used as a fixed hint and `mquery`() will return `MAP_FAILED` and set errno to `ENOMEM` if there is not size bytes free after that address. Otherwise it will return the hint addr. If no flags are set, `mquery`() will use addr as a starting point in memory and will search forward to find a memory area with size bytes free and that will be suitable for creating a mapping for the file and offset specified in the fd and off arguments. When no such area can be found, `mquery`() will return `MAP_FAILED` and set errno to indicate the error.

# RETURN VALUES

When a memory range satisfying the request is found, `mquery`() returns the available address. Otherwise, `MAP_FAILED` is returned and errno is set to indicate the error.

# ERRORS

`mquery`() will fail if:

[`EINVAL`]
  `MAP_FIXED` was specified and the requested memory area is unavailable.
[`ENOMEM`]
  There was not enough memory left after the hint specified.
[`EBADF`]
  fd is not a valid open file descriptor.

# SEE ALSO

mmap(2)

# STANDARDS

The `mquery`() function should not be used in portable applications.

# HISTORY

The `mquery`() function first appeared in OpenBSD 3.4.

March 31, 2022 | Debian