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 to see how data is stored in file.
96 -s, --stats
98 Print pool's statistics. See STATISTICS section for details.
100 -h, --help
102 Display help message and exit.
104 Options for PMEMLOG:
106 -w, --walk <size>
107 Use this option to walk through used data with fixed data chunk size.
109 See pmemlog_walk(3) in libpmemlog(7) for details.
110 Options for PMEMBLK:
112 By default the info command displays the pmemblk header and BTT (Block
113 Translation Table) Info header in case of pmemblk pool type.
114 To display BTT Map and/or BTT FLOG (Free List and Log) use -m and -g
116 options respectively or increase verbosity level.
117 In order to display BTT Info header backup use -B option.
119 -m, --map
121 Print BTT Map entries.
123 -g, --flog
125 Print BTT FLOG entries.
127 -B, --backup
129 Print BTT Info header backup.
131 NOTE: By default the info command displays all data blocks when
133 -d options is used. However it is possible to skip blocks
134 marked with zero and/or error flags. It is also possible to
135 skip blocks which are not marked with any flag. Skipping blocks
136 has impact on blocks ranges (e.g. display 10 blocks marked with
137 error flag in the range from 0 to 10000) and statistics.
138 -z, --skip-zeros
140 Skip blocks marked with zero flag.
142 -e, --skip-error
144 Skip blocks marked with error flag.
146 -u, --skip-no-flag
148 Skip blocks not marked with any flag.
150 Options for PMEMOBJ:
152 By default the info command displays pool header and pmemobj pool de‐
153 scriptor. In order to print information about other data structures
154 one of the following options may be used.
155 -l, --lanes [<range>]
157 Print information about lanes. If range is not specified all lanes are
159 displayed. The range can be specified using -r option right after the
160 -l option. See RANGE section for details about range format.
161 -R, --recovery
163 Print information about only those lanes which require recovery
165 process. This option requires -l, --lanes option.
166 -S, --section tx,allocator,list
168 Print information only about specified sections from lane. The section
170 types may be separated by comma. This option requires -l, --lanes op‐
171 tion.
172 -O, --object-store
174 Print information about all allocated objects.
176 -t, --types <range>
178 Print information about allocated objects only from specified range of
180 type numbers. If -s, --stats option is specified the objects statis‐
181 tics refer to objects from specified range of type numbers. This op‐
182 tion requires -O, --object-store or -s, --stats options. See RANGE
183 section for details about range format.
184 -E, --no-empty
186 Ignore empty lists of objects. This option requires -O, --object-store
188 option.
189 -o, --root
191 Print information about a root object.
193 -A, --alloc-header
195 Print object's allocation header. This option requires -O, --ob‐
197 ject-store or -l, --lanes or -o, --root options.
198 -a, --oob-header
200 Print object's out of band header. This option requires -O, --ob‐
202 ject-store or -l, --lanes or -o, --root options.
203 -H, --heap
205 Print information about pmemobj heap. By default only a heap header is
207 displayed.
208 -Z, --zones
210 If the -H, --heap option is used, print information about zones from
212 specified range. If the -O, --object-store option is used, print in‐
213 formation about objects only from specified range of zones. This op‐
214 tion requires -O, --object-store, -H, --heap or -s, --stats options.
215 The range can be specified using -r option right after the -Z option.
216 See RANGE section for details about range format.
217 -C, --chunks [<range>]
219 If the -H, --heap option is used, print information about chunks from
221 specified range. By default information about chunks of types used ,
222 free and run are displayed. If the -O, --object-store option is used,
223 print information about objects from specified range of chunks within a
224 zone. This option requires -O, --object-store, -H, --heap or -s,
225 --stats options. The range can be specified using -r option right af‐
226 ter the -C option. See RANGE section for details about range format.
227 -T, --chunk-type used,free,run,footer
229 Print only specified type(s) of chunks. The multiple types may be
231 specified separated by comma. This option requires -H, --heap and -C,
232 --chunks options.
233 -b, --bitmap
235 Print bitmap of used blocks in chunks of type run. This option re‐
237 quires -H, --heap and -C, --chunks options.
238 -p, --replica <num>
240 Print information from <num> replica. The 0 value means the master
242 pool file.
243
245 Using -r, --range option it is possible to dump only a range of user
246 data. This section describes valid format of <range> string.
247 You can specify multiple ranges separated by commas.
249 <first>-<last>
251 All blocks/bytes/data chunks from <first> to <last> will be dumped.
253 -<last>
255 All blocks/bytes/data chunks up to <last> will be dumped.
257 <first>-
259 All blocks/bytes/data chunks starting from <first> will be dumped.
261 <number>
263 Only <number> block/byte/data chunk will be dumped.
265
267 Below is the description of statistical measures for specific pool
268 types.
269 PMEMLOG
271 · Total - Total space in pool.
272 · Available - Size and percentage of available space.
274 · Used - Size and percentage of used space.
276 PMEMBLK
278 · Total blocks - Total number of blocks in pool.
279 · Zeroed blocks - Number and percentage of blocks marked with zero
281 flag.
282 · Error blocks - Number and percentage of blocks marked with error
284 flag.
285 · Blocks without any flag - Number and percentage of blocks not marked
287 with any flag.
288 NOTE: In case of pmemblk, statistics are evaluated for blocks which
290 meet requirements regarding: range of blocks (-r option), skipped
291 types of blocks (-z, -e, -u options).
292 PMEMOBJ
294 · Object store
295 · Number of objects - Total number of objects and number of objects per
297 type number.
298 · Number of bytes - Total number of bytes and number of bytes per type
300 number.
301 · Heap
303 · Number of zones - Total number of zones in the pool.
305 · Number of used zones - Number of used zones in the pool.
307 · Zone The zone's statistics are presented for each zone separately and
309 the aggregated results from all zones.
310 · Number of chunks - Total number of chunks in the zone and number of
312 chunks of specified type.
313 · Chunks size - Total size of all chunks in the zone and sum of sizes
315 of chunks of specified type.
316 · Allocation classes
318 · Units - Total number of units of specified class.
320 · Used units - Number of used units of specified class.
322 · Bytes - Total number of bytes of specified class.
324 · Used bytes - Number of used bytes of specified class.
326 · Total bytes - Total number of bytes of all classes.
328 · Total used bytes - Total number of used bytes of all classes.
330
332 $ pmempool info ./pmemblk
333 Parse and print information about "pmemblk" pool file.
335 $ pmempool info -f blk ./pmempool
337 Force parsing "pmempool" file as pmemblk pool type.
339 $ pmempool info -d ./pmemlog
341 Print information and data in hexadecimal dump format for file "pmem‐
343 log".
344 $ pmempool info -d -r10-100 -eu ./pmemblk
346 Print information from "pmemblk" file. Dump data blocks from 10 to
348 100, skip blocks marked with error flag and not marked with any flag.
349
351 pmempool(1), libpmemblk(7), libpmemlog(7), libpmemobj(7) and
352 <http://pmem.io>
353PMDK - pmem Tools version 1.3 2018-03-13 PMEMPOOL-INFO(1)