NDCTL-LIST(1)

📦
version 85 · 15 versions
, in fedora 43, fedora 44, ubuntu stonking

✨ NDCTL-LIST ✨

okay bestie, welcome to ndctl-list 💖 this is the ndctl Manual page that tells you how to dump the platform nvdimm device topology and attributes in json. yes it's as iconic as it sounds. grab a strawberry 🍓 and let's go.

🌸 NAME 🌸

ndctl-list — dump the platform nvdimm device topology and attributes in json

🦋 SYNOPSIS 🦋

ndctl list [<options>]

So basically: we walk all the nvdimm buses in the system and list all the attached devices along with some of their major attributes. main character energy, fr.

You can pass options to limit the output to devices of a certain class, where the classes are buses</>, dimms</>, regions</>, and namespaces</>. By default, ndctl list with no options is literally equivalent to:

ndctl list --namespaces --bus=all --region=all

no cap. that's the whole vibe. 💅

🎀 EXAMPLE 🎀

# ndctl list --buses --namespaces

{
  "provider":"nfit_test.1",
  "dev":"ndbus2",
  "namespaces":[
    {
      "dev":"namespace9.0",
      "mode":"raw",
      "size":33554432,
      "blockdev":"pmem9"
    }
  ]
}
{
  "provider":"nfit_test.0",
  "dev":"ndbus1"
}
{
  "provider":"e820",
  "dev":"ndbus0",
  "namespaces":[
    {
      "dev":"namespace0.0",
      "mode":"fsdax",
      "size":8589934592,
      "blockdev":"pmem0"
    }
  ]
}

look at all those devices just vibing. obsessed. 😭✨

💅 OPTIONS 💅

  • -r, --region= — a regionX device name, or a region id number. Restricts the operation to the specified region(s). You can also say the keyword all to indicate the lack of any restriction — but ngl, that's exactly the same as not passing a --region option at all. 🫶
  • -b, --bus= — a bus id number, or a provider string (e.g. "ACPI.NFIT"). Restricts the operation to the specified bus(es). The keyword all can be specified to indicate the lack of any restriction, however this is the same as not supplying a --bus option at all. yes, same energy as above. ✨
  • -d, --dimm= — an nmemX device name, or dimm id number. The dimm id number here is the X in nmemX. Filters the listing by devices that reference the given dimm. For example, to see all namespaces comprised of storage capacity on nmem0:
# ndctl list --dimm=nmem0 --namespaces
  • -n, --namespace= — an namespaceX.Y device name, or namespace region plus id tuple X.Y. Limits the namespace list to the single identified device, if present. 🎯
  • -m, --mode= — filter the listing by the mode (raw, fsdax, sector or devdax) of the namespace(s).
  • -U, --numa-node= — filter the listing by numa node
  • -B, --buses — include bus info in the listing
  • -D, --dimms — include dimm info in the listing
{
  "dev":"nmem0",
  "id":"cdab-0a-07e0-ffffffff",
  "handle":0,
  "phys_id":0,
  "security:":"disabled"
}
  • -H, --health — include dimm health info in the listing. For example:
{
  "dev":"nmem0",
  "health":{
    "health_state":"non-critical",
    "temperature_celsius":23,
    "spares_percentage":75,
    "alarm_temperature":true,
    "alarm_spares":true,
    "temperature_threshold":40,
    "spares_threshold":5,
    "life_used_percentage":5,
    "shutdown_state":"clean"
  }
}
  • -F, --firmware — include firmware info in the listing, including the state and capability of runtime firmware activation:
# ndctl list -BDF
[
  {
    "provider":"nfit_test.0",
    "dev":"ndbus2",
    "scrub_state":"idle",
    "firmware":{
      "activate_method":"suspend",
      "activate_state":"idle"
    },
    "dimms":[
      {
        "dev":"nmem1",
        "id":"cdab-0a-07e0-ffffffff",
        "handle":0,
        "phys_id":0,
        "security":"disabled",
        "firmware":{
          "current_version":0,
          "can_update":true
        }
      },
...
]
  • -X, --device-dax — include device-dax ("daxregion") details when a namespace is in "devdax" mode.
{
  "dev":"namespace0.0",
  "mode":"devdax",
  "size":4225761280,
  "uuid":"18ae1bbb-bb62-4efc-86df-4a5caacb5dcc",
  "daxregion":{
    "id":0,
    "size":4225761280,
    "align":2097152,
    "devices":[
      {
        "chardev":"dax0.0",
        "size":4225761280
      }
    ]
  }
}
  • -R, --regions — include region info in the listing
  • -N, --namespaces — include namespace info in the listing. Namespace info is listed by default if no other options are specified to the command. (she's the default queen 👑)
  • -i, --idle — include idle (not enabled) devices in the listing
  • -c, --configured — include configured devices (non-zero sized namespaces) regardless of whether they are enabled, or not. Other devices besides namespaces are always considered "configured".
  • -C, --capabilities — include region capabilities in the listing, i.e. supported namespace modes and variable properties like sector sizes and alignments.
  • -M, --media-errors — include media errors (badblocks) in the listing. heads up bestie: the badblock_count property is included in the listing by default when the count is non-zero, otherwise it is hidden. Also, if the namespace is in sector mode the badblocks listing is not included and the badblock_count property may include blocks that are located in metadata, or unused capacity in the namespace. Convert a sector namespace into raw mode to list precise badblocks offsets. 🔍
{
  "dev":"namespace7.0",
  "mode":"raw",
  "size":33554432,
  "blockdev":"pmem7",
  "badblock_count":17,
  "badblocks":[
    {
      "offset":4,
      "length":1
    },
    {
      "offset":32768,
      "length":8
    },
    {
      "offset":65528,
      "length":8
    }
  ]
}
  • -v, --verbose — increase verbosity of the output. This can be specified multiple times to be even more verbose on the informational and miscellaneous output, and can be used to override omitted flags for showing specific information. it's giving escalation, and we love that. 📈
    • -v — in addition to the enabled namespaces default output, show the numa_node, raw_uuid, and bad block media errors.
    • -vv — everything -v provides, plus automatically enable --dimms, --buses, and --regions.
    • -vvv — everything -vv provides, plus --health, --capabilities, --idle, and --firmware. The verbosity can also be scoped by the object type. For example, to just list regions with capabilities and media error info:
# ndctl list -Ru -vvv -r 0
{
  "dev":"region0",
  "size":"4.00 GiB (4.29 GB)",
  "available_size":0,
  "max_available_extent":0,
  "type":"pmem",
  "numa_node":0,
  "target_node":2,
  "capabilities":[
    {
      "mode":"sector",
      "sector_sizes":[
        512,
        520,
        528,
        4096,
        4104,
        4160,
        4224
      ]
    },
    {
      "mode":"fsdax",
      "alignments":[
        4096,
        2097152,
        1073741824
      ]
    },
    {
      "mode":"devdax",
      "alignments":[
        4096,
        2097152,
        1073741824
      ]
    }
  ],
  "persistence_domain":"unknown"
}
  • -u, --human — format numbers representing storage sizes, or offsets as human readable strings with units instead of the default machine-friendly raw-integer data. Convert other numeric fields into hexadecimal strings.
# ndctl list --region=7
{
  "dev":"region7",
  "size":67108864,
  "available_size":67108864,
  "type":"pmem",
  "iset_id":-6382611090938810793,
  "badblock_count":8
}

# ndctl list --human --region=7
{
  "dev":"region7",
  "size":"64.00 MiB (67.11 MB)",
  "available_size":"64.00 MiB (67.11 MB)",
  "type":"pmem",
  "iset_id":"0xa76c6907811fae57",
  "badblock_count":8
}

🌈 ENVIRONMENT VARIABLES 🌈

  • NDCTL_LIST_LINT — okay so, a bug in the "ndctl list" output needs to be fixed with care for other tooling that may have developed a dependency on the buggy behavior. The NDCTL_LIST_LINT variable is an opt-in to apply fixes, and not regress previously shipped behavior by default. This environment variable applies the following fixups:
    • Fix "ndctl list -Rv" to only show region objects and not include namespace objects.

Copyright © 2016 - 2022, Intel Corporation. License GPLv2: GNU GPL version 2 http://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

no warranty bestie, she said what she said 💀

⭐ SEE ALSO ⭐

and that's the whole page, periodt 💖✨ this was ndctl, dated 2026-07-07, from the NDCTL-LIST(1) era — go forth and list your devices, queen 👑🦋💜

📦 where this page comes from