1PMEMPOOL-INFO(1) PMDK Programmer's Manual PMEMPOOL-INFO(1)
2
6 pmempool-info - show information about persistent memory pool
7
9 $ pmempool info [<options>] <file>
10
12 The pmempool invoked with info command analyzes an existing pool creat‐
13 ed by PMDK libraries provided by file parameter. The file can be ei‐
14 ther existing pool file, a part file or a poolset file.
15 The main task of this command is to print all usable information from
17 pool headers and user data in human readable format. It automatically
18 recognizes the pool type by parsing and analyzing the pool header. The
19 recognition is done by checking the signature in the pool header. The
20 main job of info command is to present internal data structures as they
21 are stored in file but not for checking consistency. For this purpose
22 there is the pmempool-check(1) command available.
23 The pmempool with info command analyzes pool file as long as it is pos‐
25 sible regarding correctness of internal meta-data (correct offsets,
26 sizes etc.). If it is not possible to analyze the rest of the file,
27 pmempool exits with error code and prints appropriate error message.
28 Currently there is lack of interprocess synchronization for pool files,
30 so the info command should be invoked off-line. Using pmempool on pool
31 file which may be modified by another process may lead to unexpected
32 errors in pool file.
33 A poolset file passed to pmempool info may contain multiple replicas,
35 also remote ones, but pmempool currently does not read any data from
36 remote replicas. It prints only a remote node address and a remote
37 replica descriptor.
38 pmempool info opens pool file in read-only mode so the file will remain
40 untouched after processing.
41 The info command may collect and print basic statistics about data us‐
43 age. The statistics are specific to the type of pool. See STATISTICS
44 section for details.
45 Although the pool consistency is not checked by the info command, it
47 prints information about checksum errors and/or offsets errors.
48 Common options:
50 By default the info command of pmempool prints information about the
51 most important internal data structures from pool. The particular set
52 of headers and meta-data depend on pool type. The pool type is recog‐
53 nized automatically and appropriate information is displayed in hu‐
54 man-readable format.
55 To force processing specified file(s) as desired pool type use -f op‐
57 tion with appropriate name of pool type. The valid names off pool
58 types are blk, log, obj or btt. This option may be useful when the
59 pool header is corrupted and automatic recognition of pool type fails.
60 -f, --force blk|log|obj|btt
62 Force parsing pool as specified pool type.
64 NOTE: By default only pool headers and internal meta-data are
66 displayed. To display user data use -d option. Using -r option
67 you can specify number of blocks/bytes/data chunks or objects
68 using special text format. See RANGE section for details. The
69 range refers to block numbers in case of pmem blk pool type, to
70 chunk numbers in case of pmem log pool type and to object num‐
71 bers in case of pmem obj pool type. See EXAMPLES section for an
72 example of usage of these options.
73 -d, --data
75 Dump user data in hexadecimal format. In case of pmem blk pool type
77 data is dumped in blocks. In case of pmem log pool type data is dumped
78 as a wholeor in chunks if -w option is used (See Options for PMEMLOG
79 section for details).
80 -r, --range <range>
82 Range of blocks/data chunks/objects/zone headers/chunk headers/lanes.
84 See RANGE section for details about range format.
85 -n, --human
87 Print sizes in human-readable format with appropriate units (e.g. 4k,
89 8M, 16G)
90 -x, --headers-hex
92 Print pool's internal data in mixed format which consists of hexadeci‐
94 mal dump of header's data and parsed format displayed in human-readable
95 format. This allows one to see how data is stored in file.
96 -s, --stats
98 Print pool's statistics. See STATISTICS section for details.
100 -k, --bad-blocks=<yes|no>
102 Print bad blocks found in the pool.
104 -h, --help
106 Display help message and exit.
108 Options for PMEMLOG:
110 -w, --walk <size>
111 Use this option to walk through used data with fixed data chunk size.
113 See pmemlog_walk(3) in libpmemlog(7) for details.
114 Options for PMEMBLK:
116 By default the info command displays the pmemblk header and BTT (Block
117 Translation Table) Info header in case of pmemblk pool type.
118 To display BTT Map and/or BTT FLOG (Free List and Log) use -m and -g
120 options respectively or increase verbosity level.
121 In order to display BTT Info header backup use -B option.
123 -m, --map
125 Print BTT Map entries.
127 -g, --flog
129 Print BTT FLOG entries.
131 -B, --backup
133 Print BTT Info header backup.
135 NOTE: By default the info command displays all data blocks when
137 -d options is used. However it is possible to skip blocks
138 marked with zero and/or error flags. It is also possible to
139 skip blocks which are not marked with any flag. Skipping blocks
140 has impact on blocks ranges (e.g. display 10 blocks marked with
141 error flag in the range from 0 to 10000) and statistics.
142 -z, --skip-zeros
144 Skip blocks marked with zero flag.
146 -e, --skip-error
148 Skip blocks marked with error flag.
150 -u, --skip-no-flag
152 Skip blocks not marked with any flag.
154 Options for PMEMOBJ:
156 By default the info command displays pool header and pmemobj pool de‐
157 scriptor. In order to print information about other data structures
158 one of the following options may be used.
159 -l, --lanes [<range>]
161 Print information about lanes. If range is not specified all lanes are
163 displayed. The range can be specified using -r option right after the
164 -l option. See RANGE section for details about range format.
165 -R, --recovery
167 Print information about only those lanes which require recovery
169 process. This option requires -l, –lanes option.
170 -O, --object-store
172 Print information about all allocated objects.
174 -t, --types <range>
176 Print information about allocated objects only from specified range of
178 type numbers. If -s, –stats option is specified the objects statistics
179 refer to objects from specified range of type numbers. This option re‐
180 quires -O, –object-store or -s, –stats options. See RANGE section for
181 details about range format.
182 -E, --no-empty
184 Ignore empty lists of objects. This option requires -O, –object-store
186 option.
187 -o, --root
189 Print information about a root object.
191 -A, --alloc-header
193 Print object's allocation header. This option requires -O, –ob‐
195 ject-store or -l, –lanes or -o, –root options.
196 -a, --oob-header
198 Print object's out of band header. This option requires -O, –ob‐
200 ject-store or -l, –lanes or -o, –root options.
201 -H, --heap
203 Print information about pmemobj heap. By default only a heap header is
205 displayed.
206 -Z, --zones
208 If the -H, –heap option is used, print information about zones from
210 specified range. If the -O, –object-store option is used, print infor‐
211 mation about objects only from specified range of zones. This option
212 requires -O, –object-store, -H, –heap or -s, –stats options. The range
213 can be specified using -r option right after the -Z option. See RANGE
214 section for details about range format.
215 -C, --chunks [<range>]
217 If the -H, –heap option is used, print information about chunks from
219 specified range. By default information about chunks of types used ,
220 free and run are displayed. If the -O, –object-store option is used,
221 print information about objects from specified range of chunks within a
222 zone. This option requires -O, –object-store, -H, –heap or -s, –stats
223 options. The range can be specified using -r option right after the -C
224 option. See RANGE section for details about range format.
225 -T, --chunk-type used,free,run,footer
227 Print only specified type(s) of chunks. The multiple types may be
229 specified separated by comma. This option requires -H, –heap and -C,
230 –chunks options.
231 -b, --bitmap
233 Print bitmap of used blocks in chunks of type run. This option re‐
235 quires -H, –heap and -C, –chunks options.
236 -p, --replica <num>
238 Print information from <num> replica. The 0 value means the master
240 pool file.
241
243 Using -r, –range option it is possible to dump only a range of user da‐
244 ta. This section describes valid format of <range> string.
245 You can specify multiple ranges separated by commas.
247 <first>-<last>
249 All blocks/bytes/data chunks from <first> to <last> will be dumped.
251 -<last>
253 All blocks/bytes/data chunks up to <last> will be dumped.
255 <first>-
257 All blocks/bytes/data chunks starting from <first> will be dumped.
259 <number>
261 Only <number> block/byte/data chunk will be dumped.
263
265 Below is the description of statistical measures for specific pool
266 types.
267 PMEMLOG
269 • Total - Total space in pool.
270 • Available - Size and percentage of available space.
272 • Used - Size and percentage of used space.
274 PMEMBLK
276 • Total blocks - Total number of blocks in pool.
277 • Zeroed blocks - Number and percentage of blocks marked with zero
279 flag.
280 • Error blocks - Number and percentage of blocks marked with error
282 flag.
283 • Blocks without any flag - Number and percentage of blocks not marked
285 with any flag.
286 NOTE: In case of pmemblk, statistics are evaluated for blocks which
288 meet requirements regarding: range of blocks (-r option), skipped
289 types of blocks (-z, -e, -u options).
290 PMEMOBJ
292 • Object store
293 • Number of objects - Total number of objects and number of objects
295 per type number.
296 • Number of bytes - Total number of bytes and number of bytes per
298 type number.
299 • Heap
301 • Number of zones - Total number of zones in the pool.
303 • Number of used zones - Number of used zones in the pool.
305 • Zone The zone's statistics are presented for each zone separately and
307 the aggregated results from all zones.
308 • Number of chunks - Total number of chunks in the zone and number of
310 chunks of specified type.
311 • Chunks size - Total size of all chunks in the zone and sum of sizes
313 of chunks of specified type.
314 • Allocation classes
316 • Units - Total number of units of specified class.
318 • Used units - Number of used units of specified class.
320 • Bytes - Total number of bytes of specified class.
322 • Used bytes - Number of used bytes of specified class.
324 • Total bytes - Total number of bytes of all classes.
326 • Total used bytes - Total number of used bytes of all classes.
328
330 $ pmempool info ./pmemblk
331 Parse and print information about “pmemblk” pool file.
333 $ pmempool info -f blk ./pmempool
335 Force parsing “pmempool” file as pmemblk pool type.
337 $ pmempool info -d ./pmemlog
339 Print information and data in hexadecimal dump format for file “pmem‐
341 log”.
342 $ pmempool info -d -r10-100 -eu ./pmemblk
344 Print information from “pmemblk” file. Dump data blocks from 10 to
346 100, skip blocks marked with error flag and not marked with any flag.
347
349 pmempool(1), libpmemblk(7), libpmemlog(7), libpmemobj(7) and
350 <https://pmem.io>
351PMDK - pmem Tools version 1.4 2022-05-24 PMEMPOOL-INFO(1)