.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "2023-05-26" "PMDK - " "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2020, Intel Corporation
.SH NAME
.PP
\f[B]pmem2_badblock_context_new\f[R](),
\f[B]pmem2_badblock_context_delete\f[R]() - allocate and free a context
for \f[B]pmem2_badblock_next\f[R]() and \f[B]pmem2_badblock_clear\f[R]()
operations
.SH SYNOPSIS
.IP
.nf
\f[C]
#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);
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_badblock_context_new\f[R]() function instantiates a new
(opaque) bad block context structure, \f[I]pmem2_badblock_context\f[R],
which is used to read and clear bad blocks (by
\f[B]pmem2_badblock_next\f[R]() and \f[B]pmem2_badblock_clear\f[R]()).
The function returns the bad block context through the pointer in
\f[I]*bbctx\f[R].
.PP
New bad block context structure is initialized with values read from the
source given as the first argument (\f[I]src\f[R]).
.PP
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.
.PP
The \f[B]pmem2_badblock_context_delete\f[R]() function frees
\f[I]*bbctx\f[R] returned by \f[B]pmem2_badblock_context_new\f[R]() and
sets \f[I]*bbctx\f[R] to NULL.
If \f[I]*bbctx\f[R] is NULL, no operation is performed.
.PP
It is not supported on Windows.
.SH RETURN VALUE
.PP
The \f[B]pmem2_badblock_context_new\f[R]() function returns 0 on success
or a negative error code on failure.
.PP
The \f[B]pmem2_badblock_context_new\f[R]() sets \f[I]*bbctx\f[R] to NULL
on failure.
.PP
The \f[B]pmem2_badblock_context_delete\f[R]() does not return any value.
.SH ERRORS
.PP
The \f[B]pmem2_badblock_context_new\f[R]() can fail with the following
errors:
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_TYPE\f[R] - \f[I]src\f[R] is not a regular
file nor a character device.
.IP \[bu] 2
\f[B]PMEM2_E_DAX_REGION_NOT_FOUND\f[R] - cannot find a DAX region for
the given \f[I]src\f[R].
.IP \[bu] 2
\f[B]PMEM2_E_CANNOT_READ_BOUNDS\f[R] - cannot read offset or size of the
namespace of the given \f[I]src\f[R].
.IP \[bu] 2
\f[B]PMEM2_E_NOSUPP\f[R] - on Windows or when the OS does not support
this functionality
.IP \[bu] 2
\f[B]-ENOMEM\f[R] - out of memory
.IP \[bu] 2
\f[B]-errno\f[R] - set by failing \f[B]ndctl_new\f[R], while trying to
create a new ndctl context.
.IP \[bu] 2
\f[B]-errno\f[R] - set by failing \f[B]fstat\f[R](2), while trying to
validate the file descriptor of \f[I]src\f[R].
.IP \[bu] 2
\f[B]-errno\f[R] - set by failing \f[B]realpath\f[R](3), while trying to
get the canonicalized absolute sysfs pathname of DAX device given in
\f[I]src\f[R].
.IP \[bu] 2
\f[B]-errno\f[R] - set by failing \f[B]open\f[R](2), while trying to
open the FSDAX device matching with the \f[I]src\f[R].
.IP \[bu] 2
\f[B]-errno\f[R] - set by failing \f[B]read\f[R](2), while trying to
read from the FSDAX device matching with the \f[I]src\f[R].
.IP \[bu] 2
\f[B]-errno\f[R] - set by failing \f[B]ndctl_region_get_resource\f[R],
while reading an offset of the region of the given \f[I]src\f[R].
.IP \[bu] 2
\f[B]-errno\f[R] - set by failing \f[B]fiemap ioctl(2)\f[R], while
reading file extents of the given \f[I]src\f[R].
.SH SEE ALSO
.PP
\f[B]pmem2_badblock_next\f[R](3), \f[B]pmem2_badblock_clear\f[R](3),
\f[B]libpmem2\f[R](7) and \f[B]<https://pmem.io>\f[R]