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.

       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 (gauss[ian]|esu|emu), --units (gauss[ian]|esu|emu)
	      Specify a CGS units system: Gaussian, ESU, or EMU.

       -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  controled  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.

       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



			       22 September 2020		      UNITS(1)
