UNITS(1)		    General Commands Manual		      UNITS(1)



NAME
       units -- unit conversion and calculation program

SYNOPSIS
       [options] [from-unit [to-unit]]

DESCRIPTION
       The  units  program converts quantities expressed in various systems of
       measurement to their equivalents in other systems of measurement.  Like
       many  similar  programs, it can handle multiplicative scale changes. It
       can also handle nonlinear conversions such as  Fahrenheit  to  Celsius;
       see  Temperature Conversions.  The program can also perform conversions
       from and to sums of units, such as converting between meters  and  feet
       plus inches.

       But  Fahrenheit to Celsius is linear, you insist.  Not so.  A transfor-
       mation T	 is  linear  if	 T(x + y) = T(x) + T(y)	 and  this  fails  for
       T(x) = ax + b.	This  transformation  is  affine,  but not linear--see
       https://en.wikipedia.org/wiki/Linear_map.

       Basic operation is simple: you enter the units that you want to convert
       from  and  the units that you want to convert to.  You can use the pro-
       gram interactively with prompts, or you can use	it  from  the  command
       line.

       Beyond  simple unit conversions, units can be used as a general-purpose
       scientific calculator that keeps track of units	in  its	 calculations.
       You  can	 form arbitrary complex mathematical expressions of dimensions
       including sums, products, quotients, powers, and even roots  of	dimen-
       sions.	Thus  you can ensure accuracy and dimensional consistency when
       working with long expressions that involve many	different  units  that
       may  combine in complex ways; for an illustration, see Complicated Unit
       Expressions.

       The units are defined in an external data file.	You can use the exten-
       sive  data  file	 that comes with this program, or you can provide your
       own data file to suit your needs.  You can also use your own data  file
       to supplement the standard data file.

       You can change the default behavior of units with various options given
       on the command line. See Invoking Units for a description of the avail-
       able options.

INTERACTING WITH UNITS
       To  invoke  units for interactive use, type units at your shell prompt.
       The program will print something like this:

       Currency exchange rates from www.timegenie.com on 2014-03-05
       2860 units, 109 prefixes, 85 nonlinear units

       You have:

       At the 'You have:' prompt, type the quantity and	 units	that  you  are
       converting  from.   For	example,  if you want to convert ten meters to
       feet, type 10 meters.  Next, units will print 'You want:'.  You	should
       type  the  units you want to convert to.	 To convert to feet, you would
       type feet.  If the readline library was compiled in, then tab will com-
       plete  unit  names.  See	 Readline  Support  for more information about
       readline.  To quit the program type quit or exit at either prompt.

       The result will be displayed in two ways.  The first  line  of  output,
       which is marked with a '*' to indicate multiplication, gives the result
       of the conversion you have asked for.  The second line of output, which
       is  marked  with	 a  '/' to indicate division, gives the inverse of the
       conversion factor.  If you convert 10 meters to feet, units will print

	   * 32.808399
	   / 0.03048

       which tells you that 10 meters equals about 32.8 feet.  The second num-
       ber  gives  the conversion in the opposite direction.  In this case, it
       tells you that 1 foot is equal  to  about  0.03	dekameters  since  the
       dekameter is 10 meters.	It also tells you that 1/32.8 is about 0.03.

       The  units  program  prints  the inverse because sometimes it is a more
       convenient number.  In the example  above,  for	example,  the  inverse
       value  is  an  exact  conversion: a foot is exactly 0.03048 dekameters.
       But the number given the other direction is inexact.

       If you convert grains to pounds, you will see the following:

       You have: grains
       You want: pounds
	       * 0.00014285714
	       / 7000

	  From the second line of the output you can immediately  see  that  a
       grain  is equal to a seven thousandth of a pound.  This is not so obvi-
       ous from the first line of the output.  If you find  the output	format
       confusing, try using the '--verbose' option:

       You have: grain
       You want: aeginamina
	       grain = 0.00010416667 aeginamina
	       grain = (1 / 9600) aeginamina

       If  you	request a conversion between units that measure reciprocal di-
       mensions, then units will display the conversion results with an	 extra
       note indicating that reciprocal conversion has been done:

       You have: 6 ohms
       You want: siemens
	       reciprocal conversion
	       * 0.16666667
	       / 6

       Reciprocal conversion can be suppressed by using the '--strict' option.
       As usual, use the '--verbose' option to get more comprehensible output:

       You have: tex
       You want: typp
	       reciprocal conversion
	       1 / tex = 496.05465 typp
	       1 / tex = (1 / 0.0020159069) typp

       You have: 20 mph
       You want: sec/mile
	       reciprocal conversion
	       1 / 20 mph = 180 sec/mile
	       1 / 20 mph = (1 / 0.0055555556) sec/mile

       If you enter incompatible unit types, the units program	will  print  a
       message	indicating that the units are not conformable and it will dis-
       play the reduced form for each unit:

       You have: ergs/hour
       You want: fathoms kg^2 / day
       conformability error
	       2.7777778e-11 kg m^2 / sec^3
	       2.1166667e-05 kg^2 m / sec

       If you only want to find the reduced form or definition of a unit, sim-
       ply press Enter at the 'You want:' prompt.  Here is an example:

       You have: jansky
       You want:
	       Definition: fluxunit = 1e-26 W/m^2 Hz = 1e-26 kg / s^2

       The  output from units indicates that the jansky is defined to be equal
       to a fluxunit which in turn is defined to be a certain  combination  of
       watts, meters, and hertz.  The fully reduced (and in this case somewhat
       more cryptic) form appears on the far right.

       Some named units are  treated  as  dimensionless	 in  some  situations.
       These  units  include  the  radian  and steradian.  These units will be
       treated as equal to 1 in units conversions.  Power is equal  to	torque
       times  angular  velocity.  This conversion can only be performed if the
       radian is dimensionless.

       You have: (14 ft lbf) (12 radians/sec)
       You want: watts
	       * 227.77742
	       / 0.0043902509

       It is also possible to compute roots and other  non-integer  powers  of
       dimensionless  units;  this allows computations such as the altitude of
       geosynchronous orbit:

       You have: cuberoot(G earthmass / (circle/siderealday)^2) - earthradius
       You want: miles
	       * 22243.267
	       / 4.4957425e-05

       Named dimensionless units are not treated  as  dimensionless  in	 other
       contexts.    They   cannot   be	used  as  exponents  so	 for  example,
       'meter^radian' is forbidden.

       If you want a list of options you can type ? at the 'You want:' prompt.
       The  program  will  display  a list of named units that are conformable
       with the unit that you entered at the 'You have:' prompt	 above.	  Con-
       formable unit combinations will not appear on this list.

       Typing  help  at	 either prompt displays a short help message.  You can
       also type help followed by a unit name.	This will invoke  a  pager  on
       the  units  data base at the point where that unit is defined.  You can
       read the definition and comments that may give more details or histori-
       cal  information	 about	the  unit.  (You can generally quit out of the
       page by pressing 'q'.)

       Typing search text will display a list of all of the units whose	 names
       contain	text  as  a  substring along with their definitions.  This may
       help in the case where you aren't sure of the right unit name.

USING UNITS NON-INTERACTIVELY
       The units program can perform units conversions non-interactively  from
       the command line.  To do this, type the command, type the original unit
       expression, and type the new units you want.   If  a  units  expression
       contains	 non-alphanumeric  characters, you may need to protect it from
       interpretation by the shell using single or double quote characters.

       If you type

       units "2 liters" quarts

       then units will print

	   * 2.1133764
	   / 0.47317647

       and then exit.  The output tells you that 2 liters is about 2.1 quarts,
       or alternatively that a quart is about 0.47 times 2 liters.

       units  does not require a space between a numerical value and the unit,
       so the previous example can be given as

       units 2liters quarts

       to avoid having to quote the first argument.

       If the conversion is successful, units will return  success  (zero)  to
       the  calling  environment.   If	you enter  non-conformable units, then
       units will print a message giving the reduced form of each unit and  it
       will return failure (nonzero) to the calling environment.

       If the '--conformable' option is given, only one unit expression is al-
       lowed, and units will print all units conformable with that expression;
       it is equivalent to giving ? at the 'You want:' prompt.	For example,

       units --conformable gauss
       B_FIELD	 tesla
       Gs	 gauss
       T	 tesla
       gauss	 abvolt sec / cm^2
       stT	 stattesla
       statT	 stattesla
       stattesla statWb/cm^2
       tesla	 Wb/m^2

       If  you give more than one unit expression with the '--conformable' op-
       tion, the program will exit with an error message and  return  failure.
       This option has no effect in interactive mode.

       If  the	'--terse'  ('-t') option is given with the '--conformable' op-
       tion, conformable units are shown without definitions; with the	previ-
       ous example, this would give

       units --terse --conformable gauss
       B_FIELD
       Gs
       T
       gauss
       stT
       statT
       stattesla
       tesla

       When  the '--conformable' option is not given and you invoke units with
       only one argument, units will print the	definition  of	the  specified
       unit.  It will return failure if the unit is not defined and success if
       the unit is defined.

UNIT DEFINITIONS
       The conversion information is read from	a  units  data	file  that  is
       called	 'definitions.units'   and   is	  usually   located   in   the
       '/usr/share/units' directory.  If you invoke units with	the  '-V'  op-
       tion,  it  will	print the location of this file.  The default file in-
       cludes 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.

       Many constants of nature are defined, including these:

       pi	   ratio of circumference to 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 atomic masses for all of	 the  elements
       and numerous other constants.  Also included are the densities of vari-
       ous 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.

       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 ex-
       actly 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  standard
       units data file, which is extensively annotated.

   English Customary Units
       English	customary  units  differ in various ways in 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 Impe-
       rial 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 val-
       ues are the US definitions.  If you wish	 to  force  different  defini-
       tions,  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  Interna-
       tional  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, 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 differ from the international val-
       ues by about 2 ppm.

       The units program uses the international values for these units; the 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  ob-
       tain  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'.

       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  pre-1959 UK values for these units can be obtained with the prefix
       'UK'.

       In the US, the acre is officially defined in terms  of  the  US	survey
       foot,  but units uses a definition based on the international foot.  If
       you  want  the  official	 US  acre  use	'USacre'  and  similarly   use
       'USacrefoot'  for the official US version of that unit.	The difference
       between these units is about 4 parts per million.

UNIT EXPRESSIONS
   Operators
       You can enter more complicated units by combining units with operations
       such  as	 multiplication,  division, powers, addition, subtraction, and
       parentheses for grouping.  You can use the customary symbols for	 these
       operators  when	units  is invoked with its default options.  Addition-
       ally, units supports some extensions, including high priority multipli-
       cation  using  a space, and a high priority numerical division operator
       ('|') that can simplify some expressions.

       You multiply units using a space or an asterisk ('*').  The next	 exam-
       ple shows both forms:

       You have: arabicfoot * arabictradepound * force
       You want: ft lbf
	       * 0.7296
	       / 1.370614

       You can divide units using the slash ('/') or with 'per':

       You have: furlongs per fortnight
       You want: m/s
	       * 0.00016630986
	       / 6012.8727

       You can use parentheses for grouping:

       You have: (1/2) kg / (kg/meter)
       You want: league
	       * 0.00010356166
	       / 9656.0833

       White  space surrounding operators is optional, so the previous example
       could have used '(1/2)kg/(kg/meter)'.  As a consequence,	 however,  hy-
       phenated	 spelled-out  numbers  (e.g.,  'forty-two')  cannot  be	 used;
       'forty-two' is interpreted as '40 - 2'.

       Multiplication using a space has a higher precedence than division  us-
       ing  a  slash  and is evaluated left to right; in effect, the first '/'
       character marks the beginning of the denominator of a unit  expression.
       This  makes it simple to enter a quotient with several terms in the de-
       nominator: 'J / mol K'.	The '*' and '/' operators have the same prece-
       dence,  and  are evaluated left to right; if you multiply with '*', you
       must  group  the	  terms	  in   the   denominator   with	  parentheses:
       'J / (mol * K)'.

       The  higher precedence of the space operator may not always be advanta-
       geous.  For example, 'm/s s/day' is equivalent to 'm / s s day' and has
       dimensions  of length per time cubed.  Similarly, '1/2 meter' refers to
       a unit of reciprocal length equivalent to 0.5/meter, perhaps  not  what
       you  would intend if you entered that expression.  The get a half meter
       you would need to use parentheses: '(1/2) meter'.  The '*' operator  is
       convenient  for	multiplying  a	sequence  of  quotients.  For example,
       'm/s * s/day' is equivalent to 'm/day'.	 Similarly,  you  could	 write
       '1/2 * meter' to get half a meter.

       The  units program supports another option for numerical fractions: you
       can indicate division of numbers with the vertical bar ('|'), so if you
       wanted  half  a	meter you could write '1|2 meter'.  You cannot use the
       vertical bar to indicate division of non-numerical units	 (e.g.,	 'm|s'
       results in an error message).

       Powers  of  units can be specified using the '^' character, as shown in
       the following example, or by simple concatenation of a unit and its ex-
       ponent: 'cm3' is equivalent to 'cm^3'; if the exponent is more than one
       digit, the '^' is required.  You can also use '**' as an exponent oper-
       ator.

       You have: cm^3
       You want: gallons
	       * 0.00026417205
	       / 3785.4118

       Concatenation  only  works  with	 a  single  unit  name:	 if  you write
       '(m/s)2', units will treat it as multiplication by 2.  When a unit  in-
       cludes  a  prefix,  exponent  operators	apply  to  the combination, so
       'centimeter3' gives cubic centimeters.  If you separate the prefix from
       the  unit with any multiplication operator (e.g., 'centi meter^3'), the
       prefix is treated as a separate unit, so the exponent applies  only  to
       the  unit  without  the	prefix.	  The  second example is equivalent to
       'centi * (meter^3)', and gives a hundredth of a cubic meter, not a  cu-
       bic centimeter.	The units program is limited internally to products of
       99 units; accordingly, expressions like 'meter^100' or 'joule^34' (rep-
       resented internally as 'kg^34 m^68 / s^68') will fail.

       The  '|'	 operator  has	the  highest  precedence, so you can write the
       square root of two thirds as '2|3^1|2'.	The '^' operator has the  sec-
       ond highest precedence, and is evaluated right to left, as usual:

       You have: 5 * 2^3^2
       You want:
	       Definition: 2560

       With  a dimensionless base unit, any dimensionless exponent is meaning-
       ful (e.g., 'pi^exp(2.371)').  Even though angle is sometimes treated as
       dimensionless, exponents cannot have dimensions of angle:

       You have: 2^radian
			^
       Exponent not dimensionless

       If  the base unit is not dimensionless, the exponent must be a rational
       number p/q, and the dimension of the unit must be  a  power  of	q,  so
       'gallon^2|3'  works  but 'acre^2|3' fails.  An exponent using the slash
       ('/') operator (e.g., 'gallon^(2/3)') is also acceptable; the parenthe-
       ses  are	 needed	 because  the precedence of '^' is higher than that of
       '/'.  Since units cannot represent dimensions  with  exponents  greater
       than  99,  a  fully reduced exponent must have q < 100.	When raising a
       non-dimensionless unit to a power, units attempts to convert a  decimal
       exponent	 to  a	rational number with q < 100.  If this is not possible
       units displays an error message:

       You have: ft^1.234
       Base unit not dimensionless; rational exponent required

       A decimal exponent must match its rational  representation  to  machine
       precision, so 'acre^1.5' works but 'gallon^0.666' does not.

   Sums and Differences of Units
       You  may	 sometimes want to add values of different units that are out-
       side the SI.  You may also wish to use units as a calculator that keeps
       track  of  units.   Sums	 of conformable units are written with the '+'
       character, and differences with the '-' character.

       You have: 2 hours + 23 minutes + 32 seconds
       You want: seconds
	       * 8612
	       / 0.00011611705

       You have: 12 ft + 3 in
       You want: cm
	       * 373.38
	       / 0.0026782366

       You have: 2 btu + 450 ft lbf
       You want: btu
	       * 2.5782804
	       / 0.38785542

       The expressions that are added or subtracted must reduce	 to  identical
       expressions in primitive units, or an error message will be displayed:

       You have: 12 printerspoint - 4 heredium
					     ^
       Illegal sum of non-conformable units

       If  you	add  two  values  of vastly different scale you may exceed the
       available precision of floating point (about 15 digits). The effect  is
       that  the  addition  of the smaller value makes no change to the larger
       value; in other words, the smaller value is treated as if it were zero.

       You have: lightyear + cm

       No warning is given, however.  As usual, the precedence for '+' and '-'
       is  lower than that of the other operators.  A fractional quantity such
       as 2 1/2 cups can be given as '(2+1|2) cups'; the parentheses are  nec-
       essary  because multiplication has higher precedence than addition.  If
       you omit the parentheses, units attempts to add '2' and '1|2 cups', and
       you get an error message:

       You have: 2+1|2 cups
			  ^
       Illegal sum or difference of non-conformable units

       The  expression	could also be correctly written as '(2+1/2) cups'.  If
       you write '2 1|2 cups' the space is interpreted	as  multiplication  so
       the result is the same as '1 cup'.

       The  '+'	 and  '-'  characters  sometimes  appears  in  exponents  like
       '3.43e+8'.  This leads to an ambiguity in an expression like '3e+2 yC'.
       The  unit  'e'  is  a  small unit of charge, so this can be regarded as
       equivalent to '(3e+2) yC' or '(3 e)+(2 yC)'.   This  ambiguity  is  re-
       solved  by  always  interpreting	 '+' and '-' as part of an exponent if
       possible.

   Numbers as Units
       For units, numbers are just another kind of unit.  They can  appear  as
       many  times as you like and in any order in a unit expression.  For ex-
       ample, to find the volume of a box that is 2 ft by 3 ft	by  12	ft  in
       steres, you could do the following:

       You have: 2 ft 3 ft 12 ft
       You want: stere
	       * 2.038813
	       / 0.49048148

       You have: $ 5 / yard
       You want: cents / inch
	       * 13.888889
	       / 0.072

       And  the	 second example shows how the dollar sign in the units conver-
       sion can precede the five.  Be careful:	units will interpret '$5' with
       no space as equivalent to 'dollar^5'.

   Built-in Functions
       Several	built-in  functions are provided: 'sin', 'cos', 'tan', 'asin',
       'acos', 'atan', 'sinh',	'cosh',	 'tanh',  'asinh',  'acosh',  'atanh',
       'exp',  'ln',  'log',  'abs',  'round',	'floor',  'ceil', 'factorial',
       'Gamma', 'lnGamma', 'erf', and 'erfc'; the function  'lnGamma'  is  the
       natural logarithm of the 'Gamma' function.

       The  'sin',  'cos',  and 'tan' functions require either a dimensionless
       argument or an argument with dimensions of angle.

       You have: sin(30 degrees)
       You want:
	       Definition: 0.5

       You have: sin(pi/2)
       You want:
	       Definition: 1

       You have: sin(3 kg)
			 ^
       Unit not dimensionless

       The other functions on the list require dimensionless  arguments.   The
       inverse trigonometric functions return arguments with dimensions of an-
       gle.

       The 'ln' and 'log' functions give natural log and log base  10  respec-
       tively.	 To  obtain  logs for any integer base, enter the desired base
       immediately after 'log'.	 For example, to get  log  base	 2  you	 would
       write 'log2' and to get log base 47 you could write 'log47'.

       You have: log2(32)
       You want:
	       Definition: 5
       You have: log3(32)
       You want:
	       Definition: 3.1546488
       You have: log4(32)
       You want:
	       Definition: 2.5
       You have: log32(32)
       You want:
	       Definition: 1
       You have: log(32)
       You want:
	       Definition: 1.50515
       You have: log10(32)
       You want:
	       Definition: 1.50515

       If  you	wish  to  take	roots  of  units,  you	may  use the 'sqrt' or
       'cuberoot' functions.  These functions require that the	argument  have
       the  appropriate root.  You can obtain higher roots by using fractional
       exponents:

       You have: sqrt(acre)
       You want: feet
	       * 208.71074
	       / 0.0047913202

       You have: (400 W/m^2 / stefanboltzmann)^(1/4)
       You have:
	       Definition: 289.80882 K

       You have: cuberoot(hectare)
				 ^
       Unit not a root

   Previous Result
       You can insert the result of the previous conversion using  the	under-
       score  ('_').   It is useful when you want to convert the same input to
       several different units, for example

       You have: 2.3 tonrefrigeration
       You want: btu/hr
	       * 27600
	       / 3.6231884e-005
       You have: _
       You want: kW
	       * 8.0887615
	       / 0.12362832

       Suppose you want to do some deep frying that requires an oil  depth  of
       2 inches.  You have 1/2 gallon of oil, and want to know the largest-di-
       ameter pan that will maintain the required depth.  The  nonlinear  unit
       'circlearea' gives the radius of the circle (see Other Nonlinear Units,
       for a more detailed description) in SI units; you want the diameter  in
       inches:

       You have: 1|2 gallon / 2 in
       You want: circlearea
	       0.10890173 m
       You have: 2 _
       You want: in
	       * 8.5749393
	       / 0.1166189

       In most cases, surrounding white space is optional, so the previous ex-
       ample could have used '2_'.  If '_' follows a non-numerical  unit  sym-
       bol, however, the space is required:

       You have: m_
		  ^
       Parse error

       When '_' is followed by a digit, the operation is multiplication rather
       than exponentiation, so that '_2', is equivalent to '_ * 2' rather than
       '_^2'.

       You can use the '_' symbol any number of times; for example,

       You have: m
       You want:
	       Definition: 1 m
       You have: _ _
       You want:
	       Definition: 1 m^2

       Using '_' before a conversion has been performed (e.g., immediately af-
       ter invocation) generates an error:

       You have: _
		 ^
       No previous result; '_' not set

       Accordingly, '_' serves no purpose when units is	 invoked  non-interac-
       tively.

       If  units  is invoked with the '--verbose' option (see Invoking Units),
       the value of '_' is not expanded:

       You have: mile
       You want: ft
	       mile = 5280 ft
	       mile = (1 / 0.00018939394) ft
       You have: _
       You want: m
	       _ = 1609.344 m
	       _ = (1 / 0.00062137119) m

       You can give '_' at the 'You want:' prompt, but it usually is not  very
       useful.

   Complicated Unit Expressions
       The units program is especially helpful in ensuring accuracy and dimen-
       sional consistency when converting lengthy unit expressions.  For exam-
       ple, one form of the Darcy-Weisbach fluid-flow equation is

	    Delta P = (8 / pi)^2 (rho fLQ^2) / d^5,

       where  Delta  P is the pressure drop, rho is the mass density, f is the
       (dimensionless) friction factor, L is the length of the pipe, Q is  the
       volumetric  flow rate, and d is the pipe diameter.  It might be desired
       to have the equation in the form

	    Delta P = A1 rho fLQ^2 / d^5

       that accepted the user's normal units; for typical units	 used  in  the
       US, the required conversion could be something like

       You have: (8/pi^2)(lbm/ft^3)ft(ft^3/s)^2(1/in^5)
       You want: psi
	       * 43.533969
	       / 0.022970568

       The  parentheses allow individual terms in the expression to be entered
       naturally, as they might be read from the formula.  Alternatively,  the
       multiplication  could  be  done	with the '*' rather than a space; then
       parentheses are needed only around 'ft^3/s' because of its exponent:

       You have: 8/pi^2 * lbm/ft^3 * ft * (ft^3/s)^2 /in^5
       You want: psi
	       * 43.533969
	       / 0.022970568

       Without parentheses, and using spaces for multiplication, the  previous
       conversion would need to be entered as

       You have: 8 lb ft ft^3 ft^3 / pi^2 ft^3 s^2 in^5
       You want: psi
	       * 43.533969
	       / 0.022970568

   Backwards Compatibility: '*' and '-'
       The original units assigned multiplication a higher precedence than di-
       vision using the slash.	This differs from the usual precedence	rules,
       which  give  multiplication  and	 division equal precedence, and can be
       confusing for people who think of units as a calculator.

       The star operator ('*') included in this units program has, by default,
       the same precedence as division, and hence follows the usual precedence
       rules.  For backwards compatibility  you	 can  invoke  units  with  the
       '--oldstar'  option.   Then  '*' has a higher precedence than division,
       and the same precedence as multiplication using the space.

       Historically, the hyphen ('-') has been used in technical  publications
       to  indicate  products of units, and the original units program treated
       it as a multiplication operator.	 Because units provides several	 other
       ways to obtain unit products, and because '-' is a subtraction operator
       in general algebraic expressions, units treats the binary '-' as a sub-
       traction	 operator  by  default.	  For  backwards compatibility use the
       '--product' option, which causes units to treat the binary '-' operator
       as  a  product  operator.  When '-' is a multiplication operator it has
       the same precedence as multiplication with a space, giving it a	higher
       precedence than division.

       When  '-'  is used as a unary operator it negates its operand.  Regard-
       less of the units options, if '-' appears after '(' or after '+',  then
       it  will	 act as a negation operator.  So you can always compute 20 de-
       grees minus 12 minutes by entering '20 degrees + -12 arcmin'.  You must
       use this construction when you define new units because you cannot know
       what options will be in force when your definition is processed.

NONLINEAR UNIT CONVERSIONS
       Nonlinear units are represented using functional notation.   They  make
       possible nonlinear unit conversions such as temperature.

   Temperature Conversions
       Conversions  between temperatures are different from linear conversions
       between temperature increments--see the example	below.	 The  absolute
       temperature  conversions are handled by units starting with 'temp', and
       you must use functional notation.   The	temperature-increment  conver-
       sions  are done using units starting with 'deg' and they do not require
       functional notation.

       You have: tempF(45)
       You want: tempC
	       7.2222222

       You have: 45 degF
       You want: degC
	       * 25
	       / 0.04

       Think of 'tempF(x)' not as a function but as a notation that  indicates
       that  x should have units of 'tempF' attached to it.  See Defining Non-
       linear Units.  The first conversion  shows  that	 if  it's  45  degrees
       Fahrenheit  outside,  it's  7.2 degrees Celsius.	 The second conversion
       indicates that a change of  45  degrees	Fahrenheit  corresponds	 to  a
       change of 25 degrees Celsius.  The conversion from 'tempF(x)' is to ab-
       solute temperature, so that

       You have: tempF(45)
       You want: degR
	       * 504.67
	       / 0.0019814929

       gives the same result as

       You have: tempF(45)
       You want: tempR
	       * 504.67
	       / 0.0019814929

       But if you convert 'tempF(x)' to 'degC', the  output  is	 probably  not
       what you expect:

       You have: tempF(45)
       You want: degC
	       * 280.37222
	       / 0.0035666871

       The  result  is the temperature in K, because 'degC' is defined as 'K',
       the Kelvin. For consistent results, use the 'tempX' units when convert-
       ing to a temperature rather than converting a temperature increment.

       The  'tempC()'  and 'tempF()' definitions are limited to positive abso-
       lute temperatures, and giving a value that would result in  a  negative
       absolute temperature generates an error message:

       You have: tempC(-275)
			   ^
       Argument of function outside domain

   Other Nonlinear Units
       Some  other  examples  of  nonlinear  units are numerous different ring
       sizes and wire gauges, the grit sizes used for abrasives,  the  decibel
       scale,  shoe  size, scales for the density of sugar (e.g., baume).  The
       standard data file also supplies units for computing the area of a cir-
       cle  and	 the volume of a sphere.  See the standard units data file for
       more details.  Wire gauges with multiple	 zeroes	 are  signified	 using
       negative	 numbers where two zeroes is '-1'.  Alternatively, you can use
       the synonyms 'g00', 'g000', and so on that are defined in the  standard
       units data file.

       You have: wiregauge(11)
       You want: inches
	       * 0.090742002
	       / 11.020255

       You have: brwiregauge(g00)
       You want: inches
	       * 0.348
	       / 2.8735632

       You have: 1 mm
       You want: wiregauge
	       18.201919

       You have: grit_P(600)
       You want: grit_ansicoated
	       342.76923

       The  last  example shows the conversion from P graded sand paper, which
       is the European standard and may be marked "P600" on the back,  to  the
       USA standard.

       You  can	 compute  the  area  of	 a  circle  using  the nonlinear unit,
       'circlearea'.  You can also do this  using  the	circularinch  or  cir-
       cleinch.	 The next example shows two ways to compute the area of a cir-
       cle with a five inch radius and one way to  compute  the	 volume	 of  a
       sphere with a radius of one meter.

       You have: circlearea(5 in)
       You want: in2
	       * 78.539816
	       / 0.012732395

       You have: 10^2 circleinch
       You want: in2
	       * 78.539816
	       / 0.012732395

       You have: spherevol(meter)
       You want: ft3
	       * 147.92573
	       / 0.0067601492

       The inverse of a nonlinear conversion is indicated by prefixing a tilde
       ('~') to the nonlinear unit name:

       You have: ~wiregauge(0.090742002 inches)
       You want:
	       Definition: 11

       You can give a nonlinear unit definition without an argument or	paren-
       theses, and press Enter at the 'You want:' prompt to get the definition
       of a nonlinear unit; if the definition is not valid for all  real  num-
       bers,  the range of validity is also given.  If the definition requires
       specific units this information is also displayed:

       You have: tempC
	       Definition: tempC(x) = x K + stdtemp
			   defined for x >= -273.15
       You have: ~tempC
	       Definition: ~tempC(tempC) = (tempC +(-stdtemp))/K
			   defined for tempC >= 0 K
       You have: circlearea
	       Definition: circlearea(r) = pi r^2
			   r has units m

       To see the definition of the inverse use the  '~'  notation.   In  this
       case  the  parameter  in	 the functional definition will usually be the
       name of the unit.  Note that the inverse for 'tempC' shows that it  re-
       quires  units  of 'K' in the specification of the allowed range of val-
       ues.  Nonlinear unit conversions are described in more detail in Defin-
       ing Nonlinear Units.

UNIT LISTS: CONVERSION TO SUMS OF UNITS
       Outside	of  the SI, it is sometimes desirable to convert a single unit
       to a sum of units--for example, feet to feet plus inches.  The  conver-
       sion from sums of units was described in Sums and Differences of Units,
       and is a simple matter of adding the units with the '+' sign:

       You have: 12 ft + 3 in + 3|8 in
       You want: ft
	       * 12.28125
	       / 0.081424936

       Although you can similarly write a sum of units to convert to, the  re-
       sult will not be the conversion to the units in the sum, but rather the
       conversion to the particular sum that you have entered:

       You have: 12.28125 ft
       You want: ft + in + 1|8 in
	       * 11.228571
	       / 0.089058524

       The unit expression given at the 'You want:' prompt  is	equivalent  to
       asking  for conversion to multiples of '1 ft + 1 in + 1|8 in', which is
       1.09375 ft, so the conversion in the previous example is equivalent to

       You have: 12.28125 ft
       You want: 1.09375 ft
	       * 11.228571
	       / 0.089058524

       In converting to a sum of units like miles, feet and inches, you	 typi-
       cally  want  the largest integral value for the first unit, followed by
       the largest integral value for the next, and the remainder converted to
       the  last  unit.	  You can do this conversion easily with units using a
       special syntax for lists of units.  You must list the desired units  in
       order  from largest to smallest, separated by the semicolon (';') char-
       acter:

       You have: 12.28125 ft
       You want: ft;in;1|8 in
	       12 ft + 3 in + 3|8 in

       The conversion always gives integer coefficients on the	units  in  the
       list, except possibly the last unit when the conversion is not exact:

       You have: 12.28126 ft
       You want: ft;in;1|8 in
	       12 ft + 3 in + 3.00096 * 1|8 in

       The order in which you list the units is important:

       You have: 3 kg
       You want: oz;lb
	       105 oz + 0.051367866 lb

       You have: 3 kg
       You want: lb;oz
	       6 lb + 9.8218858 oz

       Listing ounces before pounds produces a technically correct result, but
       not a very useful one.  You must list the units in descending order  of
       size in order to get the most useful result.

       Ending  a  unit	list with the separator ';' has the same effect as re-
       peating the last unit on the list, so 'ft;in;1|8 in;' is equivalent  to
       'ft;in;1|8 in;1|8 in'.  With the example above, this gives

       You have: 12.28126 ft
       You want: ft;in;1|8 in;
	       12 ft + 3 in + 3|8 in + 0.00096 * 1|8 in

       in  effect  separating  the integer and fractional parts of the coeffi-
       cient for the last unit.	 If you instead prefer to round the last coef-
       ficient to an integer you can do this with the '--round' ('-r') option.
       With the previous example, the result is

       You have: 12.28126 ft
       You want: ft;in;1|8 in
	       12 ft + 3 in + 3|8 in (rounded down to nearest 1|8 in)

       When you use the '-r' option, repeating the last unit on the  list  has
       no  effect  (e.g.,  'ft;in;1|8  in;1|8  in' is equivalent to 'ft;in;1|8
       in'), and hence neither does ending a list with a ';'.  With  a	single
       unit and the '-r' option, a terminal ';' does have an effect: it causes
       units to treat the single unit as a list and produce  a	rounded	 value
       for the single unit.  Without the extra ';', the '-r' option has no ef-
       fect on single unit conversions.	 This example shows the	 output	 using
       the '-r' option:

       You have: 12.28126 ft
       You want: in
	       * 147.37512
	       / 0.0067854058

       You have: 12.28126 ft
       You want: in;
	       147 in (rounded down to nearest in)

       Each  unit  that appears in the list must be conformable with the first
       unit on the list, and of course the listed units must also be  conform-
       able with the unit that you enter at the 'You have:' prompt.

       You have: meter
       You want: ft;kg
		    ^
       conformability error
	       ft = 0.3048 m
	       kg = 1 kg

       You have: meter
       You want: lb;oz
       conformability error
	       1 m
	       0.45359237 kg

       In the first case, units reports the disagreement between units appear-
       ing on the list.	 In the second case, units  reports  disagreement  be-
       tween  the unit you entered and the desired conversion.	This conforma-
       bility error is based on the first unit on the unit list.

       Other common candidates for conversion to sums of units are angles  and
       time:

       You have: 23.437754 deg
       You want; deg;arcmin;arcsec
	   23 deg + 26 arcmin + 15.9144 arcsec

       You have: 7.2319 hr
       You want: hr;min;sec
	   7 hr + 13 min + 54.84 sec

       Some applications for unit lists may be less obvious.  Suppose that you
       have a postal scale and wish to ensure that it's accurate at 1 oz,  but
       have only metric calibration weights.  You might try

       You have: 1 oz
       You want: 100 g;50 g; 20 g;10 g;5 g;2 g;1 g;
	       20 g + 5 g + 2 g + 1 g + 0.34952312 * 1 g

       You might then place one each of the 20 g, 5 g, 2 g, and 1 g weights on
       the scale and hope that it indicates close to

       You have: 20 g + 5 g + 2 g + 1 g
       You want: oz;
	       0.98767093 oz

       Appending ';' to 'oz' forces a one-line display that includes the unit;
       here the integer part of the result is zero, so it is not displayed.

       If a non-empty list item differs vastly in scale from the quantity from
       which the list is to be converted, you may exceed the available	preci-
       sion  of floating point (about 15 digits), in which case you will get a
       warning, e.g.,

       You have: lightyear
       You want: mile;100 inch;10 inch;mm;micron
	       5.8786254e+12 mile + 390 * 100 inch (at 15-digit precision limit)

   Cooking Measure
       In North America, recipes for cooking typically measure ingredients  by
       volume,	and use units that are not always convenient multiples of each
       other.  Suppose that you have a recipe for 6 and you  wish  to  make  a
       portion	for  1.	  If the recipe calls for 2 1/2 cups of an ingredient,
       you might wish to know the measurements in terms of  measuring  devices
       you have available, you could use units and enter

       You have: (2+1|2) cup / 6
       You want: cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
	       1|3 cup + 1 tbsp + 1 tsp

       By  default,  if	 a unit in a list begins with fraction of the form 1|x
       and its multiplier is an integer, the fraction is given as the  product
       of the multiplier and the numerator; for example,

       You have: 12.28125 ft
       You want: ft;in;1|8 in;
	       12 ft + 3 in + 3|8 in

       In  many	 cases, such as the example above, this is what is wanted, but
       sometimes it is not.  For example, a cooking recipe for	6  might  call
       for  5 1/4 cup of an ingredient, but you want a portion for 2, and your
       1-cup measure is not available; you might try

       You have: (5+1|4) cup / 3
       You want: 1|2 cup;1|3 cup;1|4 cup
	       3|2 cup + 1|4 cup

       This result might be fine for a baker who has a 1 1/2-cup measure  (and
       recognizes  the	equivalence),  but  it may not be as useful to someone
       with more limited set of measures, who does want to do additional  cal-
       culations,  and only wants to know "How many 1/2-cup measures to I need
       to add?"	  After	 all,  that's  what  was  actually  asked.   With  the
       '--show-factor'	option,	 the  factor will not be combined with a unity
       numerator, so that you get

       You have: (5+1|4) cup / 3
       You want: 1|2 cup;1|3 cup;1|4 cup
	       3 * 1|2 cup + 1|4 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 re-
       sult equivalent to 1 1/2 cups will always be shown  as  '2  *  3|4 cup'
       whether or not the '--show-factor' option is given.

   Unit List Aliases
       A unit list such as

       cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp

       can  be	tedious	 to enter.  The units program provides shorthand names
       for some common combinations:

       hms	   hours, minutes, seconds
       dms	   angle: degrees, minutes, seconds
       time	   years, days, hours, minutes and seconds
       usvol	   US cooking volume: cups and smaller
       ftin	   feet, inches and 1/8 inches
       inchfine	   inches subdivided to 1/64 inch

       Using these shorthands, or unit list aliases, you can do the  following
       conversions:

       You have: anomalisticyear
       You want: time
	       1 year + 25 min + 3.4653216 sec
       You have: 1|6 cup
       You want: usvol
	       2 tbsp + 2 tsp

       You  can	 define	 your  own  unit  list aliases; see Defining Unit List
       Aliases.

       You cannot combine a unit list alias with other units: it  must	appear
       alone at the 'You want:' prompt.

       You  can	 display the definition of a unit list alias by entering it at
       the 'You have:' prompt:

       You have: dms
	       Definition: unit list, deg;arcmin;arcsec

       When you specify compact output with '--compact', '--terse' or '-t' and
       perform	conversion  to a unit list, units lists the conversion factors
       for each unit in the list, separated by semicolons.

       You have: year
       You want: day;min;sec
       365;348;45.974678

       Unlike the case of regular output, zeros are included  in  this	output
       list:

       You have: liter
       You want: cup;1|2 cup;1|4 cup;tbsp
       4;0;0;3.6280454

ALTERNATIVE UNIT SYSTEMS
   CGS Units
       The  SI--an  extension  of  the MKS (meter-kilogram-second) system--has
       largely supplanted the older CGS (centimeter-gram-second)  system,  but
       CGS  units  are	still  used in a few specialized fields, especially in
       physics where they lead to a  more  elegant  formulation	 of  Maxwell's
       equations.   Conversions	 between SI and CGS involving mechanical units
       are straightforward, involving powers of 10 (e.g., 1 m = 100 cm).  Con-
       versions	 involving  electromagnetic  units  are	 more complicated, and
       units supports four different systems of CGS units: electrostatic units
       (ESU),  electromagnetic units (EMU), the Gaussian system and the Heavi-
       side-Lorentz system.  The differences between these systems arise  from
       different choices made for proportionality constants in electromagnetic
       equations.  Coulomb's law gives electrostatic force between two charges
       separated by a distance delim $$ r:

	    F = k_C q_1 q_2 / r^2.

       Ampere's	 law  gives  the electromagnetic force per unit length between
       two current-carrying conductors separated by a distance r:

	    F/l = 2 k_A I_1 I_2 / r.

       The two constants, k_C and k_A, are related by the square of the	 speed
       of light: k_A = k_C / c^2.

       In  the SI, the constants have dimensions, and an additional base unit,
       the ampere, measures electric current.  The CGS systems do  not	define
       new  base  units,  but  express	charge and current as derived units in
       terms of mass, length, and time.	 In the ESU system, the	 constant  for
       Coulomb's  law  is  chosen to be unity and dimensionless, which defines
       the unit of charge.  In the EMU system, the constant for	 Ampere's  law
       is  chosen  to be unity and dimensionless, which defines a unit of cur-
       rent.  The Gaussian system usually uses the ESU units  for  charge  and
       current; it chooses another constant so that the units for the electric
       and magnetic fields are the same.  The Heaviside-Lorentz system is "ra-
       tionalized"  so	that factors of 4{pi} do not appear in Maxwell's equa-
       tions.  The SI system is similarly rationalized, but the other CGS sys-
       tems  are  not.	 In  the  Heaviside-Lorentz (HLU) system the factor of
       4{pi} appears in Coulomb's law instead; this system  differs  from  the
       Gaussian system by factors of the square root of 4{pi}

       The  dimensions of electrical quantities in the various CGS systems are
       different from the SI dimensions for the same units; strictly,  conver-
       sions between these systems and SI are not possible.  But units in dif-
       ferent systems relate to the same physical quantities, so  there	 is  a
       correspondence  between	these  units.	The  units program defines the
       units so that you can convert between corresponding units in the	 vari-
       ous systems.

       The  CGS definitions involve cm^(1/2) and g^(1/2), which is problematic
       because units does not normally support fractional roots of base units.
       The  '--units'  ('-u') option allows selection of a CGS unit system and
       works around this restriction by introducing base units for the	square
       roots  of length and mass: 'sqrt_cm' and 'sqrt_g'.  The centimeter then
       becomes 'sqrt_cm^2' and the gram, 'sqrt_g^2'.  This allows working from
       equations  using the units in the CGS system, and enforcing dimensional
       conformity  within  that	 system.   Recognized  CGS  arguments  to  the
       '--units' option are 'gauss[ian]', 'esu', 'emu', 'lhu'; the argument is
       case insensitive.  You can also give 'si' which just enforces  the  de-
       fault  SI  mode and displays '(SI)' at the 'You have:' prompt to empha-
       size the units mode.  Some other types of units are also	 supported  as
       described  below.   Giving  an unrecognized system generates a warning,
       and units uses SI units.

       The changes resulting from the '--units' option are actually controlled
       by  the UNITS_SYSTEM environment variable.  If you frequently work with
       one of the supported CGS units systems, you may	set  this  environment
       variable	 rather	 than  giving the '--units' option at each invocation.
       As usual, an option given on the command line overrides the setting  of
       the  environment variable. For example, if you would normally work with
       Gaussian units but might occasionally  work  with  SI,  you  could  set
       UNITS_SYSTEM  to	 'gaussian'  and specify SI with the '--units' option.
       Unlike the argument to the '--units' option, the value of  UNITS_SYSTEM
       is  case	 sensitive,  so	 setting  a value of 'EMU' will have no effect
       other than to give an error message and set SI units.

       The CGS definitions appear as  conditional  settings  in	 the  standard
       units  data  file,  which  you  can consult for more information on how
       these units are defined, or on how to define an alternate units system.

       The ESU system derives the  electromagnetic  units  from	 its  unit  of
       charge,	the  statcoulomb,  which  is  defined from Coulomb's law.  The
       statcoulomb equals dyne^(1/2) cm, or cm^(3/2) g^(1/2) s^(-1).  The unit
       of  current, the statampere, is statcoulomb sec, analogous to the rela-
       tionship in SI.	Other electrical units are then derived	 in  a	manner
       similar	to  that  for SI units; the units use the SI names prefixed by
       'stat-', e.g., 'statvolt' or 'statV'.  The prefix 'st-' is also	recog-
       nized (e.g., 'stV').

       The  EMU system derives the electromagnetic units from its unit of cur-
       rent, the abampere, which is defined in terms  of  Ampere's  law.   The
       abampere is equal to dyne^(1/2), or cm^(1/2) g^(1/2) s^(-1).  delim off
       The unit of charge, the abcoulomb, is abampere sec, again analogous  to
       the SI relationship.  Other electrical units are then derived in a man-
       ner similar to that for SI units; the units use the SI  names  prefixed
       by  'ab-',  e.g.,  'abvolt' or 'abV'.  The magnetic field units include
       the gauss, the oersted and the maxwell.

       The Gaussian units system, which was also known as the  Symmetric  Sys-
       tem,  uses  the	same charge and current units as the ESU system (e.g.,
       'statC', 'statA'); it differs by defining the magnetic field so that it
       has the same units as the electric field.  The resulting magnetic field
       units are the same ones used in the EMU system: the gauss, the  oersted
       and the maxwell.

       The  Heaviside-Lorentz  system  appears to lack named units.  We define
       five basic units, 'hlu_charge', 'hlu_current', 'hlu_volt', 'hlu_efield'
       and  'hlu_bfield' for conversions with this system.  It is important to
       remember that with all of the CGS systems, the units may look the  same
       but mean something different.  The HLU system and Gaussian systems both
       measure magnetic field using the same CGS dimensions, but the amount of
       magnetic field with the same units is different in the two systems.

       The  CGS	 systems define units that measure the same thing but may have
       conflicting dimensions.	Furthermore, the dimensions of the electromag-
       netic  CGS  units  are  never  compatible  with SI.  But if you measure
       charge in two different systems you have	 measured  the	same  physical
       thing,  so there is a correspondence between the units in the different
       systems, and units supports conversions	between	 corresponding	units.
       When  running  with  SI, units defines all of the CGS units in terms of
       SI.  When you select a CGS system, units defines the SI units  and  the
       other CGS system units in terms of the system you have selected.

       (Gaussian) You have: statA
		  You want: abA
	       * 3.335641e-11
	       / 2.9979246e+10
       (Gaussian) You have: abA
		  You want: sqrt(dyne)
       conformability error
	       2.9979246e+10 sqrt_cm^3 sqrt_g / s^2
	       1 sqrt_cm sqrt_g / s

       In  the	above  example, units converts between the current units statA
       and abA even though the abA, from the EMU system, has incompatible  di-
       mensions.   This	 works because in Gaussian mode, the abA is defined in
       terms of the statA, so it does not have the correct definition for EMU;
       consequently, you cannot convert the abA to its EMU definition.

       One  challenge  of  conversion is that because the CGS system has fewer
       base units, quantities that have different dimensions in	 SI  may  have
       the  same  dimension  in	 a CGS system.	And yet, they may not have the
       same conversion factor.	For example, the unit for the E	 field	and  B
       fields  are the same in the Gaussian system, but the conversion factors
       to SI are quite different.  This means that correct conversion is  only
       possible	 if  you  keep	track of what quantity is being measured.  You
       cannot convert statV/cm to SI without indicating which  type  of	 field
       the unit measures.  To aid in dimensional analysis, units defines vari-
       ous dimension units such as LENGTH, TIME, and CHARGE to be  the	appro-
       priate dimension in SI.	The electromagnetic dimensions such as B_FIELD
       or E_FIELD may be useful	 aids  both  for  conversion  and  dimensional
       analysis	 in CGS.  You can convert them to or from CGS in order to per-
       form SI conversions that in some cases will not work  directly  due  to
       dimensional  incompatibilities.	 This  example	shows how the Gaussian
       system uses the same units for all of the fields,  but  they  all  have
       different conversion factors with SI.

       (Gaussian) You have: statV/cm
		  You want: E_FIELD
	       * 29979.246
	       / 3.335641e-05
       (Gaussian) You have: statV/cm
		  You want: B_FIELD
	       * 0.0001
	       / 10000
       (Gaussian) You have: statV/cm
		  You want: H_FIELD
	       * 79.577472
	       / 0.012566371
       (Gaussian) You have: statV/cm
		  You want: D_FIELD
	       * 2.6544187e-07
	       / 3767303.1

       The next example shows that the oersted cannot be converted directly to
       the SI unit of magnetic field, A/m, because  the	 dimensions  conflict.
       We  cannot  redefine the ampere to make this work because then it would
       not convert with the statampere.	 But you can still do this  conversion
       as shown below.

       (Gaussian) You have: oersted
		  You want: A/m
       conformability error
	       1 sqrt_g / s sqrt_cm
	       29979246 sqrt_cm sqrt_g / s^2
       (Gaussian) You have: oersted
		  You want: H_FIELD
	       * 79.577472
	       / 0.012566371

   Natural Units
       Like the CGS units, "natural" units are an alternative to the SI system
       used primarily physicists in different fields, with  different  systems
       tailored to different fields of study.  These systems are "natural" be-
       cause the base measurements are defined using  physical	constants  in-
       stead  of  arbitrary  values such as the meter or second.  In different
       branches of physics, different physical constants are more fundamental,
       which has given rise to a variety of incompatible natural unit systems.

       The  supported  systems	are the "natural" units (which seem to have no
       better name) used in high energy	 physics  and  cosmology,  the	Planck
       units,  often  used my scientists working with gravity, and the Hartree
       atomic units are favored by those working  in  physical	chemistry  and
       condensed matter physics.

       You  can select the various natural units using the '--units' option in
       the same way that you select the CGS units.  The "natural"  units  come
       in  two types, a rationalized system derived from the Heaviside-Lorentz
       units and an unrationalized system derived from	the  Gaussian  system.
       You  can select these using 'natural' and 'natural-gauss' respectively.
       For conversions in SI mode, several unit names starting with  'natural'
       are  available.	 This "natural" system is defined by setting {hbar}, c
       and the Boltzman constant to 1.	Only a single base unit	 remains:  the
       electron volt.

       The  Planck  units exist in a variety of forms, and units supports two.
       Both supported forms are rationalized, in that factors of 4{pi} do  not
       appear  in  Maxwell's equations.	 However, Planck units can also differ
       based on how the gravitational constant is  treated.   This  system  is
       similar to the natural units in that c, {hbar}, and Boltzman's constant
       are set to 1, but in this system, Newton's gravitational constant, G is
       also  fixed.   In  the  "reduced"  Planck  system,  delim $$ 8{pi}G = 1
       whereas in the unreduced system G = 1.  The reduced  system  eliminates
       factors of 8{pi} delim off from the Einstein field equations for gravi-
       tation, so this is similar to the process of forming rationalized units
       to  simplify  Maxwell's	equations.  To obtain the unreduced system use
       the name 'planck' and  for  the	reduced	 Planck	 units,	 'planck-red'.
       Units  such as 'planckenergy' and 'planckenergy_red' enable you to con-
       vert the unreduced and reduced Planck energy unit in  SI	 mode  between
       the  various systems.  In Planck units, all measurements are dimension-
       less.

       The final natural unit system is the Hartree atomic  units.   Like  the
       Planck  units, all measurements in the Hartree units are dimensionless,
       but this system is defined by defined from completely different	physi-
       cal  constants:	the  electron  mass,  Planck's	constant, the electron
       charge, and the Coulomb constant are the defining physical  quantities,
       which  are  all set to unity.  To invoke this system with the '--units'
       option use the name 'hartree'.

   Prompt Prefix
       If a unit system is specified with the '--units' option,	 the  selected
       system's	 name  is  prepended  to the 'You have:' prompt as a reminder,
       e.g.,

       (Gaussian) You have: stC
		  You want:
	       Definition: statcoulomb = sqrt(dyne) cm = 1 sqrt_cm^3 sqrt_g / s

       You can suppressed the prefix by including a line

       !prompt

       with no argument in a site or personal units data file.	The prompt can
       be  conditionally suppressed by including such a line within '!var' ...
       '!endvar' constructs, e.g.,

       !var UNITS_SYSTEM gaussian gauss
       !prompt
       !endvar

       This might be appropriate if you normally use Gaussian units  and  find
       the prefix distracting but want to be reminded when you have selected a
       different CGS system.

LOGGING CALCULATIONS
       The '--log' option allows you to save the results of calculations in  a
       file;  this  can be useful if you need a permanent record of your work.
       For example, the fluid-flow conversion in Complicated Unit Expressions,
       is lengthy, and if you were to use it in designing a piping system, you
       might want a record of it for the project  file.	  If  the  interactive
       session

       # Conversion factor A1 for pressure drop
       # dP = A1 rho f L Q^2/d^5
       You have: (8/pi^2) (lbm/ft^3)ft(ft^3/s)^2(1/in^5) # Input units
       You want: psi
	       * 43.533969
	       / 0.022970568

       were logged, the log file would contain

       ### Log started Fri Oct 02 15:55:35 2015

       # Conversion factor A1 for pressure drop
       # dP = A1 rho f L Q^2/d^5
       From: (8/pi^2) (lbm/ft^3)ft(ft^3/s)^2(1/in^5)   # Input units
       To:   psi
	       * 43.533969
	       / 0.022970568

       The time is written to the log file when the file is opened.

       The  use	 of  comments can help clarify the meaning of calculations for
       the log.	 The log includes conformability errors between the  units  at
       the  'You have:' and 'You want:' prompts, but not other errors, includ-
       ing lack of conformability of items in sums  or	differences  or	 among
       items  in  a unit list.	For example, a conversion between zenith angle
       and elevation angle could involve

       You have: 90 deg - (5 deg + 22 min + 9 sec)
					  ^
       Illegal sum or difference of non-conformable units
       You have: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
       You want: dms
	       84 deg + 37 arcmin + 51 arcsec
       You have: _
       You want: deg
	       * 84.630833
	       / 0.011816024
       You have:

       The log file would contain

       From: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
       To:   deg;arcmin;arcsec
	       84 deg + 37 arcmin + 51 arcsec
       From: _
       To:   deg
	       * 84.630833
	       / 0.011816024

       The initial entry error (forgetting  that  minutes  have	 dimension  of
       time,  and  that	 arcminutes must be used for dimensions of angle) does
       not appear in the output.  When converting to a unit list alias,	 units
       expands the alias in the log file.

       The  'From:'  and  'To:'	 tags  are written to the log file even if the
       '--quiet' option is given.  If the log file exists when	units  is  in-
       voked, the new results are appended to the log file.  The time is writ-
       ten to the log file each time the file is opened.  The  '--log'	option
       is ignored when units is used non-interactively.

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 interac-
       tive prompts to determine which conversions to perform.	 See  Interac-
       tive  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.  Note also that the '--quiet' option is enabled  by  de-
       fault  if  you specify from-unit on the command line.  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 character) or  long  form
       ('--'  followed	by  a word or hyphen-separated words).	Short-form op-
       tions 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 begin-
       ning 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  op-
       tion 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 in-
       termixed 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 de-
       fault eight significant digits).

       The following options are available:

       -c, --check
	      Check that all units and prefixes defined in the units data file
	      reduce  to primitive units.  Print a list of all units that can-
	      not be reduced.  Also display some other diagnostics about  sus-
	      picious  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.

       --check-verbose, --verbose-check
	      Like  the	 '--check'  option, this option prints a list of units
	      that cannot be reduced.  But to help find unit  definitions that
	      cause endless loops, it lists the units as they are checked.  If
	      units hangs, then the last unit to be printed has a bad  defini-
	      tion.   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 expo-
	      nential output units displays one digit to the left of the deci-
	      mal 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 preci-
	      sion, the physically meaningful precision may be less than  that
	      shown.	 The	'--digits'    option	conflicts   with   the
	      '--output-format' option.

       -e, --exponential
	      Set the numeric output format to exponential  (i.e.,  scientific
	      notation),  like	that  used in the Unix units program.  The de-
	      fault 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 float-
	      ing point numeric format for the printf() function in the C pro-
	      gramming language.  All compilers support the format  types  'g'
	      and  'G'	to  specify significant digits, 'e' and 'E' for scien-
	      tific 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 for-
	      mat  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 specifica-
	      tion.  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	preci-
	      sion  more  simply with the '--digits' option or select exponen-
	      tial 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 op-
	      tion,  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 conver-
	      sions 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 file-
	      name 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 in-
	      teger.

       -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  ex-
	      ample, the results for a cooking recipe might show '3 * 1|2 cup'
	      as '3|2 cup'.  With the '--show-factor' option, a result equiva-
	      lent  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 speci-
	      fies '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  li-
	      brary has been included, tell whether UTF-8 support has been in-
	      cluded; 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 pro-
	      gram, 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  sys-
	      tems  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 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 sup-
	      ported units systems are: gauss[ian], esu,  emu,	hlu,  natural,
	      natural-gauss, hartree, planck, planck-red, and si. See Alterna-
	      tive Unit Systems for further information about these unit  sys-
	      tems.

       -l locale, --locale locale
	      Force  a specified locale such as 'en_GB' to get British defini-
	      tions by default.	 This overrides	 the  locale  determined  from
	      system  settings or environment variables.  See Locale for a de-
	      scription of locale format.

       -n, --nolists
	      Disable conversion to unit lists.

       -s, --strict
	      Suppress conversion of units to their reciprocal units.  For ex-
	      ample,  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 conver-
	      sion, 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 conver-
	      sion" line.

       -t, --terse
	      Print only a single conversion factor.  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 op-
	      tions:   '--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 de-
	      fault  if you invoke units with a unit expression on the command
	      line.

SCRIPTING WITH UNITS
       Despite its numerous options,  units  cannot  cover  every  conceivable
       unit-conversion task.  For example, suppose we have found some mysteri-
       ous scale, but cannot figure out the units in which  it	is  reporting.
       We  reach into our pocket, place a 3.75-gram coin on the scale, and ob-
       serve the scale reading '0.120'.	  How  do  we  quickly	determine  the
       units?	Or  we	might wonder if a unit has any "synonyms," i.e., other
       units with the same value.

       The capabilities of units are easily extended  with  simple  scripting.
       Both  questions above involve conformable units; on a system with Unix-
       like utilities, conversions to conformable units could be shown	accom-
       plished with the following script:

       #!/bin/sh

       progname=`basename $0 .sh`
       umsg="Usage: $progname [<number>] unit"

       if [ $# -lt 1 ]
       then
	   echo "$progname: missing quantity to convert"
	   echo "$umsg"
	   exit 1
       fi

       for unit in `units --conformable "$*" | cut -f 1 -d ' '`
       do
	   echo "$*"   # have -- quantity to convert
	   echo $unit  # want -- conformable unit
       done | units --terse --verbose

       When  units is invoked with no non-option arguments, it reads have/want
       pairs, on alternating lines, from its standard input, so the  task  can
       be  accomplished	 with  only two invocations of units.  This avoids the
       computational overhead of needlessly reprocessing  the  units  database
       for  each  conformable unit, as well as the inherent system overhead of
       process invocation.

       By itself, the script is not very useful.  But it could be used in com-
       bination	 with  other commands to address specific tasks.  For example,
       running the script through a simple output filter could help solve  the
       scale problem above.  If the script is named conformable, running

       $ conformable 3.75g | grep 0.120

       gives
	       3.75g = 0.1205653 apounce
	       3.75g = 0.1205653 fineounce
	       3.75g = 0.1205653 ozt
	       3.75g = 0.1205653 tradewukiyeh
	       3.75g = 0.1205653 troyounce

       So we might conclude that the scale is calibrated in troy ounces.

       We might run
       $ units --verbose are
	       Definition: 100 m^2 = 100 m^2

       and wonder if 'are' has any synonyms, value.  To find out, we could run

       $ conformable are | grep "= 1 "
	       are = 1 a
	       are = 1 are

OUTPUT STYLES
       The  output  can be tweaked in various ways using command line options.
       With no options, the output looks like this

       $ units
       Currency exchange rates from FloatRates (USD base) on 2019-02-20
       3070 units, 109 prefixes, 109 nonlinear units

       You have: 23ft
       You want: m
	       * 7.0104
	       / 0.14264521
       You have: m
       You want: ft;in
	       3 ft + 3.3700787 in

       This is arguably a bit cryptic; the '--verbose' option makes clear what
       the output means:

       $ units --verbose
       Currency exchange rates from FloatRates (USD base) on 2019-02-20
       3070 units, 109 prefixes, 109 nonlinear units

       You have: 23 ft
       You want: m
	       23 ft = 7.0104 m
	       23 ft = (1 / 0.14264521) m
       You have: meter
       You want: ft;in
	       meter = 3 ft + 3.3700787 in

       The  '--quiet'  option  suppresses  the	clutter	 displayed  when units
       starts, as well as the prompts to the user.  This option is enabled  by
       default when you give units on the command line.

       $ units --quiet
       23 ft
       m
	       * 7.0104
	       / 0.14264521

       $ units 23ft m
	       * 7.0104
	       / 0.14264521

       The  remaining style options allow you to display only numerical values
       without the tab or the multiplication and division signs, or to display
       just a single line showing the forward conversion:

       $ units --compact 23ft m
       7.0104
       0.14264521

       $ units --compact m 'ft;in'
       3;3.3700787

       $ units --one-line 23ft m
	       * 7.0104

       $ units --one-line 23ft 1/m
	       reciprocal conversion
	       * 0.14264521

       $ units --one-line 23ft kg
       conformability error
	       7.0104 m
	       1 kg

       Note  that  when converting to a unit list, the '--compact' option dis-
       plays a semicolon separated list of results.  Also be  aware  that  the
       'one-line' option doesn't live up to its name if you execute a recipro-
       cal conversion or if you get a conformability error.  The  former  case
       can be prevented using the '--strict' option, which suppresses recipro-
       cal conversions.	 Similarly you can suppress unit list conversion using
       '--nolists'.  It is impossible to prevent the three line error output.

       $ units --compact --nolists m 'ft;in'
       Error in 'ft;in': Parse error

       $ units --one-line --strict 23ft 1/m

       The  various style options can be combined appropriately.  The ultimate
       combination  is	the  '--terse'	option,	 which	combines   '--strict',
       '--quiet', '--one-line', and '--compact' to produce the minimal output,
       just a single number for regular conversions and a semicolon  separated
       list for conversion to unit lists.  This will likely be the best choice
       for programs that want to call units and then process its result.

       $ units --terse 23ft m
       7.0104

       $ units --terse m 'ft;in'
       3;3.3700787

       $ units --terse 23ft 1/m
       conformability error
       7.0104 m
       1 / m

ADDING YOUR OWN DEFINITIONS
   Units Data Files
       The units and prefixes that units can convert are defined in the	 units
       data  file,  typically  '/usr/share/units/definitions.units'.   If  you
       can't find this file, run units --version to  get  information  on  the
       file  locations for your installation.  Although you can extend or mod-
       ify this data file if you have appropriate user privileges,  it's  usu-
       ally better to put extensions in separate files so that the definitions
       will be preserved if you update units.

       You can include additional data files in the units database  using  the
       '!include' command in the standard units data file. For example

       !include	   /usr/local/share/units/local.units

       might be appropriate for a site-wide supplemental data file.  The loca-
       tion of the '!include' statement in the standard units data file is im-
       portant;	 later definitions replace earlier ones, so any definitions in
       an included file will override definitions before the '!include' state-
       ment in the standard units data file.  With normal invocation, no warn-
       ing is given about redefinitions; to ensure that you don't have an  un-
       intended	 redefinition,	run units -c after making changes to any units
       data file.

       If you want to add your own units in addition to or in place  of	 stan-
       dard  or	 site-wide supplemental units data files, you can include them
       in the '.units' file in your home directory.  If this file exists it is
       read  after  the	 standard  units data file, so that any definitions in
       this file will replace definitions of the same units  in	 the  standard
       data  file or in files included from the standard data file.  This file
       will not be read if any units files are specified on the command	 line.
       (Under Windows the personal units file is named 'unitdef.units'.)  Run-
       ning units -V will display the location and name of your personal units
       file.

       The units program first tries to determine your home directory from the
       HOME environment variable.  On systems running  Microsoft  Windows,  if
       HOME  does  not	exist, units attempts to find your home directory from
       HOMEDRIVE, HOMEPATH and USERPROFILE.  You can specify an arbitrary file
       as your personal units data file with the MYUNITSFILE environment vari-
       able; if this variable exists, its value is used without searching your
       home directory.	The default units data files are described in more de-
       tail in Data Files.

   Defining New Units and Prefixes
       A unit is specified on a single line by giving its name and an  equiva-
       lence.	Comments start with a '#' character, which can appear anywhere
       in a line.  The backslash character ('\') acts as a continuation	 char-
       acter if it appears as the last character on a line, making it possible
       to spread definitions out over several lines if desired.	 A file can be
       included	 by giving the command '!include' followed by the file's name.
       The '!' must be the first character on the  line.   The	file  will  be
       sought  in the same directory as the parent file unless you give a full
       path.  The name of the file to be included cannot contain spaces or the
       comment character '#'.

       Unit  names  must  not contain any of the operator characters '+', '-',
       '*', '/', '|', '^', ';', '~', the comment character '#',	 or  parenthe-
       ses.   They cannot begin or end with an underscore ('_'), a comma (',')
       or a decimal point ('.').  The figure dash (U+2012), typographical  mi-
       nus  ('-'; U+2212), and en dash ('--'; U+2013) are converted to the op-
       erator '-', so none of these  characters	 can  appear  in  unit	names.
       Names  cannot  begin  with a digit, and if a name ends in a digit other
       than zero or one, the digit must be preceded by a string beginning with
       an  underscore,	and  afterwards	 consisting  only  of  digits, decimal
       points, or commas.  For example, 'foo_2', 'foo_2,1', or 'foo_3.14'  are
       valid names but 'foo2' or 'foo_a2' are invalid.	The underscore is nec-
       essary because without it, units cannot determine whether 'foo2'	 is  a
       unit  name  or represents 'foo^2'.  Zero and one are exceptions because
       units never interprets them as exponents.

       You could define nitrous oxide as

       N2O     nitrogen 2  + oxygen

       but would need to define nitrogen dioxide as

       NO_2    nitrogen + oxygen 2

       Be careful to define new units in terms of old ones so that a reduction
       leads  to  the  primitive units, which are marked with '!'  characters.
       Dimensionless units are indicated by using the string  '!dimensionless'
       for the unit definition.

       When adding new units, be sure to use the '-c' option to check that the
       new units reduce properly.  If you create a loop in the	units  defini-
       tions,  then  units  will  hang when invoked with the '-c' option.  You
       will need to use the '--check-verbose' option, which  prints  out  each
       unit  as it is checked.	The program will still hang, but the last unit
       printed will be the unit that caused the infinite loop.

       If you define any units that contain '+' characters  in	their  defini-
       tions, carefully check them because the '-c' option will not catch non-
       conformable sums.  Be careful with the '-' operator as well.  When used
       as  a binary operator, the '-' character can perform addition or multi-
       plication depending on the options used to  invoke  units.   To	ensure
       consistent  behavior  use  '-'  only  as a unary negation operator when
       writing units definitions.  To multiply two units leave a space or  use
       the  '*'	 operator with care, recalling that it has two possible prece-
       dence values and may require parentheses to ensure consistent behavior.
       To compute the difference of 'foo' and 'bar' write 'foo+(-bar)' or even
       'foo+-bar'.

       You may wish to intentionally redefine a unit.  When you do  this,  and
       use the '-c' option, units displays a warning message about the redefi-
       nition.	You can suppress these warnings by redefining a unit  using  a
       '+'  at the beginning of the unit name.	Do not include any white space
       between the '+' and the redefined unit name.

       Here is an example of a short data file that defines some basic units:

       m       !	       # The meter is a primitive unit
       sec     !	       # The second is a primitive unit
       rad     !dimensionless  # A dimensionless primitive unit
       micro-  1e-6	       # Define a prefix
       minute  60 sec	       # A minute is 60 seconds
       hour    60 min	       # An hour is 60 minutes
       inch    72 m	       # Inch defined incorrectly terms of meters
       ft      12 inches       # The foot defined in terms of inches
       mile    5280 ft	       # And the mile
       +inch   0.0254 m	       # Correct redefinition, warning suppressed

       A unit that ends with a '-' character is a prefix.  If a prefix defini-
       tion  contains any '/' characters, be sure they are protected by paren-
       theses.	If you define 'half- 1/2', then 'halfmeter' would  be  equiva-
       lent to '1 / (2 meter)'.

   Defining Nonlinear Units
       Some  unit conversions of interest are nonlinear; for example, tempera-
       ture conversions between the Fahrenheit and Celsius  scales  cannot  be
       done by simply multiplying by conversion factors.

       When  you  give a linear unit definition such as 'inch 2.54 cm' you are
       providing information that units uses to convert values in inches  into
       primitive  units of meters.  For nonlinear units, you give a functional
       definition that provides the same information.

       Nonlinear units are represented using a	functional  notation.	It  is
       best  to	 regard	 this  notation not as a function call but as a way of
       adding units to a number, much the same way that writing a linear  unit
       name  after  a number adds units to that number.	 Internally, nonlinear
       units are defined by a pair of functions that convert to and from  lin-
       ear  units in the database, so that an eventual conversion to primitive
       units is possible.

       Here is an example nonlinear unit definition:

       tempF(x) units=[1;K] domain=[-459.67,) range=[0,) \
		   (x+(-32)) degF + stdtemp ; (tempF+(-stdtemp))/degF + 32

       A nonlinear unit definition comprises a unit name, a  formal  parameter
       name, two functions, and optional specifications for units, the domain,
       and the range (the domain of the inverse function).  The functions tell
       units  how  to  convert to and from the new unit.  To produce valid re-
       sults, the arguments of these functions need to have the correct dimen-
       sions and be within the domains for which the functions are defined.

       The  definition begins with the unit name followed immediately (with no
       spaces) by a '(' character.  In the parentheses is the name of the for-
       mal parameter.  Next is an optional specification of the units required
       by the  functions  in  the  definition.	 In  the  example  above,  the
       'units=[1;K]'  specification  indicates	that  the 'tempF' function re-
       quires an input argument conformable with '1' (i.e.,  the  argument  is
       dimensionless),	and  that the inverse function requires an input argu-
       ment conformable with 'K'.  For normal nonlinear units definition,  the
       forward function will always take a dimensionless argument; in general,
       the inverse function will need units that match the  quantity  measured
       by  your nonlinear unit.	 Specifying the units enables units to perform
       error checking on function arguments, and also to assign units  to  do-
       main and range specifications, which are described later.

       Next  the  function  definitions	 appear.   In  the  example above, the
       'tempF' function is defined by

       tempF(x) = (x+(-32)) degF + stdtemp

       This gives a rule for converting 'x' in the  units  'tempF'  to	linear
       units  of absolute temperature, which makes it possible to convert from
       tempF to other units.

       To enable conversions to Fahrenheit, you must give a rule for  the  in-
       verse  conversions.   The inverse will be 'x(tempF)' and its definition
       appears after a ';' character.  In our example, the inverse is

       x(tempF) = (tempF+(-stdtemp))/degF + 32

       This inverse definition takes an absolute temperature as	 its  argument
       and  converts  it  to  the  Fahrenheit temperature.  The inverse can be
       omitted by leaving out the ';' character and  the  inverse  definition,
       but  then conversions to the unit will not be possible.	If the inverse
       definition is omitted, the '--check' option will display a warning.  It
       is up to you to calculate and enter the correct inverse function to ob-
       tain proper conversions; the '--check' option tests the inverse at  one
       point  and  prints an error if it is not valid there, but this is not a
       guarantee that your inverse is correct.

       With some definitions, the units may vary.  For example, the definition

       square(x)       x^2

       can have any arbitrary units, and can  also  take  dimensionless	 argu-
       ments.	In such a case, you should not specify units.  If a definition
       takes a root of its arguments, the definition is valid only  for	 units
       that yield such a root.	For example,

       squirt(x)       sqrt(x)

       is valid for a dimensionless argument, and for arguments with even pow-
       ers of units.

       Some definitions may not be valid for all real numbers.	In such cases,
       units can handle errors better if you specify an appropriate domain and
       range.  You specify the domain and range as shown below:

       baume(d) units=[1;g/cm^3] domain=[0,130.5] range=[1,10] \
		(145/(145-d)) g/cm^3 ; (baume+-g/cm^3) 145 / baume

       In this example the domain is specified after 'domain=' with  the  end-
       points  given  in  brackets.   In  accord with mathematical convention,
       square brackets indicate a closed interval (one that includes its  end-
       points),	 and  parentheses indicate an open interval (one that does not
       include its endpoints).	An interval can be open or closed  on  one  or
       both  ends; an interval that is unbounded on either end is indicated by
       omitting the limit on that end.	For example, a quantity to which deci-
       bel  (dB) is applied may have any value greater than zero, so the range
       is indicated by '(0,)':

       decibel(x) units=[1;1] range=(0,) 10^(x/10); 10 log(decibel)

       If the domain or range is given, the second endpoint  must  be  greater
       than the first.

       The domain and range specifications can appear independently and in any
       order along with the units specification.  The values  for  the	domain
       and range endpoints are attached to the units given in the units speci-
       fication, and if necessary, the parameter value is adjusted for compar-
       ison  with  the	endpoints.   For  example,  if	a  definition includes
       'units=[1;ft]' and 'range=[3,)', the range will be taken as 3 ft to in-
       finity.	 If the function is passed a parameter of '900 mm', that value
       will be adjusted to 2.9527559 ft, which is outside the specified range.
       If  you	omit  the units specification from the previous example, units
       can not tell whether you intend the lower endpoint to be 3 ft or	 3 mi-
       crofurlongs,  and can not adjust the parameter value of 900 mm for com-
       parison.	 Without units, numerical values other than zero  or  plus  or
       minus  infinity	for domain or range endpoints are meaningless, and ac-
       cordingly they are not allowed.	 If  you  give	other  values  without
       units,  then  the  definition will be ignored and you will get an error
       message.

       Although the units, domain, and range specifications are optional, it's
       best  to	 give  them when they are applicable; doing so allows units to
       perform better error checking and give  more  helpful  error  messages.
       Giving the domain and range also enables the '--check' option to find a
       point in the domain to use for its point check of your inverse  defini-
       tion.

       You can make synonyms for nonlinear units by providing both the forward
       and inverse functions; inverse functions can be obtained using the  '~'
       operator.  So to create a synonym for 'tempF' you could write

       fahrenheit(x) units=[1;K] tempF(x); ~tempF(fahrenheit)

       This  is	 useful	 for creating a nonlinear unit definition that differs
       slightly from an existing definition without having to repeat the orig-
       inal functions.	For example,

       dBW(x)	  units=[1;W] range=[0,) dB(x) W ;  ~dB(dBW/W)

       If  you	wish  a synonym to refer to an existing nonlinear unit without
       modification, you can do so more simply by adding the synonym with  ap-
       pended  parentheses  as	a new unit, with the existing nonlinear unit--
       without parentheses--as the definition.	So to  create  a  synonym  for
       'tempF' you could write

       fahrenheit()  tempF

       The definition must be a nonlinear unit; for example, the synonym

       fahrenheit()  meter

       will result in an error message when units starts.

       You  may occasionally wish to define a function that operates on units.
       This can be done using a nonlinear unit definition.  For	 example,  the
       definition  below  provides conversion between radius and the area of a
       circle.	This definition requires a length as  input  and  produces  an
       area as output, as indicated by the 'units=' specification.  Specifying
       the range as the nonnegative numbers can	 prevent  cryptic  error  mes-
       sages.

       circlearea(r) units=[m;m^2] range=[0,)	pi r^2 ; sqrt(circlearea/pi)

   Defining Piecewise Linear Units
       Sometimes you may be interested in a piecewise linear unit such as many
       wire gauges.  Piecewise linear units can be defined by specifying  con-
       versions	 to  linear  units  on	a list of points.  Conversion at other
       points will be done by linear interpolation.  A partial	definition  of
       zinc gauge is

       zincgauge[in] 1 0.002, 10 0.02, 15 0.04, 19 0.06, 23 0.1

       In  this example, 'zincgauge' is the name of the piecewise linear unit.
       The definition of such a unit is indicated by the embedded '['  charac-
       ter.   After  the bracket, you should indicate the units to be attached
       to the numbers in the table.  No spaces can appear before the ']' char-
       acter,  so a definition like 'foo[kg meters]' is invalid; instead write
       'foo[kg*meters]'.  The definition of the unit consists  of  a  list  of
       pairs optionally separated by commas.  This list defines a function for
       converting from the piecewise linear unit to linear units.   The	 first
       item  in	 each  pair  is	 the function argument; the second item is the
       value of the function at that  argument	(in  the  units	 specified  in
       brackets).  In this example, we define 'zincgauge' at five points.  For
       example, we set 'zincgauge(1)' equal to '0.002 in'.   Definitions  like
       this  may  be  more readable  if written using  continuation characters
       as

       zincgauge[in] \
	    1 0.002  \
	   10 0.02   \
	   15 0.04   \
	   19 0.06   \
	   23 0.1

       With the preceding definition, the following  conversion	 can  be  per-
       formed:

       You have: zincgauge(10)
       You want: in
	   * 0.02
	   / 50
       You have: .01 inch
       You want: zincgauge
	   5

       If  you	define a piecewise linear unit that is not strictly monotonic,
       then the inverse will not be well defined.  If the inverse is requested
       for such a unit, units will return the smallest inverse.

       After  adding  nonlinear	 units	definitions,  you  should normally run
       units --check to check for errors.   If	the  'units'  keyword  is  not
       given,  the '--check' option checks a nonlinear unit definition using a
       dimensionless argument, and then checks using an arbitrary  combination
       of units, as well as the square and cube of that combination; a warning
       is given if any of these tests fail.  For example,

       Warning: function 'squirt(x)' defined as 'sqrt(x)'
		failed for some test inputs:
		squirt(7(kg K)^1): Unit not a root
		squirt(7(kg K)^3): Unit not a root

       Running units --check will print a warning if a non-monotonic piecewise
       linear unit is encountered.  For example, the relationship between ANSI
       coated abrasive designation and mean particle size is non-monotonic  in
       the vicinity of 800 grit:

       ansicoated[micron] \
	    . . .
	   600 10.55 \
	   800 11.5 \
	   1000 9.5 \

       Running units --check would give the error message

       Table 'ansicoated' lacks unique inverse around entry 800

       Although	 the  inverse is not well defined in this region, it's not re-
       ally an error.  Viewing such error messages  can	 be  tedious,  and  if
       there  are  enough  of them, they can distract from true errors.	 Error
       checking for nonlinear unit definitions can be suppressed by giving the
       'noerror' keyword; for the examples above, this could be done as

       squirt(x) noerror domain=[0,) range=[0,) sqrt(x); squirt^2
       ansicoated[micron] noerror \
	    . . .

       Use  the	 'noerror'  keyword  with  caution.  The safest approach after
       adding a nonlinear unit definition is to run units --check and  confirm
       that there are no actual errors before adding the 'noerror' keyword.

   Defining Unit List Aliases
       Unit  list  aliases  are treated differently from unit definitions, be-
       cause they are a data entry shorthand rather than a true definition for
       a  new  unit.  A unit list alias definition begins with '!unitlist' and
       includes the alias and the definition;  for example,  the  aliases  in-
       cluded in the standard units data file are

       !unitlist   hms	   hr;min;sec
       !unitlist   time	   year;day;hr;min;sec
       !unitlist   dms	   deg;arcmin;arcsec
       !unitlist   ftin	   ft;in;1|8 in
       !unitlist   usvol   cup;3|4 cup;2|3 cup;1|2 cup;1|3 cup;1|4 cup;\
			   tbsp;tsp;1|2 tsp;1|4 tsp;1|8 tsp

       Unit  list  aliases are only for unit lists, so the definition must in-
       clude a ';'.  Unit list aliases can never be  combined  with  units  or
       other  unit list aliases, so the definition of 'time' shown above could
       not have been shortened to 'year;day;hms'.

       As usual, be sure to run units --check to ensure that the units	listed
       in unit list aliases are conformable.

NUMERIC OUTPUT FORMAT
       By  default,  units  shows results to eight significant digits. You can
       change this with the '--exponential', '--digits', and '--output-format'
       options.	  The first sets an exponential format (i.e., scientific nota-
       tion) like that used in the original Unix units program, the second al-
       lows  you  to specify a different number of significant digits, and the
       last allows you to control the output appearance using the  format  for
       the  printf() function in the C programming language.  If you only want
       to change the number of significant digits or specify exponential  for-
       mat   type,  use	 the  '--digits'  and  '--exponential'	options.   The
       '--output-format' option affords the greatest control of the output ap-
       pearance,  but  requires at least rudimentary knowledge of the printf()
       format syntax. See Invoking Units for descriptions of these options.

   Format Specification
       The format specification recognized with the  '--output-format'	option
       is  a  subset  of  that for printf().  The format specification has the
       form %[flags][width][.precision]type; it must begin with '%', and  must
       end  with  a  floating-point  type specifier: 'g' or 'G' to specify the
       number of significant digits, 'e' or 'E' for scientific	notation,  and
       'f'  for	 fixed-point decimal.  The ISO C99 standard added 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.  Type length modifiers (e.g., 'L' to indicate a long double)  are
       inapplicable and are not allowed.

       The  default  format  for  units	 is '%.8g'; for greater precision, you
       could specify '-o %.15g'.  The 'g' and 'G' format types use exponential
       format  whenever	 the  exponent	would  be  less	 than -4, so the value
       0.000013 displays as '1.3e-005'.	 These types also use exponential  no-
       tation  when the exponent is greater than or equal to the precision, so
       with the default format, the value 5e7 displays as '50000000'  and  the
       value 5e8 displays as '5e+008'.	If you prefer fixed-point display, you
       might specify '-o %.8f'; however, small numbers will display  very  few
       significant  digits,  and values less than 0.5e-8 will show nothing but
       zeros.

       The format specification may include one or more optional  flags:  '+',
       ' '  (space),  '#',  '-',  or '0' (the digit zero).  The digit-grouping
       flag ''' is allowed with compilers that support it.  Flags are followed
       by  an optional value for the minimum field width, and an optional pre-
       cision specification that begins with a period (e.g., '.6').  The field
       width includes the digits, decimal point, the exponent, thousands sepa-
       rators (with the digit-grouping flag), and the sign if any of these are
       shown.

   Flags
       The  '+' flag causes the output to have a sign ('+' or '-').  The space
       flag ' ' is similar to the '+' flag, except that when the value is pos-
       itive,  it  is prefixed with a space rather than a plus sign; this flag
       is ignored if the '+' flag is also given.  The '+' or ' ' flag could be
       useful  if conversions might include positive and negative results, and
       you wanted to align the decimal points in  exponential  notation.   The
       '#'  flag  causes  the  output  value to contain a decimal point in all
       cases; by default, the output contains a decimal point  only  if	 there
       are  digits  (which  can	 be trailing zeros) to the right of the point.
       With the 'g' or 'G' types, the '#' flag also prevents  the  suppression
       of trailing zeros.  The digit-grouping flag ''' shows a thousands sepa-
       rator in digits to the left of the decimal point.  This can  be	useful
       when displaying large numbers in fixed-point decimal; for example, with
       the format '%f',

       You have: mile
       You want: microfurlong
	       * 8000000.000000
	       / 0.000000

       the magnitude of the first result may not be immediately obvious	 with-
       out counting the digits to the left of the decimal point.  If the thou-
       sands separator is the comma (','), the output with  the	 format	 '%'f'
       might be

       You have: mile
       You want: microfurlong
	       * 8,000,000.000000
	       / 0.000000

       making  the  magnitude  readily apparent.  Unfortunately, few compilers
       support the digit-grouping flag.

       With the '-' flag, the output value is left aligned within  the	speci-
       fied  field  width.   If	 a field width greater than needed to show the
       output value is specified, the '0' (zero) flag causes the output	 value
       to  be  left  padded  with  zeros  until	 the  specified field width is
       reached; for example, with the format '%011.6f',

       You have: troypound
       You want: grain
	       * 5760.000000
	       / 0000.000174

       The '0' flag has no effect if the '-' (left align) flag is given.

   Field Width
       By default, the output value is left aligned and shown with the minimum
       width  necessary	 for the specified (or default) precision.  If a field
       width greater than this is specified, the value shown is right aligned,
       and  padded  on	the  left  with enough spaces to provide the specified
       field width.  A width specification is typically used with  fixed-point
       decimal to have columns of numbers align at the decimal point; this ar-
       guably is less useful with units than with long columnar output, but it
       may  nonetheless assist in quickly assessing the relative magnitudes of
       results.	 For example, with the format '%12.6f',

       You have: km
       You want: in
	       * 39370.078740
	       /     0.000025
       You have: km
       You want: rod
	       *   198.838782
	       /     0.005029
       You have: km
       You want: furlong
	       *     4.970970
	       /     0.201168

   Precision
       The meaning of "precision" depends on the format	 type.	 With  'g'  or
       'G', it specifies the number of significant digits (like the '--digits'
       option); with 'e', 'E', 'f', or 'F', it specifies the maximum number of
       digits to be shown after the decimal point.

       With  the  'g'  and 'G' format types, trailing zeros are suppressed, so
       the results may sometimes have fewer digits than the  specified	preci-
       sion (as indicated above, the '#' flag causes trailing zeros to be dis-
       played).

       The default precision is 6, so '%g' is equivalent to '%.6g', and	 would
       show  the  output  to  six significant digits.  Similarly, '%e' or '%f'
       would show the output with six digits after the decimal point.

       The C printf() function allows a precision of arbitrary	size,  whether
       or not all of the digits are meaningful.	 With most compilers, the max-
       imum internal precision with units is 15 decimal digits (or 13 hexadec-
       imal digits).  With the '--digits' option, you are limited to the maxi-
       mum internal precision; with  the  '--output-format'  option,  you  may
       specify	a  precision  greater than this, but it may not be meaningful.
       In some cases, specifying excess precision can result in rounding arti-
       facts.	For example, a pound is exactly 7000 grains, but with the for-
       mat '%.18g', the output might be

       You have: pound
       You want: grain
	       * 6999.9999999999991
	       / 0.00014285714285714287

       With the format '%.25g' you might get the following:

       You have: 1/3
       You want:
	       Definition: 0.333333333333333314829616256247

       In this case the displayed value includes a series of digits that  rep-
       resent  the  underlying	binary floating-point approximation to 1/3 but
       are not meaningful for the desired computation.	In general, the result
       with  excess precision is system dependent.  The precision affects only
       the display of numbers; if a result relies on physical  constants  that
       are  not	 known	to  the	 specified precision, the number of physically
       meaningful digits may be less than the number of digits shown.

       See the documentation for printf() for more  detailed  descriptions  of
       the format specification.

       The  '--output-format'  option is incompatible with the '--exponential'
       or '--digits' options; if the former is given in combination  with  ei-
       ther of the latter, the format is controlled by the last option given.

LOCALIZATION
       Some units have different values in different locations.	 The localiza-
       tion feature accommodates this by allowing a units data file to specify
       definitions that depend on the user's locale.

   Locale
       A  locale is a subset of a user's environment that indicates the user's
       language and country, and some attendant preferences, such as the  for-
       matting	of  dates.  The units program attempts to determine the locale
       from the POSIX setlocale function; if this cannot be done, units	 exam-
       ines  the environment variables LC_CTYPE and LANG.  On POSIX systems, a
       locale is of the form language_country, where language is the two-char-
       acter  code  from  ISO 639-1 and country is the two-character code from
       ISO 3166-1; language is lower case and country is upper case. For exam-
       ple, the POSIX locale for the United Kingdom is en_GB.

       On systems running Microsoft Windows, the value returned by setlocale()
       is different from that on POSIX systems; units attempts to map the Win-
       dows  value  to	a  POSIX  value	 by  means  of	a  table  in  the file
       'locale_map.txt' in the same directory as the other  data  files.   The
       file  includes  entries	for many combinations of language and country,
       and   can   be	extended   to	include	  other	  combinations.	   The
       'locale_map.txt'	 file  comprises two tab-separated columns; each entry
       is of the form

	    Windows-locale   POSIX-locale

       where POSIX-locale is as described above, and Windows-locale  typically
       spells  out  both the language and country.  For example, the entry for
       the United States is

       English_United States   en_US

       You can force units to run in a desired locale by using	the  '-l'  op-
       tion.

       In order to create unit definitions for a particular locale you begin a
       block of definitions in a unit datafile with '!locale'  followed	 by  a
       locale  name.   The  '!'	 must be the first character on the line.  The
       units program reads the following definitions only if the  current  lo-
       cale  matches.  You end the block of localized units with '!endlocale'.
       Here is an example, which defines the British gallon.

       !locale en_GB
       gallon	    4.54609 liter
       !endlocale

   Additional Localization
       Sometimes the locale isn't sufficient to	 determine  unit  preferences.
       There  could  be regional preferences, or a company could have specific
       preferences.  Though probably uncommon, such  differences  could	 arise
       with  the choice of English customary units outside of English-speaking
       countries.  To address this, units allows specifying  definitions  that
       depend on environment variable settings.	 The environment variables can
       be controlled based on the current locale, or the user can set them  to
       force a particular group of definitions.

       A conditional block of definitions in a units data file begins with ei-
       ther '!var' or '!varnot' following by an environment variable name  and
       then  a space separated list of values.	The leading '!' must appear in
       the first column of a units data file, and  the	conditional  block  is
       terminated  by  '!endvar'.  Definitions in blocks beginning with '!var'
       are executed only if the environment variable is exactly equal  to  one
       of  the	listed values.	Definitions in blocks beginning with '!varnot'
       are executed only if the environment variable does not equal any of the
       list values.

       The  inch  has  long been a customary measure of length in many places.
       The word comes from the Latin uncia meaning "one twelfth," referring to
       its  relationship with the foot.	 By the 20th century, the inch was of-
       ficially defined in English-speaking countries relative	to  the	 yard,
       but  until  1959, the yard differed slightly among those countries.  In
       France the customary inch, which was displaced in 1799  by  the	meter,
       had a different length based on a french foot.  These customary defini-
       tions could be accommodated as follows:

       !var INCH_UNIT usa
       yard	     3600|3937 m
       !endvar
       !var INCH_UNIT canada
       yard	     0.9144 meter
       !endvar
       !var INCH_UNIT uk
       yard	     0.91439841 meter
       !endvar
       !var INCH_UNIT canada uk usa
       foot	     1|3 yard
       inch	     1|12 foot
       !endvar
       !var INCH_UNIT france
       foot	     144|443.296 m
       inch	     1|12 foot
       line	     1|12 inch
       !endvar
       !varnot INCH_UNIT usa uk france canada
       !message Unknown value for INCH_UNIT
       !endvar

       When units reads the above definitions it will  check  the  environment
       variable	 INCH_UNIT  and	 load only the definitions for the appropriate
       section.	 If INCH_UNIT is unset or is not set to one of the four values
       listed,	then  units  will run the last block.  In this case that block
       uses the '!message' command to display  a  warning  message.   Alterna-
       tively that block could set default values.

       In  order to create default values that are overridden by user settings
       the data file can use the '!set' command,  which	 sets  an  environment
       variable	 only  if  it is not already set;  these settings are only for
       the current units invocation and do not persist.	  So  if  the  example
       above  were  preceded  by '!set INCH_UNIT france', then this would make
       'france' the default value for INCH_UNIT.  If  the  user	 had  set  the
       variable in the environment before invoking units, then units would use
       the user's value.

       To link these settings to the user's locale you combine the '!set' com-
       mand  with  the	'!locale' command.  If you wanted to combine the above
       example with suitable locales you could do by preceding the above defi-
       nition with the following:

       !locale en_US
       !set INCH_UNIT usa
       !endlocale
       !locale en_GB
       !set INCH_UNIT uk
       !endlocale
       !locale en_CA
       !set INCH_UNIT canada
       !endlocale
       !locale fr_FR
       !set INCH_UNIT france
       !endlocale
       !set INCH_UNIT france

       These definitions set the overall default for INCH_UNIT to 'france' and
       set default values for four locales appropriately.  The overall default
       setting	comes  last so that it only applies when INCH_UNIT was not set
       by one of the other commands or by the user.

       If the variable given after '!var'  or  '!varnot'  is  undefined,  then
       units  prints an error message and ignores the definitions that follow.
       Use '!set' to create defaults to prevent this situation	from  arising.
       The  '-c'  option  only	checks the definitions that are active for the
       current environment and locale, so when	adding	new  definitions  take
       care to check that all cases give rise to a well defined set of defini-
       tions.

ENVIRONMENT VARIABLES
       The units program uses the following environment variables:

       HOME   Specifies the location of your home directory;  it  is  used  by
	      units  to	 find a personal units data file '.units'.  On systems
	      running Microsoft Windows, the file is 'unitdef.units',  and  if
	      HOME  does  not exist, units tries to determine your home direc-
	      tory from the HOMEDRIVE and HOMEPATH environment	variables;  if
	      these    variables   do	not   exist,   units   finally	 tries
	      USERPROFILE--typically 'C:\Users\username'  (Windows  Vista  and
	      Windows 7) or 'C:\Documents and Settings\username' (Windows XP).

       LC_CTYPE, LANG
	      Checked  to  determine the locale if units cannot obtain it from
	      the operating system.  Sections of the standard units data  file
	      are specific to certain locales.

       MYUNITSFILE
	      Specifies	 your  personal units data file.  If this variable ex-
	      ists, units uses its value rather than searching your  home  di-
	      rectory  for  '.units'.	The  personal  units  file will not be
	      loaded if any data files are given using the '-f' option.

       PAGER  Specifies the pager to use for help and for displaying the  con-
	      formable	units.	 The  help function browses the units database
	      and calls the pager using the '+n'n syntax for specifying a line
	      number.  The default pager is more; PAGER can be used to specify
	      alternatives such as less, pg, emacs, or vi.

       UNITS_ENGLISH
	      Set to either 'US' or 'GB' to choose United  States  or  British
	      volume definitions, overriding the default from your locale.

       UNITSFILE
	      Specifies	 the  units data file to use (instead of the default).
	      You can only specify a single units data file using  this	 envi-
	      ronment  variable.  If units data files are given using the '-f'
	      option, the file specified by UNITSFILE will be  not  be	loaded
	      unless  the  '-f'	 option	 is  given  with  the  empty string (-
	      'units -f ""').

       UNITSLOCALEMAP
	      Windows only; this variable has no effect on Unix-like  systems.
	      Specifies	 the  units locale map file to use (instead of the de-
	      fault).  This variable seldom needs to be set, but you  can  use
	      it to ensure that the locale map file will be found if you spec-
	      ify a location for the units data file using either the '-f' op-
	      tion  or	the  UNITSFILE environment variable, and that location
	      does not also contain the locale map file.

       UNITS_SYSTEM
	      This environment variable is used in the standard data  file  to
	      select CGS measurement systems.  Currently supported systems are
	      'esu', 'emu', 'gauss[ian]', and 'si'.  The default is 'si'.

DATA FILES
       The units program uses two default data files: 'definitions.units'  and
       'currency.units'.   The program can also use an optional personal units
       data file '.units'  ('unitdef.units'  under  Windows)  located  in  the
       user's  home  directory.	  The personal units data file is described in
       more detail in Units Data Files.

       On  Unix-like  systems,	the  data  files  are  typically  located   in
       '/usr/share/units'  if  units is provided with the operating system, or
       in '/usr/local/share/units' if units is compiled from the  source  dis-
       tribution.   Note that the currency file 'currency.units' is a symbolic
       link to another location.

       On systems running Microsoft Windows, the files may be in the same  lo-
       cations if Unix-like commands are available, a Unix-like file structure
       is present (e.g., 'C:/usr/local'),  and	units  is  compiled  from  the
       source  distribution.   If Unix-like commands are not available, a more
       common location is 'C:\Program Files (x86)\GNU\units' (for 64-bit  Win-
       dows installations) or 'C:\Program Files\GNU\units' (for 32-bit instal-
       lations).

       If    units    is    obtained	from	the    GNU    Win32    Project
       (http://gnuwin32.sourceforge.net/),   the   files   are	 commonly   in
       'C:\Program Files\GnuWin32\share\units'.

       If the default units data file is not an absolute pathname, units  will
       look  for the file in the directory that contains the units program; if
       the  file  is  not  found  there,  units	 will  look  in	 a   directory
       ../share/units relative to the directory with the units program.

       You can determine the location of the files by running units --version.
       Running units --info will give you  additional  information  about  the
       files,  how  units will attempt to find them, and the status of the re-
       lated environment variables.

UNICODE SUPPORT
       The standard units data file is in Unicode, using UTF-8 encoding.  Most
       definitions use only ASCII characters (i.e., code points U+0000 through
       U+007F); definitions using non-ASCII characters appear in blocks begin-
       ning with '!utf8' and ending with '!endutf8'.

       The  non-ASCII  definitions are loaded only if the platform and the lo-
       cale support UTF-8.  Platform support is determined when units is  com-
       piled;  the  locale is checked at every invocation of units.  To see if
       your version of units includes Unicode support, invoke the program with
       the '--version' option.

       When Unicode support is available, units checks every line within UTF-8
       blocks in all of the units data files for invalid or non-printing UTF-8
       sequences;  if such sequences occur, units ignores the entire line.  In
       addition to checking validity, units determines the  display  width  of
       non-ASCII  characters  to  ensure  proper positioning of the pointer in
       some error messages and to align columns for the 'search' and '?'  com-
       mands.

       As  of early 2019, Microsoft Windows provides limited support for UTF-8
       in console applications, and accordingly, units does not	 support  Uni-
       code  on Windows.  The UTF-16 and UTF-32 encodings are not supported on
       any platforms.

       If Unicode support is available and definitions that contain  non-ASCII
       UTF-8  characters  are  added  to  a units data file, those definitions
       should be enclosed within '!utf8' ... '!endutf8' to  ensure  that  they
       are  only  loaded when Unicode support is available.  As usual, the '!'
       must appear as the first character on the line.	As discussed in	 Units
       Data  Files,  it's usually best to put such definitions in supplemental
       data files linked by an '!include' command or in a personal units  data
       file.

       When Unicode support is not available, units makes no assumptions about
       character encoding, except that characters in the range 00-7F hexadeci-
       mal  correspond to ASCII encoding.  Non-ASCII characters are simply se-
       quences of bytes, and have no special meanings; for definitions in sup-
       plementary  units  data files, you can use any encoding consistent with
       this assumption.	 For example, if you wish to use non-ASCII  characters
       in  definitions when running units under Windows, you can use a charac-
       ter set such as Windows "ANSI" (code page 1252 in the  US  and  Western
       Europe); if this is done, the console code page must be set to the same
       encoding for the characters to display  properly.   You	can  even  use
       UTF-8,  though  some messages may be improperly aligned, and units will
       not detect invalid UTF-8 sequences.  If you  use	 UTF-8	encoding  when
       Unicode support is not available, you should place any definitions with
       non-ASCII characters outside '!utf8'

       Typeset material other than code examples usually uses the Unicode  mi-
       nus  (U+2212) rather than the ASCII hyphen-minus operator (U+002D) used
       in units; the figure dash (U+2012) and en dash (U+2013) are also	 occa-
       sionally	 used.	To allow such material to be copied and pasted for in-
       teractive use or in units data files, units converts  these  characters
       to  U+002D  before  further processing.	Because of this, none of these
       characters can appear in unit names.

READLINE SUPPORT
       If the readline package has been compiled in, then when units  is  used
       interactively,  numerous	 command  line editing features are available.
       To check if your version of units includes readline, invoke the program
       with the '--version' option.

       For  complete information about readline, consult the documentation for
       the readline package.  Without  any  configuration,  units  will	 allow
       editing	in  the	 style of emacs.  Of particular use with units are the
       completion commands.

       If you type a few characters and then hit ESC followed by ?, then units
       will  display  a	 list  of all the units that start with the characters
       typed.  For example, if you type metr and then request completion,  you
       will see something like this:

       You have: metr
       metre		 metriccup	   metrichorsepower  metrictenth
       metretes		 metricfifth	   metricounce	     metricton
       metriccarat	 metricgrain	   metricquart	     metricyarncount
       You have: metr

       If  there  is a unique way to complete a unit name, you can hit the TAB
       key and units will provide the rest of the unit name.  If units	beeps,
       it  means  that	there is no unique completion.	Pressing the TAB key a
       second time will print the list of all completions.

       The readline library also keeps a history of the values you enter.  You
       can  move  through this history using the up and down arrows.  The his-
       tory is saved to the file '.units_history' in your  home	 directory  so
       that it will persist across multiple units invocations.	If you wish to
       keep work for a certain project separate you  can  change  the  history
       filename using the '--history' option.  You could, for example, make an
       alias for units to units --history .units_history so that  units	 would
       save  separate  history	in  the current directory.  The length of each
       history file is limited to 5000 lines.  Note also that if you run  sev-
       eral  concurrent	 copies of units each one will save its new history to
       the history file upon exit.

UPDATING CURRENCY EXCHANGE RATES
       The units program database includes currency exchange rates and prices
       for some precious metals.  Of course, these values change over time,
       sometimes very rapidly, and units cannot provide real-time values.  To
       update the exchange rates, run units_cur, which rewrites the file con-
       taining the currency rates, typically '/var/lib/units/currency.units'
       or '/usr/local/com/units/currency.units' on a Unix-like system or
       'C:Program Files (x86)\:GNU\:units\:definitions.units' on a Windows
       system.

       This program requires Python (https://www.python.org); either version 2
       or 3 will work.	The program must be run with suitable  permissions  to
       write  the file.	 To keep the rates updated automatically, run it using
       a cron job on a Unix-like system, or a similar scheduling program on  a
       different system.

       Reliable	 free  sources of currency exchange rates have been annoyingly
       ephemeral.  The program currently supports several sources:

	*  FloatRates (https://www/floatrates.com).  The US dollar ('USD')  is
	   the	default	 base currency.	 You can change the base currency with
	   the '-b' option described below.   Allowable	 base  currencies  are
	   listed on the FloatRates website.  Exchange rates update daily.

	*  The	European  Central  Bank (https://www.ecb.europa.eu).  The base
	   currency is always the euro ('EUR').	 Exchange rates update	daily.
	   This	 source offers a more limited list of currencies than the oth-
	   ers.

	*  Fixer (https://fixer.io).  Registration for a free API key  is  re-
	   quired.   With  a free API key, base currency is the euro; exchange
	   rates are updated hourly, the service has  a	 limit	of  1,000  API
	   calls  per month, and SSL encryption (https protocol) is not avail-
	   able.  Most of these restrictions are eliminated  or	 reduced  with
	   paid plans.

	*  open	 exchange rates (https://openexchangerates.org).  Registration
	   for a free API key is required.  With a free API key, the base cur-
	   rency  is  the  US  dollar;	exchange rates are updated hourly, and
	   there is a limit of 1,000 API calls per month.  Most of  these  re-
	   strictions are eliminated or reduced with paid plans.

       ExchangeRate-API.com  (https://www.exchangerate-api.com).   Allows open
       access without an API key, with unlimited API requests.	 Rates	update
       once  a day, and you can choose your base currency.  You can optionally
       sign up for an API key to access paid benefits such as faster data  up-
       date rates.

       The  default source is FloatRates; you can select a different one using
       '-s' option described below.

       Precious	 metals	 pricing  is  obtained	from  Packetizer   (www.packe-
       tizer.com).  This site updates once per day.

       You invoke units_cur like this:

       units_cur [options] [outfile]

       By  default,  the  output  is  written to the default currency file de-
       scribed above; this is usually what you want,  because  this  is	 where
       units  looks  for  the  file.  If you wish, you can specify a different
       filename on the command line and units_cur will write the data to  that
       file.  If you give '-' for the file it will write to standard output.

       The following options are available:

       -h, --help
	      Print a summary of the options for units_cur.

       -V, --version
	      Print the units_cur version number.

       -v, --verbose
	      Give slightly more verbose output when attempting to update cur-
	      rency exchange rates.

       -s source, --source source
	      Specify the source for currency exchange rates;  currently  sup-
	      ported  values  are 'floatrates' (for FloatRates), 'eubank' (for
	      the  European  Central   Bank),	'fixer'	  (for	 Fixer),   and
	      'openexchangerates'  (for open exchange rates); the last two re-
	      quire an API key to be given with the '-k' option.

       -b base, --base base
	      Set the base currency (when allowed by the  site	providing  the
	      data).   base  should  be	 a  3-letter  ISO currency code, e.g.,
	      'USD'.  The specified currency will be  the  primitive  currency
	      unit  used by units.  You may find it convenient to specify your
	      local currency.  Conversions may be more accurate and  you  will
	      be  able	to convert to your currency by simply hitting Enter at
	      the 'You want:' prompt.  This option is ignored  if  the	source
	      does  not	 allow	specifying the base currency.  (Currently only
	      floatrates supports this option.)

       -k key, --key key
	      Set the API key to key for sources that require it.

DATABASE COMMAND SYNTAX
       unit definition
	      Define a regular unit.

       prefix- definition
	      Define a prefix.

       funcname(var)   noerror	  units=[in-units,out-units]	domain=[x1,x2]
       range=[y1,y2] definition(var) ; inverse(funcname)
	      Define  a	 nonlinear  unit  or unit function.  The four optional
	      keywords noerror, units=, range= and domain= can appear  in  any
	      order.  The definition of the inverse is optional.

       tabname[out-units] noerror pair-list
	      Define  a piecewise linear unit.	The pair list gives the points
	      on the table listed in ascending order.  The noerror keyword  is
	      optional.

       !endlocale
	      End a block of definitions beginning with '!locale'

       !endutf8
	      End a block of definitions begun with '!utf8'

       !endvar
	      End a block of definitions begun with '!var' or '!varnot'

       !include file
	      Include the specified file.

       !locale value
	      Load  the	 following  definitions	 only  of the locale is set to
	      value.

       !message text
	      Display text when the database is read unless the	 quiet	option
	      ('-q')  is enabled.  If you omit text, then units will display a
	      blank line.  Messages will also appear in the log file.

       !prompt text
	      Prefix the 'You have:' prompt with the specified text.   If  you
	      omit text, then any existing prefix is canceled.

       !set variable value
	      Sets  the environment variable, variable, to the specified value
	      only if it is not already set.

       !unitlist alias definition
	      Define a unit list alias.

       !utf8  Load the following definitions only if  units  is	 running  with
	      UTF-8 enabled.

       !var envar value-list
	      Load  the block of definitions that follows only if the environ-
	      ment variable envar is set to one of the values  listed  in  the
	      space-separated  value  list.  If envar is not set, units prints
	      an error message and ignores the block of definitions.

       !varnot envar value-list
	      Load the block of definitions that follows only if the  environ-
	      ment  variable  envar  is set to value that is not listed in the
	      space-separated value list.  If envar is not set,	 units	prints
	      an error message and ignores the block of definitions.

FILES
       /usr/local/share/units/definitions.units	 --  the  standard  units data
       file

AUTHOR
       units was written by Adrian Mariano



				25 August 2022			      UNITS(1)