1PMEMPOOL-INFO(1)           PMDK Programmer's Manual           PMEMPOOL-INFO(1)
2
3
4

NAME

6       pmempool-info - show information about persistent memory pool
7

SYNOPSIS

9              $ pmempool info [<options>] <file>
10

DESCRIPTION

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
16       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
24       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
29       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
34       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
39       pmempool info opens pool file in read-only mode so the file will remain
40       untouched after processing.
41
42       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
46       Although  the  pool  consistency is not checked by the info command, it
47       prints information about checksum errors and/or offsets errors.
48
49   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
56       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
61       -f, --force blk|log|obj|btt
62
63       Force parsing pool as specified pool type.
64
65              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
74       -d, --data
75
76       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
81       -r, --range <range>
82
83       Range  of  blocks/data chunks/objects/zone headers/chunk headers/lanes.
84       See RANGE section for details about range format.
85
86       -n, --human
87
88       Print sizes in human-readable format with appropriate  units  (e.g. 4k,
89       8M, 16G)
90
91       -x, --headers-hex
92
93       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
97       -s, --stats
98
99       Print pool's statistics.  See STATISTICS section for details.
100
101       -k, --bad-blocks=<yes|no>
102
103       Print bad blocks found in the pool.
104
105       -h, --help
106
107       Display help message and exit.
108
109   Options for PMEMLOG:
110       -w, --walk <size>
111
112       Use  this  option to walk through used data with fixed data chunk size.
113       See pmemlog_walk(3) in libpmemlog(7) for details.
114
115   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
119       To  display  BTT  Map and/or BTT FLOG (Free List and Log) use -m and -g
120       options respectively or increase verbosity level.
121
122       In order to display BTT Info header backup use -B option.
123
124       -m, --map
125
126       Print BTT Map entries.
127
128       -g, --flog
129
130       Print BTT FLOG entries.
131
132       -B, --backup
133
134       Print BTT Info header backup.
135
136              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
143       -z, --skip-zeros
144
145       Skip blocks marked with zero flag.
146
147       -e, --skip-error
148
149       Skip blocks marked with error flag.
150
151       -u, --skip-no-flag
152
153       Skip blocks not marked with any flag.
154
155   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
160       -l, --lanes [<range>]
161
162       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
166       -R, --recovery
167
168       Print  information  about  only  those  lanes  which  require  recovery
169       process.  This option requires -l, –lanes option.
170
171       -O, --object-store
172
173       Print information about all allocated objects.
174
175       -t, --types <range>
176
177       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
183       -E, --no-empty
184
185       Ignore empty lists of objects.  This option requires -O,  –object-store
186       option.
187
188       -o, --root
189
190       Print information about a root object.
191
192       -A, --alloc-header
193
194       Print  object's  allocation  header.   This  option  requires  -O, –ob‐
195       ject-store or -l, –lanes or -o, –root options.
196
197       -a, --oob-header
198
199       Print object's out of band  header.   This  option  requires  -O,  –ob‐
200       ject-store or -l, –lanes or -o, –root options.
201
202       -H, --heap
203
204       Print information about pmemobj heap.  By default only a heap header is
205       displayed.
206
207       -Z, --zones
208
209       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
216       -C, --chunks [<range>]
217
218       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
226       -T, --chunk-type used,free,run,footer
227
228       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
232       -b, --bitmap
233
234       Print  bitmap  of  used  blocks in chunks of type run.  This option re‐
235       quires -H, –heap and -C, –chunks options.
236
237       -p, --replica <num>
238
239       Print information from <num> replica.  The 0  value  means  the  master
240       pool file.
241

RANGE

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
246       You can specify multiple ranges separated by commas.
247
248       <first>-<last>
249
250       All blocks/bytes/data chunks from <first> to <last> will be dumped.
251
252       -<last>
253
254       All blocks/bytes/data chunks up to <last> will be dumped.
255
256       <first>-
257
258       All blocks/bytes/data chunks starting from <first> will be dumped.
259
260       <number>
261
262       Only <number> block/byte/data chunk will be dumped.
263

STATISTICS

265       Below is the description of  statistical  measures  for  specific  pool
266       types.
267
268   PMEMLOG
269Total - Total space in pool.
270
271Available - Size and percentage of available space.
272
273Used - Size and percentage of used space.
274
275   PMEMBLK
276Total blocks - Total number of blocks in pool.
277
278Zeroed  blocks  -  Number  and  percentage of blocks marked with zero
279         flag.
280
281Error blocks - Number and percentage  of  blocks  marked  with  error
282         flag.
283
284Blocks  without any flag - Number and percentage of blocks not marked
285         with any flag.
286
287         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
291   PMEMOBJ
292Object store
293
294Number of objects - Total number of objects and number  of  objects
295           per type number.
296
297Number  of  bytes  -  Total number of bytes and number of bytes per
298           type number.
299
300Heap
301
302Number of zones - Total number of zones in the pool.
303
304Number of used zones - Number of used zones in the pool.
305
306Zone The zone's statistics are presented for each zone separately and
307         the aggregated results from all zones.
308
309Number of chunks - Total number of chunks in the zone and number of
310           chunks of specified type.
311
312Chunks size - Total size of all chunks in the zone and sum of sizes
313           of chunks of specified type.
314
315Allocation classes
316
317Units - Total number of units of specified class.
318
319Used units - Number of used units of specified class.
320
321Bytes - Total number of bytes of specified class.
322
323Used bytes - Number of used bytes of specified class.
324
325Total bytes - Total number of bytes of all classes.
326
327Total used bytes - Total number of used bytes of all classes.
328

EXAMPLE

330              $ pmempool info ./pmemblk
331
332       Parse and print information about “pmemblk” pool file.
333
334              $ pmempool info -f blk ./pmempool
335
336       Force parsing “pmempool” file as pmemblk pool type.
337
338              $ pmempool info -d ./pmemlog
339
340       Print  information  and data in hexadecimal dump format for file “pmem‐
341       log”.
342
343              $ pmempool info -d -r10-100 -eu ./pmemblk
344
345       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

SEE ALSO

349       pmempool(1),    libpmemblk(7),    libpmemlog(7),    libpmemobj(7)   and
350       <https://pmem.io>
351
352
353
354PMDK - pmem Tools version 1.4     2021-09-24                  PMEMPOOL-INFO(1)
Impressum