1PMEM2_BADBLOCK_CONTEXT_NEW(3P)MDK Programmer's ManuaPlMEM2_BADBLOCK_CONTEXT_NEW(3)
2
3
4

NAME

6       pmem2_badblock_context_new(),  pmem2_badblock_context_delete()  - allo‐
7       cate and  free  a  context  for  pmem2_badblock_next()  and  pmem2_bad‐
8       block_clear() operations
9

SYNOPSIS

11              #include <libpmem2.h>
12
13              struct pmem2_source;
14              struct pmem2_badblock_context;
15
16              int pmem2_badblock_context_new(
17                      struct pmem2_badblock_context **bbctx,
18                      const struct pmem2_source *src);
19
20              void pmem2_badblock_context_delete(
21                      struct pmem2_badblock_context **bbctx);
22

DESCRIPTION

24       The  pmem2_badblock_context_new()  function instantiates a new (opaque)
25       bad block context structure, pmem2_badblock_context, which is  used  to
26       read  and  clear  bad  blocks  (by pmem2_badblock_next() and pmem2_bad‐
27       block_clear()).  The function returns the bad block context through the
28       pointer in *bbctx.
29
30       New  bad  block  context structure is initialized with values read from
31       the source given as the first argument (src).
32
33       A bad block is an uncorrectable media error - a part of a storage media
34       that  is  either  inaccessible  or unwritable due to permanent physical
35       damage.  In case of memory-mapped I/O, if a  process  tries  to  access
36       (read  or write) the corrupted block, it will be terminated by the SIG‐
37       BUS signal.
38
39       The pmem2_badblock_context_delete() function frees *bbctx  returned  by
40       pmem2_badblock_context_new()  and  sets  *bbctx  to NULL.  If *bbctx is
41       NULL, no operation is performed.
42
43       It is not supported on Windows.
44

RETURN VALUE

46       The pmem2_badblock_context_new() function returns 0  on  success  or  a
47       negative error code on failure.
48
49       The pmem2_badblock_context_new() sets *bbctx to NULL on failure.
50
51       The pmem2_badblock_context_delete() does not return any value.
52

ERRORS

54       The pmem2_badblock_context_new() can fail with the following errors:
55
56       • PMEM2_E_INVALID_FILE_TYPE - src is not a regular file nor a character
57         device.
58
59       • PMEM2_E_DAX_REGION_NOT_FOUND - cannot find a DAX region for the given
60         src.
61
62       • PMEM2_E_CANNOT_READ_BOUNDS  - cannot read offset or size of the name‐
63         space of the given src.
64
65       • PMEM2_E_NOSUPP - on Windows or when the  OS  does  not  support  this
66         functionality
67
68       • -ENOMEM - out of memory
69
70       • -errno - set by failing ndctl_new, while trying to create a new ndctl
71         context.
72
73       • -errno - set by failing fstat(2), while trying to validate  the  file
74         descriptor of src.
75
76       • -errno  - set by failing realpath(3), while trying to get the canoni‐
77         calized absolute sysfs pathname of DAX device given in src.
78
79       • -errno - set by failing open(2), while trying to open the  FSDAX  de‐
80         vice matching with the src.
81
82       • -errno  - set by failing read(2), while trying to read from the FSDAX
83         device matching with the src.
84
85       • -errno - set by failing ndctl_region_get_resource, while  reading  an
86         offset of the region of the given src.
87
88       • -errno  -  set by failing fiemap ioctl(2), while reading file extents
89         of the given src.
90

SEE ALSO

92       pmem2_badblock_next(3),   pmem2_badblock_clear(3),   libpmem2(7)    and
93       <https://pmem.io>
94
95
96
97PMDK - pmem2 API version 1.0      2021-09-24     PMEM2_BADBLOCK_CONTEXT_NEW(3)
Impressum