9 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 Interactive Use.
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. See Command Line Use.
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
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).
The following options are available:
- Check that all units and prefixes defined in the units data file reduce
to primitive units. Print a list of all units that
cannot be reduced. 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.
- Like the --check option, this option prints a list of units that
cannot be reduced. But to help find unit definitions that cause
it lists the units as they are checked.
If units hangs, then the last unit to be printed has a bad
definition. Only definitions active in the current locale are checked.
- -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
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
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 conflicts with the --output-format
- 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 conflicts with the --output-format option.
- -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’. 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.
- -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 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.
See Logging Calculations, for a more detailed description and some
- Print out a summary of the options for units.
- Causes ‘-’ to be interpreted as a subtraction operator. This is
the default behavior.
- 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
- Causes ‘*’ to have the old-style precedence, higher than the
precedence of division so that ‘1/2*3’ will equal ‘1/6’.
- 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’.
- Give compact output featuring only the conversion factor. This turns
off the --verbose option.
- Suppress prompting of the user for units and the display of statistics
about the number of units loaded.
- Disable conversion to unit lists.
- 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.
- 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.
- 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.
- 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
- Give terse output when converting units. This option can be used when
calling units from another program so that the output is easy to
parse. 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.
- 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
- 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 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.
- 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.
- Print the location of the default units data file and exit; if the file
cannot be found, print “Units data file not found”.
- -l locale
- --locale locale
- Print the information given with the --version option, show the
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.