---
name: "bitmap_onto"
section: "9"
platform: "linux"
package: "linux-manual-4.9"
version: "4.9.228-1"
release: "Debian 9 (Stretch)"
platforms: ["linux"]
url: "https://new.carta.tech/bitmap_onto"
---

# bitmap\_onto(9)

translate one bitmap relative to another

## NAME

bitmap\_onto - translate one bitmap relative to another

## SYNOPSIS

**void bitmap\_onto(unsigned long \*** *dst***, const unsigned long \*** *orig***, const unsigned long \*** *relmap***, unsigned int** *bits***);**

## ARGUMENTS

*dst*

resulting translated bitmap

*orig*

original untranslated bitmap

*relmap*

bitmap relative to which translated

*bits*

number of bits in each of these bitmaps

## DESCRIPTION

Set the n-th bit of *dst* iff there exists some m such that the n-th bit of *relmap* is set, the m-th bit of *orig* is set, and the n-th bit of *relmap* is also the m-th \_set\_ bit of *relmap*. (If you understood the previous sentence the first time your read it, you're overqualified for your current job.)

In other words, *orig* is mapped onto (surjectively) *dst*, using the map { \<n, m\> \| the n-th bit of *relmap* is the m-th set bit of *relmap* }.

Any set bits in *orig* above bit number W, where W is the weight of (number of set bits in) *relmap* are mapped nowhere. In particular, if for all bits m set in *orig*, m \>= W, then *dst* will end up empty. In situations where the possibility of such an empty result is not desired, one way to avoid it is to use the **bitmap\_fold** operator, below, to first fold the *orig* bitmap over itself so that all its set bits x are in the range 0 \<= x \< W. The **bitmap\_fold** operator does this by setting the bit (m % W) in *dst*, for each bit (m) set in *orig*.

Example \[1\] for **bitmap\_onto**: Let's say *relmap* has bits 30-39 set, and *orig* has bits 1, 3, 5, 7, 9 and 11 set. Then on return from this routine, *dst* will have bits 31, 33, 35, 37 and 39 set.

When bit 0 is set in *orig*, it means turn on the bit in *dst* corresponding to whatever is the first bit (if any) that is turned on in *relmap*. Since bit 0 was off in the above example, we leave off that bit (bit 30) in *dst*.

When bit 1 is set in *orig* (as in the above example), it means turn on the bit in *dst* corresponding to whatever is the second bit that is turned on in *relmap*. The second bit in *relmap* that was turned on in the above example was bit 31, so we turned on bit 31 in *dst*.

Similarly, we turned on bits 33, 35, 37 and 39 in *dst*, because they were the 4th, 6th, 8th and 10th set bits set in *relmap*, and the 4th, 6th, 8th and 10th bits of *orig* (i.e. bits 3, 5, 7 and 9) were also set.

When bit 11 is set in *orig*, it means turn on the bit in *dst* corresponding to whatever is the twelfth bit that is turned on in *relmap*. In the above example, there were only ten bits turned on in *relmap* (30..39), so that bit 11 was set in *orig* had no affect on *dst*.

Example \[2\] for **bitmap\_fold** + **bitmap\_onto**: Let's say *relmap* has these ten bits set: 40 41 42 43 45 48 53 61 74 95 (for the curious, that's 40 plus the first ten terms of the Fibonacci sequence.)

Further lets say we use the following code, invoking **bitmap\_fold** then bitmap\_onto, as suggested above to avoid the possibility of an empty *dst* result:

unsigned long \*tmp; // a temporary bitmap's bits

bitmap\_fold(tmp, orig, bitmap\_weight(relmap, bits), bits); bitmap\_onto(dst, tmp, relmap, bits);

Then this table shows what various values of *dst* would be, for various *orig*'s. I list the zero-based positions of each set bit. The tmp column shows the intermediate result, as computed by using **bitmap\_fold** to fold the *orig* bitmap modulo ten (the weight of *relmap*).

*orig* tmp *dst* 0 0 40 1 1 41 9 9 95 10 0 40 (\*) 1 3 5 7 1 3 5 7 41 43 48 61 0 1 2 3 4 0 1 2 3 4 40 41 42 43 45 0 9 18 27 0 9 8 7 40 61 74 95 0 10 20 30 0 40 0 11 22 33 0 1 2 3 40 41 42 43 0 12 24 36 0 2 4 6 40 42 45 53 78 102 211 1 2 8 41 42 74 (\*)

(\*) For these marked lines, if we hadn't first done **bitmap\_fold** into tmp, then the *dst* result would have been empty.

If either of *orig* or *relmap* is empty (no set bits), then *dst* will be returned empty.

If (as explained above) the only set bits in *orig* are in positions m where m \>= W, (where W is the weight of *relmap*) then *dst* will once again be returned empty.

All bits in *dst* not set by the above rule are cleared.

## COPYRIGHT