---
name: "vm_map_find"
section: "9"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/vm_map_find"
---

# vm\_map\_find(9)

find a free region within a map, and optionally map a vm\_object

## NAME

**vm\_map\_find** – find a free region within a map, and optionally map a vm\_object

## SYNOPSIS

**#include \<sys/param.h\>**

**#include \<vm/vm.h\>**

**#include \<vm/vm\_map.h\>**

*int*\

**vm\_map\_find**(*vm\_map\_t map*, *vm\_object\_t object*, *vm\_ooffset\_t offset*, *vm\_offset\_t \*addr*, *vm\_size\_t length*, *vm\_offset\_t max\_addr*, *int find\_space*, *vm\_prot\_t prot*, *vm\_prot\_t max*, *int cow*);

## DESCRIPTION

The **vm\_map\_find**() function attempts to find a free region in the target *map*, with the given *length.* If a free region is found, **vm\_map\_find**() creates a mapping of *object* via a call to [vm\_map\_insert(9)](/vm_map_insert/9.md).

The arguments *offset*, *prot*, *max*, and *cow* are passed unchanged to [vm\_map\_insert(9)](/vm_map_insert/9.md) when creating the mapping, if and only if a free region is found.

If *object* is non-NULL, the reference count on the object must be incremented by the caller before calling this function to account for the new entry.

If *max\_addr* is non-zero, it specifies an upper bound on the mapping. The mapping will only succeed if a free region can be found that resides entirely below *max\_addr*.

The *find\_space* argument specifies the strategy to use when searching for a free region of the requested length. For all values other than VMFS\_NO\_SPACE, [vm\_map\_findspace(9)](/vm_map_findspace/9.md) is called to locate a free region of the requested length with a starting address at or above *\*addr*. The following strategies are supported:

- VMFS\_NO\_SPACE

  The mapping will only succeed if there is a free region of the requested length at the given address *\*addr*.

- VMFS\_ANY\_SPACE

  The mapping will succeed as long as there is a free region.

- VMFS\_SUPER\_SPACE

  The mapping will succeed as long as there is a free region that begins on a superpage boundary. If *object* is non-NULL and is already backed by superpages, then the mapping will require a free region that aligns relative to the existing superpages rather than one beginning on a superpage boundary.

- VMFS\_OPTIMAL\_SPACE

  The mapping will succeed as long as there is a free region. However, if *object* is non-NULL and is already backed by superpages, this strategy will attempt to find a free region aligned relative to the existing superpages.

- VMFS\_ALIGNED\_SPACE(*n*)

  The mapping will succeed as long as there is a free region that aligns on a 2^*n* boundary.

## IMPLEMENTATION NOTES

This function acquires a lock on *map* by calling [vm\_map\_lock(9)](/vm_map_lock/9.md), and holds it until the function returns.

The search for a free region is defined to be first-fit, from the address *addr* onwards.

## RETURN VALUES

The **vm\_map\_find**() function returns KERN\_SUCCESS if the mapping was successfully created. If space could not be found or *find\_space* was VMFS\_NO\_SPACE and the given address, *addr*, was already mapped, KERN\_NO\_SPACE will be returned. If the discovered range turned out to be bogus, KERN\_INVALID\_ADDRESS will be returned.

## SEE ALSO

[vm\_map(9)](/vm_map/9.md), [vm\_map\_findspace(9)](/vm_map_findspace/9.md), [vm\_map\_insert(9)](/vm_map_insert/9.md), [vm\_map\_lock(9)](/vm_map_lock/9.md)

## AUTHORS

This manual page was written by Bruce M Simpson ⟨*bms@spc.org*⟩.