1() PMDK Programmer's Manual ()
2
6 pmempool-info - show information about persistent memory pool
7
9 $ pmempool info [<options>] <file>
10
12 NOTICE:
13 The libpmemblk and libpmemlog libraries are deprecated (this affects
15 pool types blk, btt and log) since PMDK 1.13.0 release.
16
18 The pmempool invoked with info command analyzes an existing pool creat‐
19 ed by PMDK libraries provided by file parameter. The file can be ei‐
20 ther existing pool file, a part file or a poolset file.
21 The main task of this command is to print all usable information from
23 pool headers and user data in human readable format. It automatically
24 recognizes the pool type by parsing and analyzing the pool header. The
25 recognition is done by checking the signature in the pool header. The
26 main job of info command is to present internal data structures as they
27 are stored in file but not for checking consistency. For this purpose
28 there is the pmempool-check(1) command available.
29 The pmempool with info command analyzes pool file as long as it is pos‐
31 sible regarding correctness of internal meta-data (correct offsets,
32 sizes etc.). If it is not possible to analyze the rest of the file,
33 pmempool exits with error code and prints appropriate error message.
34 Currently there is lack of interprocess synchronization for pool files,
36 so the info command should be invoked off-line. Using pmempool on pool
37 file which may be modified by another process may lead to unexpected
38 errors in pool file.
39 pmempool info opens pool file in read-only mode so the file will remain
41 untouched after processing.
42 The info command may collect and print basic statistics about data us‐
44 age. The statistics are specific to the type of pool. See STATISTICS
45 section for details.
46 Although the pool consistency is not checked by the info command, it
48 prints information about checksum errors and/or offsets errors.
49 Common options:
51 By default the info command of pmempool prints information about the
52 most important internal data structures from pool. The particular set
53 of headers and meta-data depend on pool type. The pool type is recog‐
54 nized automatically and appropriate information is displayed in human-
55 readable format.
56 To force processing specified file(s) as desired pool type use -f op‐
58 tion with appropriate name of pool type. The valid names off pool
59 types are blk, log, obj or btt. This option may be useful when the
60 pool header is corrupted and automatic recognition of pool type fails.
61 -f, --force blk|log|obj|btt
63 Force parsing pool as specified pool type.
65 NOTE: By default only pool headers and internal meta-data are
67 displayed. To display user data use -d option. Using -r option
68 you can specify number of blocks/bytes/data chunks or objects
69 using special text format. See RANGE section for details. The
70 range refers to block numbers in case of pmem blk pool type, to
71 chunk numbers in case of pmem log pool type and to object num‐
72 bers in case of pmem obj pool type. See EXAMPLES section for an
73 example of usage of these options.
74 -d, --data
76 Dump user data in hexadecimal format. In case of pmem blk pool type
78 data is dumped in blocks. In case of pmem log pool type data is dumped
79 as a wholeor in chunks if -w option is used (See Options for PMEMLOG
80 section for details).
81 -r, --range <range>
83 Range of blocks/data chunks/objects/zone headers/chunk headers/lanes.
85 See RANGE section for details about range format.
86 -n, --human
88 Print sizes in human-readable format with appropriate units (e.g. 4k,
90 8M, 16G)
91 -x, --headers-hex
93 Print pool’s internal data in mixed format which consists of hexadeci‐
95 mal dump of header’s data and parsed format displayed in human-readable
96 format. This allows one to see how data is stored in file.
97 -s, --stats
99 Print pool’s statistics. See STATISTICS section for details.
101 -k, --bad-blocks=<yes|no>
103 Print bad blocks found in the pool.
105 -h, --help
107 Display help message and exit.
109 Options for PMEMLOG:
111 -w, --walk <size>
112 Use this option to walk through used data with fixed data chunk size.
114 See pmemlog_walk(3) in libpmemlog(7) for details.
115 Options for PMEMBLK:
117 By default the info command displays the pmemblk header and BTT (Block
118 Translation Table) Info header in case of pmemblk pool type.
119 To display BTT Map and/or BTT FLOG (Free List and Log) use -m and -g
121 options respectively or increase verbosity level.
122 In order to display BTT Info header backup use -B option.
124 -m, --map
126 Print BTT Map entries.
128 -g, --flog
130 Print BTT FLOG entries.
132 -B, --backup
134 Print BTT Info header backup.
136 NOTE: By default the info command displays all data blocks when
138 -d options is used. However it is possible to skip blocks
139 marked with zero and/or error flags. It is also possible to
140 skip blocks which are not marked with any flag. Skipping blocks
141 has impact on blocks ranges (e.g. display 10 blocks marked with
142 error flag in the range from 0 to 10000) and statistics.
143 -z, --skip-zeros
145 Skip blocks marked with zero flag.
147 -e, --skip-error
149 Skip blocks marked with error flag.
151 -u, --skip-no-flag
153 Skip blocks not marked with any flag.
155 Options for PMEMOBJ:
157 By default the info command displays pool header and pmemobj pool de‐
158 scriptor. In order to print information about other data structures
159 one of the following options may be used.
160 -l, --lanes [<range>]
162 Print information about lanes. If range is not specified all lanes are
164 displayed. The range can be specified using -r option right after the
165 -l option. See RANGE section for details about range format.
166 -R, --recovery
168 Print information about only those lanes which require recovery
170 process. This option requires -l, –lanes option.
171 -O, --object-store
173 Print information about all allocated objects.
175 -t, --types <range>
177 Print information about allocated objects only from specified range of
179 type numbers. If -s, –stats option is specified the objects statistics
180 refer to objects from specified range of type numbers. This option re‐
181 quires -O, –object-store or -s, –stats options. See RANGE section for
182 details about range format.
183 -E, --no-empty
185 Ignore empty lists of objects. This option requires -O, –object-store
187 option.
188 -o, --root
190 Print information about a root object.
192 -A, --alloc-header
194 Print object’s allocation header. This option requires -O, –object-
196 store or -l, –lanes or -o, –root options.
197 -a, --oob-header
199 Print object’s out of band header. This option requires -O, –object-
201 store or -l, –lanes or -o, –root options.
202 -H, --heap
204 Print information about pmemobj heap. By default only a heap header is
206 displayed.
207 -Z, --zones
209 If the -H, –heap option is used, print information about zones from
211 specified range. If the -O, –object-store option is used, print infor‐
212 mation about objects only from specified range of zones. This option
213 requires -O, –object-store, -H, –heap or -s, –stats options. The range
214 can be specified using -r option right after the -Z option. See RANGE
215 section for details about range format.
216 -C, --chunks [<range>]
218 If the -H, –heap option is used, print information about chunks from
220 specified range. By default information about chunks of types used ,
221 free and run are displayed. If the -O, –object-store option is used,
222 print information about objects from specified range of chunks within a
223 zone. This option requires -O, –object-store, -H, –heap or -s, –stats
224 options. The range can be specified using -r option right after the -C
225 option. See RANGE section for details about range format.
226 -T, --chunk-type used,free,run,footer
228 Print only specified type(s) of chunks. The multiple types may be
230 specified separated by comma. This option requires -H, –heap and -C,
231 –chunks options.
232 -b, --bitmap
234 Print bitmap of used blocks in chunks of type run. This option re‐
236 quires -H, –heap and -C, –chunks options.
237 -p, --replica <num>
239 Print information from <num> replica. The 0 value means the master
241 pool file.
242
244 Using -r, –range option it is possible to dump only a range of user da‐
245 ta. This section describes valid format of <range> string.
246 You can specify multiple ranges separated by commas.
248 <first>-<last>
250 All blocks/bytes/data chunks from <first> to <last> will be dumped.
252 -<last>
254 All blocks/bytes/data chunks up to <last> will be dumped.
256 <first>-
258 All blocks/bytes/data chunks starting from <first> will be dumped.
260 <number>
262 Only <number> block/byte/data chunk will be dumped.
264
266 Below is the description of statistical measures for specific pool
267 types.
268 PMEMLOG
270 • Total - Total space in pool.
271 • Available - Size and percentage of available space.
273 • Used - Size and percentage of used space.
275 PMEMBLK
277 • Total blocks - Total number of blocks in pool.
278 • Zeroed blocks - Number and percentage of blocks marked with zero
280 flag.
281 • Error blocks - Number and percentage of blocks marked with error
283 flag.
284 • Blocks without any flag - Number and percentage of blocks not marked
286 with any flag.
287 NOTE: In case of pmemblk, statistics are evaluated for blocks which
289 meet requirements regarding: range of blocks (-r option), skipped
290 types of blocks (-z, -e, -u options).
291 PMEMOBJ
293 • Object store
294 • Number of objects - Total number of objects and number of objects
296 per type number.
297 • Number of bytes - Total number of bytes and number of bytes per
299 type number.
300 • Heap
302 • Number of zones - Total number of zones in the pool.
304 • Number of used zones - Number of used zones in the pool.
306 • Zone The zone’s statistics are presented for each zone separately and
308 the aggregated results from all zones.
309 • Number of chunks - Total number of chunks in the zone and number of
311 chunks of specified type.
312 • Chunks size - Total size of all chunks in the zone and sum of sizes
314 of chunks of specified type.
315 • Allocation classes
317 • Units - Total number of units of specified class.
319 • Used units - Number of used units of specified class.
321 • Bytes - Total number of bytes of specified class.
323 • Used bytes - Number of used bytes of specified class.
325 • Total bytes - Total number of bytes of all classes.
327 • Total used bytes - Total number of used bytes of all classes.
329
331 $ pmempool info ./pmemblk
332 Parse and print information about “pmemblk” pool file.
334 $ pmempool info -f blk ./pmempool
336 Force parsing “pmempool” file as pmemblk pool type.
338 $ pmempool info -d ./pmemlog
340 Print information and data in hexadecimal dump format for file “pmem‐
342 log”.
343 $ pmempool info -d -r10-100 -eu ./pmemblk
345 Print information from “pmemblk” file. Dump data blocks from 10 to
347 100, skip blocks marked with error flag and not marked with any flag.
348
350 pmempool(1), libpmemblk(7), libpmemlog(7), libpmemobj(7) and
351 <https://pmem.io>
352PMDK - 2023-06-05 ()