## 4 Unit Definitions ¶

The conversion information is read from several units data files: `definitions.units`, `elements.units`, `currency.units`, and `cpi.units`, which are usually located in the `/usr/share/units` directory. If you invoke `units` with the `-V` option, it will print the location of these files. The default main file includes definitions for all familiar units, abbreviations and metric prefixes. It also includes many obscure or archaic units. Many common spelled-out numbers (e.g., ‘`seventeen`’) are recognized.

### 4.1 Physical Constants ¶

Many constants of nature are defined, including these:

    pi          ratio of circumference of a circle to its diameter
    c           speed of light
    e           charge on an electron
    force       acceleration of gravity
    mole        Avogadro’s number
    water       pressure per unit height of water
    Hg          pressure per unit height of mercury
    au          astronomical unit
    k           Boltzman’s constant
    mu0         permeability of vacuum
    epsilon0    permittivity of vacuum
    G           Gravitational constant
    mach        speed of sound

The standard data file includes numerous other constants. Also included are the densities of various ingredients used in baking so that ‘`2 cups flour_sifted`’ can be converted to ‘`grams`’. This is not an exhaustive list. Consult the units data file to see the complete list, or to see the definitions that are used.

### 4.2 Atomic Masses of the Elements ¶

The data file `elements.units` includes atomic masses for most elements and most known isotopes. If the mole fractions of constituent isotopes are known, an elemental mass is calculated from the sum of the products of the mole fractions and the masses of the constituent isotopes. If the mole fractions are not known, the mass of the most stable isotope—if known—is given as the elemental mass. For radioactive elements with atomic numbers 95 or greater, the mass number of the most stable isotope is not specified, because the list of studied isotopes is still incomplete. If no stable isotope is known, no elemental mass is given, and you will need to choose the most appropriate isotope.

The data are obtained from the US National Institute for Standards and Technology (NIST): https://physics.nist.gov/cgi-bin/Compositions/stand_alone.pl?ele=&all=all&ascii=ascii2&isotype=all. The `elements.units` file can be generated from these data using the `elemcvt` command included with the distribution.

### 4.3 Currency Exchange Rates and Consumer Price Index ¶

The data file `currency.units` includes currency conversion rates; the file `cpi.units` includes the US Consumer Price Index (CPI), published by the US Bureau of Labor Statistics. The data are updated monthly by the BLS; see Updating Currency Exchange Rates and CPI for information on updating `currency.units` and `cpi.units`.

### 4.4 English Customary Units ¶

English customary units differ in various ways among different regions. In Britain a complex system of volume measurements featured different gallons for different materials such as a wine gallon and ale gallon that different by twenty percent. This complexity was swept away in 1824 by a reform that created an entirely new gallon, the British Imperial gallon defined as the volume occupied by ten pounds of water. Meanwhile in the USA the gallon is derived from the 1707 Winchester wine gallon, which is 231 cubic inches. These gallons differ by about twenty percent. By default if `units` runs in the ‘`en_GB`’ locale you will get the British volume measures. If it runs in the ‘`en_US`’ locale you will get the US volume measures. In other locales the default values are the US definitions. If you wish to force different definitions, then set the environment variable `UNITS_ENGLISH` to either ‘`US`’ or ‘`GB`’ to set the desired definitions independent of the locale.

Before 1959, the value of a yard (and other units of measure defined in terms of it) differed slightly among English-speaking countries. In 1959, Australia, Canada, New Zealand, the United Kingdom, the United States, and South Africa adopted the Canadian value of 1 yard = 0.9144 m (exactly), which was approximately halfway between the values used by the UK and the US; it had the additional advantage of making 1 inch = 2.54 cm (exactly). This new standard was termed the International Yard. Australia, Canada, and the UK then defined all customary lengths in terms of the International Yard (Australia did not define the furlong or rod); because many US land surveys were in terms of the pre-1959 units, the US continued to define customary surveyors’ units (furlong, chain, rod, pole, perch, and link) in terms of the previous value for the foot, which was termed the US survey foot. The US defined a US survey mile as 5280 US survey feet, and defined a statute mile as a US survey mile. The US values for these units differed from the international values by about 2 ppm.

The 1959 redefinition of the foot was legally binding in the US but allowed continued use of the previous definition of the foot for geodetic surveying. It was assumed that this use would be temporary, but use persisted, leading to confusion and errors, and it was at odds with the intent of uniform standards. Since January 1, 2023, the US survey foot has been officially deprecated (85 FR 62698), with its use limited to historical and legacy applications.

The `units` program has always used the international values for these units; the legacy US values can be obtained by using either the ‘`US`’ or the ‘`survey`’ prefix. In either case, the simple familiar relationships among the units are maintained, e.g., 1 ‘`furlong`’ = 660 ‘`ft`’, and 1 ‘`USfurlong`’ = 660 ‘`USft`’, though the metric equivalents differ slightly between the two cases. The ‘`US`’ prefix or the ‘`survey`’ prefix can also be used to obtain the US survey mile and the value of the US yard prior to 1959, e.g., ‘`USmile`’ or ‘`surveymile`’ (but not ‘`USsurveymile`’). To get the US value of the statute mile, use either ‘`USstatutemile`’ or ‘`USmile`’. The pre-1959 UK values for these units can be obtained with the prefix ‘`UK`’.

Except for distances that extend over hundreds of miles (such as in the US State Plane Coordinate System), the differences in the miles are usually insignificant:

    You have: 100 surveymile - 100 mile
    You want: inch
            * 12.672025
            / 0.078913984

The US acre was officially defined in terms of the US survey foot, but `units` has used a definition based on the international foot; the `units` definition is now the same as the official US value. If you want the previous US acre, use ‘`USacre`’ and similarly use ‘`USacrefoot`’ for the previous US version of that unit. The difference between these units is about 4 parts per million.

### 4.5 Miscellaneous Notes on Unit Definitions ¶

The ‘`pound`’ is a unit of mass. To get force, multiply by the force conversion unit ‘`force`’ or use the shorthand ‘`lbf`’. (Note that ‘`g`’ is already taken as the standard abbreviation for the gram.) The unit ‘`ounce`’ is also a unit of mass. The fluid ounce is ‘`fluidounce`’ or ‘`floz`’. When British capacity units differ from their US counterparts, such as the British Imperial gallon, the unit is defined both ways with ‘`br`’ and ‘`us`’ prefixes. Your locale settings will determine the value of the unprefixed unit. Currency is prefixed with its country name: ‘`belgiumfranc`’, ‘`britainpound`’.

When searching for a unit, if the specified string does not appear exactly as a unit name, then the `units` program will try to remove a trailing ‘`s`’, ‘`es`’. Next units will replace a trailing ‘`ies`’ with ‘`y`’. If that fails, `units` will check for a prefix. The database includes all of the standard metric prefixes. Only one prefix is permitted per unit, so ‘`micromicrofarad`’ will fail. However, prefixes can appear alone with no unit following them, so ‘`micro*microfarad`’ will work, as will ‘`micro microfarad`’.

To find out which units and prefixes are available, read the default units data files; the main data file is extensively annotated.