PMEMPOOL-INFO(1)

🧚 PMEMPOOL-INFO(1) — PMDK Programmer's Manual 🧚

okay so bestie, this is the manual for pmempool-info, and it's giving “let me read the pool’s diary and tell you everything.” 💅

🌸 NAME 🌸

pmempool-info — show information about persistent memory pool ✨

✨ SYNOPSIS ✨

$ pmempool info [<options>] <file>

🚨 NOTE 🚨

NOTICE: The libpmemblk and libpmemlog libraries are deprecated (this affects pool types blk, btt and log) since PMDK 1.13.0 release. 😭

🫶 DESCRIPTION 🫶

When you hit pmempool with the info command, it analyzes an existing pool created by PMDK libraries — the one you point at with the file parameter. That file can be an existing pool file, a part file or a poolset file. 🎀

The main task of this command is literally to print all usable information from pool headers and user data in human readable format. It automatically recognizes the pool type by parsing and analyzing the pool header. The recognition is done by checking the signature in the pool header. The main job of the info command is to present internal data structures as they are stored in the file, not for checking consistency. For that purpose there is the pmempool-check(1) command available. 👑

The pmempool with the info command analyzes the pool file as long as it is possible regarding correctness of internal meta-data (correct offsets, sizes etc.). If it is not possible to analyze the rest of the file, pmempool exits with error code and prints an appropriate error message. 😭

Currently there is a lack of interprocess synchronization for pool files, so the info command should be invoked off-line. Using pmempool on a pool file which may be modified by another process may lead to unexpected errors in the pool file. 🫣

pmempool info opens the pool file in read-only mode so the file will remain untouched after processing. ✨

The info command may collect and print basic statistics about data usage. The statistics are specific to the type of pool. See the STATISTICS section for details. 🌈

Although the pool consistency is not checked by the info command, it prints information about checksum errors and/or offsets errors. 💀

💅 Common options 💅

By default the info command of pmempool prints information about the most important internal data structures from the pool. The particular set of headers and meta-data depends on the pool type. The pool type is recognized automatically and appropriate information is displayed in human-readable format. 🦋

To force processing specified file(s) as the desired pool type, use the -f option with the appropriate name of pool type. The valid names of pool types are blk, log, obj or btt. This option may be useful when the pool header is corrupted and automatic recognition of pool type fails. 🔥

• -f, --force blk|log|obj|btt — force parsing the pool as the specified pool type.

NOTE: By default only pool headers and internal meta-data are displayed. To display user data use the -d option. Using the -r option you can specify number of blocks/bytes/data chunks or objects using special text format. See the RANGE section for details. The range refers to block numbers in case of pmem blk pool type, to chunk numbers in case of pmem log pool type and to object numbers in case of pmem obj pool type. See the EXAMPLES section for an example of usage of these options. 🎀

• -d, --data — dump user data in hexadecimal format. In case of pmem blk pool type, data is dumped in blocks. In case of pmem log pool type, data is dumped as a whole or in chunks if the -w option is used (see the Options for PMEMLOG section for details).
• -r, --range <range> — range of blocks/data chunks/objects/zone headers/chunk headers/lanes. See the RANGE section for details about range format.
• -n, --human — print sizes in human-readable format with appropriate units (e.g. 4k, 8M, 16G).
• -x, --headers-hex — print pool’s internal data in mixed format, which consists of a hexadecimal dump of header’s data and parsed format displayed in human-readable format. This allows one to see how data is stored in the file.
• -s, --stats — print pool’s statistics. See the STATISTICS section for details.
• -k, --bad-blocks=<yes|no> — print bad blocks found in the pool.
• -h, --help — display help message and exit.

🌈 Options for PMEMLOG 🌈

• -w, --walk <size> — use this option to walk through used data with fixed data chunk size. See pmemlog_walk(3) in libpmemlog(7) for details. 🧚

🍓 Options for PMEMBLK 🍓

By default the info command displays the pmemblk header and BTT (Block Translation Table) Info header in case of pmemblk pool type. 🎀

To display BTT Map and/or BTT FLOG (Free List and Log), use the -m and -g options respectively, or increase the verbosity level. ✨

In order to display BTT Info header backup, use the -B option. 💖

• -m, --map — print BTT Map entries.
• -g, --flog — print BTT FLOG entries.
• -B, --backup — print BTT Info header backup.

NOTE: By default the info command displays all data blocks when the -d option is used. However it is possible to skip blocks marked with zero and/or error flags. It is also possible to skip blocks which are not marked with any flag. Skipping blocks has impact on blocks ranges (e.g. display 10 blocks marked with error flag in the range from 0 to 10000) and statistics. 👀

• -z, --skip-zeros — skip blocks marked with zero flag.
• -e, --skip-error — skip blocks marked with error flag.
• -u, --skip-no-flag — skip blocks not marked with any flag.

🦋 Options for PMEMOBJ 🦋

By default the info command displays the pool header and pmemobj pool descriptor. In order to print information about other data structures, one of the following options may be used. 🌸

• -l, --lanes [<range>] — print information about lanes. If range is not specified, all lanes are displayed. The range can be specified using the -r option right after the -l option. See the RANGE section for details about range format.
• -R, --recovery — print information about only those lanes which require recovery process. This option requires the -l, --lanes option.
• -O, --object-store — print information about all allocated objects.
• -t, --types <range> — print information about allocated objects only from the specified range of type numbers. If the -s, --stats option is specified, the objects statistics refer to objects from the specified range of type numbers. This option requires the -O, --object-store or -s, --stats options. See the RANGE section for details about range format.
• -E, --no-empty — ignore empty lists of objects. This option requires the -O, --object-store option.
• -o, --root — print information about a root object.
• -A, --alloc-header — print object’s allocation header. This option requires the -O, --object-store or -l, --lanes or -o, --root options.
• -a, --oob-header — print object’s out of band header. This option requires the -O, --object-store or -l, --lanes or -o, --root options.
• -H, --heap — print information about pmemobj heap. By default only a heap header is displayed.
• -Z, --zones — if the -H, --heap option is used, print information about zones from the specified range. If the -O, --object-store option is used, print information about objects only from the specified range of zones. This option requires the -O, --object-store, -H, --heap or -s, --stats options. The range can be specified using the -r option right after the -Z option. See the RANGE section for details about range format.
• -C, --chunks [<range>] — if the -H, --heap option is used, print information about chunks from the specified range. By default information about chunks of types used, free and run are displayed. If the -O, --object-store option is used, print information about objects from the specified range of chunks within a zone. This option requires the -O, --object-store, -H, --heap or -s, --stats options. The range can be specified using the -r option right after the -C option. See the RANGE section for details about range format.
• -T, --chunk-type used,free,run,footer — print only the specified type(s) of chunks. Multiple types may be specified separated by comma. This option requires the -H, --heap and -C, --chunks options.
• -b, --bitmap — print bitmap of used blocks in chunks of type run. This option requires the -H, --heap and -C, --chunks options.
• -p, --replica <num> — print information from <num> replica. The 0 value means the master pool file.

🎀 RANGE 🎀

Using the -r, --range option it is possible to dump only a range of user data. This section describes valid format of the <range> string. 💖

You can specify multiple ranges separated by commas. ✨

• <first>-<last> — all blocks/bytes/data chunks from <first> to <last> will be dumped.
• -<last> — all blocks/bytes/data chunks up to <last> will be dumped.
• <first>- — all blocks/bytes/data chunks starting from <first> will be dumped.
• <number> — only <number> block/byte/data chunk will be dumped.

⭐ STATISTICS ⭐

Below is the description of statistical measures for specific pool types. 📊

💜 PMEMLOG

• Total — total space in pool.
• Available — size and percentage of available space.
• Used — size and percentage of used space.

💜 PMEMBLK

• Total blocks — total number of blocks in pool.
• Zeroed blocks — number and percentage of blocks marked with zero flag.
• Error blocks — number and percentage of blocks marked with error flag.
• Blocks without any flag — number and percentage of blocks not marked with any flag.

NOTE: In case of pmemblk, statistics are evaluated for blocks which meet requirements regarding: range of blocks (-r option), skipped types of blocks (-z, -e, -u options). 🫶

💜 PMEMOBJ

• Object store
  • Number of objects — total number of objects and number of objects per type number.
  • Number of bytes — total number of bytes and number of bytes per type number.
• Heap
  • Number of zones — total number of zones in the pool.
  • Number of used zones — number of used zones in the pool.
• Zone — the zone’s statistics are presented for each zone separately and the aggregated results from all zones.
  • Number of chunks — total number of chunks in the zone and number of chunks of specified type.
  • Chunks size — total size of all chunks in the zone and sum of sizes of chunks of specified type.
• Allocation classes
  • Units — total number of units of specified class.
  • Used units — number of used units of specified class.
  • Bytes — total number of bytes of specified class.
  • Used bytes — number of used bytes of specified class.
  • Total bytes — total number of bytes of all classes.
  • Total used bytes — total number of used bytes of all classes.

🎀 EXAMPLE 🎀

okay bestie, here's the vibe in action — real commands, real output energy ✨

$ pmempool info ./pmemblk

lowkey the classic: it parses and prints all the juicy info about that pmemblk pool file. no cap, that's the whole flex 💅

---

$ pmempool info -f blk ./pmempool

okay so sometimes a file is giving "mystery meat" and the tool can't tell what it is — -f blk forces the parsing of the pmempool file as a pmemblk pool type. assertive. iconic. 👑

---

$ pmempool info -d ./pmemlog

this one prints the information and the data, all in hexadecimal dump format, for the file pmemlog. full dump energy, gorgeous hex bytes everywhere 🦋

---

$ pmempool info -d -r10-100 -eu ./pmemblk

the combo meal 🍓 — it prints information from the pmemblk file, dumps data blocks from 10 to 100 (that's the -r10-100 range), skips blocks marked with the error flag, and skips blocks not marked with any flag (that's -eu doing its thing). very selective, very main character 💜

---

🌈 SEE ALSO 🌈

go check out the whole friend group, they're all slaying in their own lanes:

• pmempool(1)
• libpmemblk(7)
• libpmemlog(7)
• libpmemobj(7)
• and of course <https://pmem.io> ✨

---

bestie this is the end of the page, so here's the little receipt 🧾 — this gorgeous manual came from PMDK (the version field is literally just -, no version string, she's mysterious like that 🙈) and it's dated 2023-05-31. now go forth and info responsibly 🫶💖