bitmap_print_bitmask_to_buf(9)

📦 version 7.3.1, in nixpkgs unstable

🎀 NAME 🎀

bitmap_print_bitmask_to_buf — convert bitmap to hex bitmask format ASCII string ✨

okay bestie, welcome to the bitmap_print_bitmask_to_buf(9) page from the Kernel API Manual 💅 this one is giving low-level bitmap-to-string realness and we are going to get through it together 🫶

🌸 SYNOPSIS 🌸

int bitmap_print_bitmask_to_buf (char *buf , const unsigned long *maskp
, int nmaskbits , loff_t off , size_t count );

🦋 ARGUMENTS 🦋

  • buf — buffer into which string is placed 💖
  • maskp — pointer to bitmap to convert
  • nmaskbits — size of bitmap, in bits
  • off — in the string from which we are copying, We copy to buf
  • count — the maximum number of bytes to print

✨ DESCRIPTION ✨

Okay so here’s the tea ☕: the sprintf("*pb[l]") format is used by drivers to export a hexadecimal bitmask and a decimal list to userspace by the sysfs ABI. Drivers might be using a normal attribute for this kind of ABIs. A normal attribute typically has a show entry like this:

         static ssize_t example_attribute_show(struct device *dev,
                    struct device_attribute *attr, char *buf)
         {
            ...
            return scnprintf(buf, PAGE_SIZE - offset_in_page(buf), nr_trig_max, mask);
         }

So the show entry of an attribute has no offset and count parameters, and that means the file is limited to one page only. Not iconic. 😭

The problem is: once we have a large bitmap, we have a chance to get a bitmask or list that’s more than one page. Especially for a list, it could be as complex as 0,3,5,7,9,... — and we have no simple way to know its exact size. It turns out bin_attribute is a way to break this limit. bin_attribute has a show entry like this:

         static ssize_t
         example_bin_attribute_show(struct file *filp, struct kobject *kobj,
                    struct bin_attribute *attr, char *buf,
                    loff_t offset, size_t count)
         {
            ...
         }

With the new offset and count parameters, this makes the sysfs ABI able to support file size more than one page. For example, offset could be >= 4096. bitmap_print_bitmask_to_buf and bitmap_print_list_to_buf — with their cpumap wrappers cpumap_print_bitmask_to_buf and cpumap_print_list_to_buf — make those drivers able to support large bitmask and list after they move to use bin_attribute. In result, we have to pass the corresponding parameters such as off and count from the bin_attribute show entry to this API. Slay. 💅

The role of cpumap_print_bitmask_to_buf and cpumap_print_list_to_buf is similar to direct sysfs_emit("*pb[l]") formatting, but the latter assumes the destination buffer is exactly one page and won’t be more than one page. cpumap_print_bitmask_to_buf and cpumap_print_list_to_buf, on the other hand, mainly serve bin_attribute, which doesn’t work with exactly one page, and it can break the size limit of the converted decimal list and hexadecimal bitmask. Obsessed with breaking limits honestly 🦋

🚨 WARNING! 🚨

This function is not a replacement for sprintf. No cap. It is intended to workaround sysfs limitations discussed above and should be used carefully in the general case for the following reasons:

  • Time complexity is O(nbits^2/count), comparing to O(nbits) for snprintf. 😭
  • Memory complexity is O(nbits), comparing to O(1) for snprintf. 💀
  • off and count are NOT offset and number of bits to print. Read that again bestie 🙈
  • If printing part of bitmap as list, the resulting string is not a correct list representation of bitmap. Particularly, some bits within or out of related interval may be erroneously set or unset. The format of the string may be broken, so a bitmap_parselist-like parser may fail parsing it. 😬
  • If printing the whole bitmap as list by parts, user must ensure the order of calls of the function such that the offset is incremented linearly. 📈
  • If printing the whole bitmap as list by parts, user must keep bitmap unchanged between the very first and very last call. Otherwise concatenated result may be incorrect, and format may be broken. 🫠

Returns the number of characters actually printed to buf ✨

👑 SEE ALSO 👑

Kernel file ./lib/bitmap-str.c and these whole besties:

source/version: ./lib; date: October 2026; page: bitmap_print_bitmask_to_buf(9) — byeee bestie 🫶💋

📦 where this page comes from