.\" Automatically generated by Pandoc 2.0.6
.\"
.TH "PMEM2_BADBLOCK_CONTEXT_NEW" "3" "2022-08-25" "PMDK - pmem2 API version 1.0" "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[](),
\f[B]pmem2_badblock_context_delete\f[]() \- allocate and free a context
for \f[B]pmem2_badblock_next\f[]() and \f[B]pmem2_badblock_clear\f[]()
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[]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmem2_badblock_context_new\f[]() function instantiates a new
(opaque) bad block context structure, \f[I]pmem2_badblock_context\f[],
which is used to read and clear bad blocks (by
\f[B]pmem2_badblock_next\f[]() and \f[B]pmem2_badblock_clear\f[]()).
The function returns the bad block context through the pointer in
\f[I]*bbctx\f[].
.PP
New bad block context structure is initialized with values read from the
source given as the first argument (\f[I]src\f[]).
.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[]() function frees
\f[I]*bbctx\f[] returned by \f[B]pmem2_badblock_context_new\f[]() and
sets \f[I]*bbctx\f[] to NULL.
If \f[I]*bbctx\f[] 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[]() function returns 0 on success
or a negative error code on failure.
.PP
The \f[B]pmem2_badblock_context_new\f[]() sets \f[I]*bbctx\f[] to NULL
on failure.
.PP
The \f[B]pmem2_badblock_context_delete\f[]() does not return any value.
.SH ERRORS
.PP
The \f[B]pmem2_badblock_context_new\f[]() can fail with the following
errors:
.IP \[bu] 2
\f[B]PMEM2_E_INVALID_FILE_TYPE\f[] \- \f[I]src\f[] is not a regular file
nor a character device.
.IP \[bu] 2
\f[B]PMEM2_E_DAX_REGION_NOT_FOUND\f[] \- cannot find a DAX region for
the given \f[I]src\f[].
.IP \[bu] 2
\f[B]PMEM2_E_CANNOT_READ_BOUNDS\f[] \- cannot read offset or size of the
namespace of the given \f[I]src\f[].
.IP \[bu] 2
\f[B]PMEM2_E_NOSUPP\f[] \- on Windows or when the OS does not support
this functionality
.IP \[bu] 2
\f[B]\-ENOMEM\f[] \- out of memory
.IP \[bu] 2
\f[B]\-errno\f[] \- set by failing \f[B]ndctl_new\f[], while trying to
create a new ndctl context.
.IP \[bu] 2
\f[B]\-errno\f[] \- set by failing \f[B]fstat\f[](2), while trying to
validate the file descriptor of \f[I]src\f[].
.IP \[bu] 2
\f[B]\-errno\f[] \- set by failing \f[B]realpath\f[](3), while trying to
get the canonicalized absolute sysfs pathname of DAX device given in
\f[I]src\f[].
.IP \[bu] 2
\f[B]\-errno\f[] \- set by failing \f[B]open\f[](2), while trying to
open the FSDAX device matching with the \f[I]src\f[].
.IP \[bu] 2
\f[B]\-errno\f[] \- set by failing \f[B]read\f[](2), while trying to
read from the FSDAX device matching with the \f[I]src\f[].
.IP \[bu] 2
\f[B]\-errno\f[] \- set by failing \f[B]ndctl_region_get_resource\f[],
while reading an offset of the region of the given \f[I]src\f[].
.IP \[bu] 2
\f[B]\-errno\f[] \- set by failing \f[B]fiemap ioctl(2)\f[], while
reading file extents of the given \f[I]src\f[].
.SH SEE ALSO
.PP
\f[B]pmem2_badblock_next\f[](3), \f[B]pmem2_badblock_clear\f[](3),
\f[B]libpmem2\f[](7) and \f[B]<https://pmem.io>\f[]