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), while trying to validate the file descriptor of src.

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

       • -errno - set by failing open(2), while trying to open the FSDAX device matching with the
         src.

       • -errno  -  set  by  failing read(2), 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), while reading file extents of the given src.

SEE ALSO

       pmem2_badblock_next(3), pmem2_badblock_clear(3), libpmem2(7) and <https://pmem.io>