---
name: "pmem2_map_new"
section: "3"
platform: "linux"
package: "libpmem2-dev"
version: "1.13.1-1.1+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/pmem2_map_new"
---

# pmem2\_map\_new(3)

creates a mapping

## NAME

**pmem2\_map\_new**() - creates a mapping

## SYNOPSIS

-

  ```
  #include <libpmem2.h>
  struct pmem2_config;
  struct pmem2_source;
  struct pmem2_map;
  int pmem2_map_new(struct pmem2_map **map_ptr, const struct pmem2_config *config,
          const struct pmem2_source *source);
  ```

## DESCRIPTION

The **pmem2\_map\_new**() function creates a new mapping in the virtual address space of the calling process. This function requires a configuration *config* of the mapping and the data source *source*.

Optionally, the mapping can be created at the offset of the virtual memory reservation set in the configuration *config*. See [**pmem2\_config\_set\_vm\_reservation**(3)](/pmem2_config_set_vm_reservation/3.md) for details.

For a mapping to succeed, the *config* structure must have the granularity parameter set to the appropriate level. See [**pmem2\_config\_set\_required\_store\_granularity**(3)](/pmem2_config_set_required_store_granularity/3.md) and [**libpmem2**(7)](/libpmem2/7.md) for more details.

If the **pmem2\_map\_new**() function succeeds in creating a new mapping it instantiates a new \*struct pmem2\_map\*\* object describing the mapping. The pointer to this newly created object is stored in the user-provided variable passed via the *map\_ptr* pointer. If the mapping fails the variable pointed by *map\_ptr* will contain a NULL value and appropriate error value will be returned. For a list of possible return values please see RETURN VALUE.

All *struct pmem2\_map* objects created via the **pmem2\_map\_new**() function have to be destroyed using the **pmem2\_map\_delete**() function. For details please see [**pmem2\_map\_delete**(3)](/pmem2_map_delete/3.md) manual page.

## RETURN VALUE

The **pmem2\_map\_new**() function returns 0 on success or a negative error code on failure.

## ERRORS

The **pmem2\_map\_new**() can fail with the following errors:

- •

  **PMEM2\_E\_GRANULARITY\_NOT\_SET** - the store granularity for the mapping was not set in the provided *config* structure. Please see [**pmem2\_config\_set\_required\_store\_granularity**(3)](/pmem2_config_set_required_store_granularity/3.md) and [**libpmem2**(7)](/libpmem2/7.md).

- •

  **PMEM2\_E\_MAP\_RANGE** - *offset* + *length* is too big to represent it using *size\_t* data type

- •

  **PMEM2\_E\_MAP\_RANGE** - end of the mapping (*offset* + *length*) is outside of the file. The file is too small.

- •

  **PMEM2\_E\_SOURCE\_EMPTY** - mapped file has size equal to 0.

- •

  **PMEM2\_E\_MAPPING\_EXISTS** - if the object exists before the function call. For details please see **CreateFileMapping**() manual pages. (Windows only)

- •

  **PMEM2\_E\_OFFSET\_UNALIGNED** - argument unaligned, offset is not a multiple of the alignment required for specific *\*source*. Please see [**pmem2\_source\_alignment**(3)](/pmem2_source_alignment/3.md).

- •

  **PMEM2\_E\_LENGTH\_UNALIGNED** - argument unaligned, length is not a multiple of the alignment required for specific *\*source*. Please see [**pmem2\_source\_alignment**(3)](/pmem2_source_alignment/3.md).

- •

  **PMEM2\_E\_SRC\_DEVDAX\_PRIVATE** - device DAX mapped with MAP\_PRIVATE. (Linux only)

- •

  **PMEM2\_E\_ADDRESS\_UNALIGNED** - when mapping device DAX to a virtual memory reservation and the base mapping address (reservation address + reservation offset) is not aligned to the device DAX granularity. Please see [**pmem2\_config\_set\_vm\_reservation**(3)](/pmem2_config_set_vm_reservation/3.md). (Linux only)

- •

  **PMEM2\_E\_ADDRESS\_UNALIGNED** - when mapping to a virtual memory reservation and the region for the mapping exceeds reservation size. Please see [**pmem2\_config\_set\_vm\_reservation**(3)](/pmem2_config_set_vm_reservation/3.md).

- •

  **PMEM2\_E\_NOSUPP** - when config-provided protection flags combination is not supported.

- •

  **PMEM2\_E\_NO\_ACCESS** - there is a conflict between mapping protection and file opening mode.

It can also return **-EACCES**, **-EAGAIN**, **-EBADF**, **-ENFILE**, **-ENODEV**, **-ENOMEM**, **-EPERM**, **-ETXTBSY** from the underlying [**mmap**(2)](/mmap/2.md) function. It is used with and without **MAP\_ANONYMOUS**.

**-EACCES** may be returned only if the file descriptor points to an append-only file.

It can also return all errors from the underlying **pmem2\_source\_size**() and **pmem2\_source\_alignment**() functions.

## SEE ALSO

[**mmap**(2)](/mmap/2.md), **open**(3), [**pmem2\_config\_set\_required\_store\_granularity**(3)](/pmem2_config_set_required_store_granularity/3.md), [**pmem2\_source\_alignment**(3)](/pmem2_source_alignment/3.md), [**pmem2\_source\_from\_fd**(3)](/pmem2_source_from_fd/3.md), [**pmem2\_source\_size**(3)](/pmem2_source_size/3.md), [**pmem2\_map\_delete**(3)](/pmem2_map_delete/3.md), [**pmem2\_config\_set\_vm\_reservation**(3)](/pmem2_config_set_vm_reservation/3.md), [**libpmem2**(7)](/libpmem2/7.md) and **\<https://pmem.io\>**