Invoking Units (Units: A Unit Conversion Program and Scientific Calculator)

## 10 Invoking `units` ¶

You invoke `units` like this:

    units [options] [from-unit [to-unit]]

If the from-unit and to-unit are omitted, the program will use interactive prompts to determine which conversions to perform. See Interacting with `units`. If both from-unit and to-unit are given, `units` will print the result of that single conversion and then exit. If only from-unit appears on the command line, `units` will display the definition of that unit and exit. Units specified on the command line may need to be quoted to protect them from shell interpretation and to group them into two arguments. Note also that the `--quiet` option is enabled by default if you specify from-unit on the command line. See Using `units` Non-Interactively.

The default behavior of `units` can be changed by various options given on the command line. In most cases, the options may be given in either short form (a single ‘`-`’ followed by a single character) or long form (`--` followed by a word or hyphen-separated words). Short-form options are cryptic but require less typing; long-form options require more typing but are more explanatory and may be more mnemonic. With long-form options you need only enter sufficient characters to uniquely identify the option to the program. For example, `--out %f` works, but `--o %f` fails because `units` has other long options beginning with ‘`o`’. However, `--q` works because `--quiet` is the only long option beginning with ‘`q`’.

Some options require arguments to specify a value (e.g., `-d 12` or `--digits 12`). Short-form options that do not take arguments may be concatenated (e.g., `-erS` is equivalent to `-e -r -S`); the last option in such a list may be one that takes an argument (e.g., `-ed 12`). With short-form options, the space between an option and its argument is optional (e.g., `-d12` is equivalent to `-d 12`). Long-form options may not be concatenated, and the space between a long-form option and its argument is required. Short-form and long-form options may be intermixed on the command line. Options may be given in any order, but when incompatible options (e.g., `--output-format` and `--exponential`) are given in combination, behavior is controlled by the last option given. For example, `-o%.12f -e` gives exponential format with the default eight significant digits).

Many options can be set interactively; this can be especially helpful for Windows users who start `units` from a shortcut. See Setting Options Interactively for more information.

The following options are available:

`-c` ¶
`--check`

  Check that all units and prefixes defined in units data files reduce to primitive units. Display a list of all units that cannot be reduced and a list of units with circular definitions. Also display some other diagnostics about suspicious definitions in the units data file. Only definitions active in the current locale are checked. You should always run `units` with this option after modifying a units data file.

  Some errors may hide other errors, so you should run `units` with this option again after correcting any errors, and keep doing so until there are no errors.

`--check-verbose` ¶
`--verbose-check`

  Like the `--check` option, this option displays a list of units that cannot be reduced. But it also lists the units as they are checked. Because the `--check` option now catches circular unit definitions that previously caused `units` to hang, this option is no longer necessary. It is retained only for compatibility with previous versions.

`--list-units` ¶

  This option displays a list of all units and exits. With output redirected to a file, it can produce a list of all units in the database, which may comprise multiple `units` data files. It can also be useful if you aren’t sure of the name of a unit or want to find all units of a particular type and you want a more advanced search than is available with the interactive `search` command. See Finding Units for some examples of how this option can be used.

`-d ndigits` ¶
`--digits ndigits`

  Set the number of significant digits in the output to the value specified (which must be greater than zero). For example, `-d 12` sets the number of significant digits to 12. With exponential output, `units` displays one digit to the left of the decimal point and eleven digits to the right of the decimal point. On most systems, the maximum number of internally meaningful digits is 15; if you specify a greater number than your system’s maximum, `units` will print a warning and set the number to the largest meaningful value. To directly set the maximum value, give an argument of `max` (e.g., `-d max`). Be aware, of course, that “significant” here refers only to the display of numbers; if results depend on physical constants not known to this precision, the physically meaningful precision may be less than that shown. The `--digits` option is incompatible with the `--output-format` option; if you give them both, the format is controlled by the last option given.

`-e` ¶
`--exponential`

  Set the numeric output format to exponential (i.e., scientific notation), like that used in the Unix `units` program. The default precision is eight significant digits (seven digits to the right of the decimal point); this can be changed with the `--digits` option. The `--exponential` option is incompatible with the `--output-format` option; if you give them both, the format is controlled by the last option given.

`-o format` ¶
`--output-format format`

  This option affords complete control over the numeric output format using the specified format. The format is a single floating point numeric format for the `printf` function in the C programming language. All compilers support the format types ‘`g`’ and ‘`G`’ to specify significant digits, ‘`e`’ and ‘`E`’ for scientific notation, and ‘`f`’ for fixed-point decimal. The ISO C99 standard introduced the ‘`F`’ type for fixed-point decimal and the ‘`a`’ and ‘`A`’ types for hexadecimal floating point; these types are allowed with compilers that support them. The default format is ‘`%.8g`’; for greater precision, you could specify `-o %.15g`. Unlike with the `--digits` option, you can specify any desired precision, though not all digits may be meaningful. See Numeric Output Format, and the documentation for `printf` for more detailed descriptions of the format specification. The `--output-format` option affords the greatest control of the output appearance, but requires at least rudimentary knowledge of the `printf` format syntax. If you don’t want to bother with the `printf` syntax, you can specify greater precision more simply with the `--digits` option or select exponential format with `--exponential`. The `--output-format` option is incompatible with the `--exponential` and `--digits` options; if you give either in combination with `--output-format`, the format is controlled by the last option given.

`-f filename` ¶
`--file filename`

  Instruct `units` to load the units file filename. You can specify up to 25 units files on the command line. When you use this option, `units` will load only the files you list on the command line; it will not load the standard file or your personal units file unless you explicitly list them. If filename is the empty string (`-f ""`), the default main units file (or that specified by `UNITSFILE`) will be loaded in addition to any others specified with `-f`.

`-L logfile` ¶
`--log logfile`

  Save the results of calculations in the file logfile; this can be useful if it is important to have a record of unit conversions or other calculations that are to be used extensively or in a critical activity such as a program or design project. If logfile exits, the new results are appended to the file. This option is ignored when `units` is used non-interactively. See Logging Calculations, for a more detailed description and some examples.

`-H filename` ¶
`--history filename`

  Instruct `units` to save history to filename, so that a record of your commands is available for retrieval across different `units` invocations. To prevent the history from being saved set filename to the empty string (`-H ""`). This option has no effect if readline is not available.

`-h` ¶
`--help`

  Print out a summary of the options for `units`.

`-m` ¶
`--minus`

  Causes ‘`-`’ to be interpreted as a subtraction operator. This is the default behavior.

`-p` ¶
`--product`

  Causes ‘`-`’ to be interpreted as a multiplication operator when it has two operands. It will act as a negation operator when it has only one operand: ‘`(-3)`’. By default ‘`-`’ is treated as a subtraction operator.

`--oldstar` ¶

  Causes ‘`*`’ to have the old-style precedence, higher than the precedence of division so that ‘`1/2*3`’ will equal ‘`1/6`’.

`--newstar` ¶

  Forces ‘`*`’ to have the new (default) precedence that follows the usual rules of algebra: the precedence of ‘`*`’ is the same as the precedence of ‘`/`’, so that ‘`1/2*3`’ will equal ‘`3/2`’.

`-r`
`--round`

  When converting to a combination of units given by a unit list, round the value of the last unit in the list to the nearest integer.

`-S`
`--show-factor`

  When converting to a combination of units specified in a list, always show a non-unity factor before a unit that begins with a fraction with a unity denominator. By default, if the unit in a list begins with fraction of the form 1|x and its multiplier is an integer other than 1, the fraction is given as the product of the multiplier and the numerator (e.g., ‘`3|8 in`’ rather than ‘`3 * 1|8 in`’). In some cases, this is not what is wanted; for example, the results for a cooking recipe might show ‘`3 * 1|2 cup`’ as ‘`3|2 cup`’. With the `--show-factor` option, a result equivalent to 1.5 cups will display as ‘`3 * 1|2 cup`’ rather than ‘`3|2 cup`’. A user-specified fractional unit with a numerator other than 1 is never overridden, however—if a unit list specifies ‘`3|4 cup;1|2 cup`’, a result equivalent to 1 1/2 cups will always be shown as ‘`2 * 3|4 cup`’ whether or not the `--show-factor` option is given.

`--conformable` ¶

  In non-interactive mode, show all units conformable with the original unit expression. Only one unit expression is allowed; if you give more than one, `units` will exit with an error message and return failure.

`-v` ¶
`--verbose`

  Give slightly more verbose output when converting units. When combined with the `-c` option this gives the same effect as `--check-verbose`. When combined with `--version` produces a more detailed output, equivalent to the `--info` option.

`-V` ¶
`--version`

  Print the program version number, tell whether the `readline` library has been included, tell whether UTF-8 support has been included; give the locale, the location of the default main units data file, and the location of the personal units data file; indicate if the personal units data file does not exist.

  When given in combination with the `--terse` option, the program prints only the version number and exits.

  When given in combination with the `--verbose` option, the program, the `--version` option has the same effect as the `--info` option below.

`-I` ¶
`--info`

  Print the information given with the `--version` option, show the pathname of the units program, show the status of the `UNITSFILE` and `MYUNITSFILE` environment variables, and additional information about how `units` locates the related files. On systems running Microsoft Windows, the status of the `UNITSLOCALE` environment variable and information about the related locale map are also given. This option is usually of interest only to developers and administrators, but it can sometimes be useful for troubleshooting.

  Combining the `--version` and `--verbose` options has the same effect as giving `--info`.

`-U` ¶
`--unitsfile`

  Print the location of the default main units data file and exit; if the file cannot be found, print “Units data file not found”.

`-u units-system` ¶
`--units units-system`

  Specify a CGS units system or natural units system. The supported units systems are: gauss[ian], esu, emu, hlu, natural, natural-gauss, hartree, planck, planck-red, and si. See Alternative Unit Systems, for further information about these unit systems.

`-l locale` ¶
`--locale locale`

  Force a specified locale such as ‘`en_GB`’ to get British definitions by default. This overrides the locale determined from system settings or environment variables. See Locale, for a description of locale format.

`-n`
`--nolists`

  Disable conversion to unit lists.

`-s` ¶
`--strict`

  Suppress conversion of units to their reciprocal units. For example, `units` will normally convert hertz to seconds because these units are reciprocals of each other. The strict option requires that units be strictly conformable to perform a conversion, and will give an error if you attempt to convert hertz to seconds.

`-1` ¶
`--one-line`

  Give only one line of output (the forward conversion); do not print the reverse conversion. If a reciprocal conversion is performed, then `units` will still print the “reciprocal conversion” line.

`-t` ¶
`--terse`

  Print only a single conversion factor without any clutter, or if you request a definition, prints just the definition (including its units). This option can be used when calling `units` from another program so that the output is easy to parse. The command `units --terse mile m` produces the output ‘`1690.344`’. This option has the combined effect of these options: `--strict` `--quiet` `--one-line` `--compact`. When combined with `--version` it produces a display showing only the program name and version number.

`--compact` ¶

  Give compact output featuring only the conversion factor; the multiplication and division signs are not shown, and there is no leading whitespace. If you convert to a unit list, then the output is a semicolon separated list of factors. This turns off the `--verbose` option.

`-q` ¶
`--quiet`
`--silent`

  Suppress the display of statistics about the number of units loaded, any messages printed by the units database, and the prompting of the user for units. This option does not affect how `units` displays the results. This option is turned on by default if you invoke `units` with a unit expression on the command line.