---
name: "pmem2_badblock_context_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_badblock_context_new"
---

# pmem2\_badblock\_context\_new(3)

allocate and free a context for pmem2\_badblock\_next() and pmem2\_badblock\_clear() operations

## NAME

**pmem2\_badblock\_context\_new**(), **pmem2\_badblock\_context\_delete**() - allocate and free a context for **pmem2\_badblock\_next**() and **pmem2\_badblock\_clear**() operations

## SYNOPSIS

-

  ```
  #include <libpmem2.h>
  struct pmem2_source;
  struct pmem2_badblock_context;
  int pmem2_badblock_context_new(
          struct pmem2_badblock_context **bbctx,
          const struct pmem2_source *src);
  void pmem2_badblock_context_delete(
          struct pmem2_badblock_context **bbctx);
  ```

## DESCRIPTION

The **pmem2\_badblock\_context\_new**() function instantiates a new (opaque) bad block context structure, *pmem2\_badblock\_context*, which is used to read and clear bad blocks (by **pmem2\_badblock\_next**() and **pmem2\_badblock\_clear**()). The function returns the bad block context through the pointer in *\*bbctx*.

New bad block context structure is initialized with values read from the source given as the first argument (*src*).

A bad block is an uncorrectable media error - a part of a storage media that is either inaccessible or unwritable due to permanent physical damage. In case of memory-mapped I/O, if a process tries to access (read or write) the corrupted block, it will be terminated by the SIGBUS signal.

The **pmem2\_badblock\_context\_delete**() function frees *\*bbctx* returned by **pmem2\_badblock\_context\_new**() and sets *\*bbctx* to NULL. If *\*bbctx* is NULL, no operation is performed.

It is not supported on Windows.

## RETURN VALUE

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

The **pmem2\_badblock\_context\_new**() sets *\*bbctx* to NULL on failure.

The **pmem2\_badblock\_context\_delete**() does not return any value.

## ERRORS

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

- •

  **PMEM2\_E\_INVALID\_FILE\_TYPE** - *src* is not a regular file nor a character device.

- •

  **PMEM2\_E\_DAX\_REGION\_NOT\_FOUND** - cannot find a DAX region for the given *src*.

- •

  **PMEM2\_E\_CANNOT\_READ\_BOUNDS** - cannot read offset or size of the namespace of the given *src*.

- •

  **PMEM2\_E\_NOSUPP** - on Windows or when the OS does not support this functionality

- •

  **-ENOMEM** - out of memory

- •

  **-errno** - set by failing **ndctl\_new**, while trying to create a new ndctl context.

- •

  **-errno** - set by failing [**fstat**(2)](/fstat/2.md), while trying to validate the file descriptor of *src*.

- •

  **-errno** - set by failing [**realpath**(3)](/realpath/3.md), while trying to get the canonicalized absolute sysfs pathname of DAX device given in *src*.

- •

  **-errno** - set by failing [**open**(2)](/open/2.md), while trying to open the FSDAX device matching with the *src*.

- •

  **-errno** - set by failing [**read**(2)](/read/2.md), while trying to read from the FSDAX device matching with the *src*.

- •

  **-errno** - set by failing **ndctl\_region\_get\_resource**, while reading an offset of the region of the given *src*.

- •

  **-errno** - set by failing **fiemap [ioctl(2)](/ioctl/2.md)**, while reading file extents of the given *src*.

## SEE ALSO

[**pmem2\_badblock\_next**(3)](/pmem2_badblock_next/3.md), [**pmem2\_badblock\_clear**(3)](/pmem2_badblock_clear/3.md), [**libpmem2**(7)](/libpmem2/7.md) and **\<https://pmem.io\>**