1PMEM2_BADBLOCK_CONTEXT_NEW(3P)MDK Programmer's ManuaPlMEM2_BADBLOCK_CONTEXT_NEW(3)
2
3
4
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
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
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
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
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
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 2022-05-24 PMEM2_BADBLOCK_CONTEXT_NEW(3)