UNITS(1)		    General Commands Manual		      UNITS(1)



NAME
       units -- unit conversion and calculation program

SYNOPSIS
       'units' [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-pur-
       pose  scientific  calculator  that keeps track of units in its calcula-
       tions.  You can form  arbitrary	complex  mathematical  expressions  of
       dimensions  including sums, products, quotients, powers, and even roots
       of dimensions.  Thus you can ensure accuracy  and  dimensional  consis-
       tency  when  working  with long expressions that involve many different
       units that may combine in complex ways; for an illustration,  see  Com-
       plicated 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
       available 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 complete 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
       dimensions,  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 combina-
       tion 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  con-
       formable  with  the  unit  that	you  entered at the 'You have:' prompt
       above.  Conformable 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 expres-
       sion contains non-alphanumeric characters, you may need to  protect  it
       from  interpretation  by the shell using single or double quote charac-
       ters.

       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,  then	'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 environ-
       ment.

       When you invoke 'units' with only one argument, it will print the defi-
       nition  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'
       option,	it  will  print  the  location of this file.  The default file
       includes definitions for all familiar units, abbreviations  and	metric
       prefixes.  It also includes many obscure or archaic units.  Many common
       spelled-out numbers (e.g., 'seventeen') are recognized.

       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
       exactly as a unit name, then the 'units' program will try to  remove  a
       trailing 's', 'es'.  Next units will replace a trailing 'ies' with 'y'.
       If that fails, 'units' will check for a prefix.	The database  includes
       all  of the standard metric prefixes.  Only one prefix is permitted per
       unit, so 'micromicrofarad' will fail.   However,  prefixes  can	appear
       alone  with no unit following them, so 'micro*microfarad' will work, as
       will 'micro microfarad'.

       To find out which units and prefixes are available, read  the  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' pre-
       fix.  In either case, the simple familiar relationships among the units
       are maintained, e.g., 1 'furlong' = 660 'ft', and 1 'USfurlong'	=  660
       'USft',	though	the metric equivalents differ slightly between the two
       cases.  The 'US' prefix or the 'survey' prefix  can  also  be  used  to
       obtain  the  US survey mile and the value of the US yard prior to 1959,
       e.g., 'USmile' or 'surveymile' (but not 'USsurveymile').  To get the US
       value of the statute mile, use either 'USstatutemile' or 'USmile'.

       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	multi-
       plication  using a space, and a high priority numerical division opera-
       tor ('|') 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,
       hyphenated  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
       using  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
       denominator: 'J / mol K'.  The '*' and  '/'  operators  have  the  same
       precedence,  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
       exponent:  'cm3'  is equivalent to 'cm^3'; if the exponent is more than
       one digit, the '^' is required.	You can also use '**' as  an  exponent
       operator.

	  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
       includes  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
       cubic  centimeter.   The 'units' program is limited internally to prod-
       ucts  of  99  units;  accordingly,  expressions	like  'meter^100'   or
       'joule^34' (represented 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  deci-
       mal  exponent to a rational number with q < 100.  If this is not possi-
       ble '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

       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 necessary 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 mes-
       sage:

	  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
       resolved 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
       example,  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',  'ln',
       'log',  'exp', 'acos', 'atan', 'asin', 'cosh', 'sinh', 'tanh', 'acosh',
       'asinh', and 'atanh'.  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
       angle.

       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-
       diameter 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
       example 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
       after 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
       dimensional consistency when converting lengthy unit expressions.   For
       example, 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 division using the slash.  This differs from the  usual
       precedence  rules,  which give multiplication and division equal prece-
       dence, and can be confusing for people who think of units as a calcula-
       tor.

       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 subtraction 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 oper-
       ator  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
       degrees	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
       absolute 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
       requires 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
       result 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
       repeating  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
       effect 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
       appearing  on  the list.  In the second case, 'units' reports disagree-
       ment between the unit you entered and  the  desired  conversion.   This
       conformability 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

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

       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.

       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

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

USING 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  three  different systems of CGS units: electrostatic
       units (ESU), electromagnetic units (EMU), and the Gaussian 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  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.

   Specifying CGS Units
       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 sys-
       tem and works around this restriction by introducing base units for the
       square  roots of length and mass: 'sqrt_cm' and 'sqrt_g'.  The centime-
       ter 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 arguments to the
       '--units' option are 'gauss[ian]', 'esu', 'emu', and 'si'; the argument
       is case insensitive.  The default mode for 'units'  is  SI  units;  the
       only  effect  of  giving  'si'  with the '--units' option is to prepend
       '(SI)' to the 'You have:' prompt.  Giving an unrecognized system gener-
       ates 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 environ-
       ment variable rather than giving the '--units' option at  each  invoca-
       tion.  As usual, an option given on the command line overrides the set-
       ting 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.

   CGS Units Systems
       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.

   Conversions Between Different 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
       dimensions.  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
       various	dimension  units  such	as  LENGTH, TIME, and CHARGE to be the
       appropriate dimension in SI.  The electromagnetic  dimensions  such  as
       B_FIELD	or  E_FIELD  may be useful aids both for conversion and dimen-
       sional analysis in CGS.	You can convert them to or from CGS  in  order
       to perform 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

   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
       invoked,  the  new  results  are appended to the log file.  The time is
       written 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
       default 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
       options are cryptic but require less typing; long-form options  require
       more  typing  but  are more explanatory and may be more mnemonic.  With
       long-form options you need only enter sufficient characters to uniquely
       identify the option to the program.  For example, '--out %f' works, but
       '--o %f' fails because 'units' has other long  options  beginning  with
       'o'.   However,	'--q'  works because '--quiet' is the only long option
       beginning with 'q'.

       Some options require arguments to specify a  value  (e.g.,  '-d 12'  or
       '--digits 12').	 Short-form  options that do not take arguments may be
       concatenated (e.g., '-erS'  is  equivalent  to  '-e -r -S');  the  last
       option  in  such  a  list  may  be  one	that  takes an argument (e.g.,
       '-ed 12').  With short-form options, the space between  an  option  and
       its  argument  is  optional  (e.g.,  '-d12'  is equivalent to '-d 12').
       Long-form options may not be concatenated,  and	the  space  between  a
       long-form  option  and  its argument is required.  Short-form and long-
       form options may be intermixed on the command  line.   Options  may  be
       given  in  any  order,  but when incompatible options (e.g., '--output-
       format' and '--exponential') are given in combination, behavior is con-
       trolled	by  the  last  option  given.  For example, '-o%.12f -e' gives
       exponential format with the default 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  defi-
	      nition.	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
	      decimal point and eleven digits to  the  right  of  the  decimal
	      point.   On most systems, the maximum number of internally mean-
	      ingful digits is 15; if you specify a greater number  than  your
	      system's	maximum, 'units' will print a warning and set the num-
	      ber to the largest meaningful value.  To directly set the  maxi-
	      mum  value,  give  an  argument  of  'max' (e.g., '-d max').  Be
	      aware, of course, that "significant" here  refers  only  to  the
	      display  of numbers; if results depend on physical constants not
	      known to this precision, the physically meaningful precision may
	      be  less	than that shown.  The '--digits' option 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
	      default precision is eight significant digits (seven  digits  to
	      the  right  of  the decimal point); this can be changed with the
	      '--digits' option.  The '--exponential'  option  conflicts  with
	      the '--output-format' option.

       -o format, --output-format format
	      This  option  affords  complete  control over the numeric output
	      format using the specified format. The format is a single float-
	      ing  point  numeric  format for the 'printf()' function in the C
	      programming language.  All compilers support  the  format  types
	      'g'  and 'G' to specify significant digits, 'e' and 'E' for sci-
	      entific 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 specifi-
	      cation.	The '--output-format' option affords the greatest con-
	      trol 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  pre-
	      cision 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 spec-
	      ify up to 25 units files on the command line.  When you use this
	      option, 'units' will load only the files you list on the command
	      line; it will not load the standard file or your personal  units
	      file  unless you explicitly list them.  If filename is the empty
	      string ('-f ""'), the default units file (or that  specified  by
	      'UNITSFILE')  will be loaded in addition to any others specified
	      with '-f'.

       -L logfile, --log logfile
	      Save the results of calculations in the file logfile;  this  can
	      be  useful  if  it is important to have a record of unit 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 filename to the empty string ('-H ""').  This option has  no
	      effect if readline is not available.

       -h, --help
	      Print out a summary of the options for 'units'.

       -m, --minus
	      Causes '-' to be interpreted as a subtraction operator.  This is
	      the default behavior.

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

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

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

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

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

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

       -V, --version
	      Print  the  program  version number, tell whether the 'readline'
	      library has been included, tell whether UTF-8 support  has  been
	      included;  give  the  locale,  the location of the default 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  addi-
	      tional  information about how 'units' locates the related files.
	      On  systems  running  Microsoft  Windows,  the  status  of   the
	      'UNITSLOCALE'  environment  variable  and  information about the
	      related locale map are also given.  This option  is  usually  of
	      interest only to developers and administrators, but it can some-
	      times 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
	      description of locale format.

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

       -s, --strict
	      Suppress	conversion  of	units  to their reciprocal units.  For
	      example, 'units' will normally convert hertz to seconds  because
	      these  units  are  reciprocals of each other.  The strict option
	      requires that units be strictly conformable to perform a 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
	      options: '--strict' '--quiet'  '--one-line'  '--compact'.   When
	      combined with '--version' it produces a display showing only the
	      program name and version number.

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

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

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
       modify this data file if you have  appropriate  user  privileges,  it's
       usually	better to put extensions in separate files so that the defini-
       tions 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
       important;  later  definitions replace earlier ones, so any definitions
       in an included file will override  definitions  before  the  '!include'
       statement  in the standard units data file.  With normal invocation, no
       warning is given about redefinitions; to ensure that you don't have  an
       unintended  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 variable; if this variable exists, its value is used  with-
       out  searching  your  home directory.  The default units data files are
       described in more detail 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
       minus  ('-';  U+2212),  and  en dash ('-'; U+2013) are converted to the
       operator '-', 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, 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.  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
       redefinition.  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 func-
       tional 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
       results, the arguments of these functions  need	to  have  the  correct
       dimensions  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
       requires  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  per-
       form  error checking on function arguments, and also to assign units to
       domain 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
       inverse 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
       obtain  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
       infinity.  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 microfurlongs, and can not adjust the parameter  value  of	900 mm
       for  comparison.   Without  units,  numerical values other than zero or
       plus or minus infinity for domain or range endpoints  are  meaningless,
       and accordingly 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
       appended 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 piece-
       wise linear unit is encountered.  For example, the relationship between
       ANSI  coated  abrasive  designation and mean particle size is non-mono-
       tonic 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
       really  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 con-
       firm that there are no actual errors before adding the  'noerror'  key-
       word.

   Defining Unit List Aliases
       Unit  list  aliases  are  treated  differently  from  unit definitions,
       because 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
       included 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
       include 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
       allows 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
       format  type,  use  the	'--digits'  and  '--exponential' options.  The
       '--output-format' option affords the greatest  control  of  the	output
       appearance,   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
       notation 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
       arguably  is  less  useful with 'units' than with long columnar output,
       but it may nonetheless assist in quickly assessing the relative	magni-
       tudes 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 hexa-
       decimal digits).  With the '--digits' option, you are  limited  to  the
       maximum	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
       either 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'
       examines  the  environment  variables  'LC_CTYPE' and 'LANG'.  On POSIX
       systems, a locale is of the form language'_'country, where language  is
       the  two-character 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 example, 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
       Windows	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'
       option.

       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
       locale	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
       either '!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
       officially 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 val-
       ues  listed,  then  'units' will run the last block.  In this case that
       block uses the '!message' command to display a warning message.	Alter-
       natively 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 fol-
       low.  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
       definitions.

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
	      directory from the 'HOMEDRIVE' and 'HOMEPATH' environment  vari-
	      ables;  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
	      exists, 'units' uses its value rather than searching  your  home
	      directory  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
	      default).  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'
	      option  or  the 'UNITSFILE' environment variable, and that loca-
	      tion 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
       locations  if Unix-like commands are available, a Unix-like file struc-
       ture 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
       Windows	installations)	or  'C:\Program Files\GNU\units'  (for	32-bit
       installations).

       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' pro-
       gram; 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 related 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
       locale support UTF-8.  Platform support is determined when  'units'  is
       compiled; 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 '?' commands.

       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
       hexadecimal  correspond	to  ASCII  encoding.  Non-ASCII characters are
       simply sequences of bytes, and have no special  meanings;  for  defini-
       tions  in supplementary units data files, you can use any encoding con-
       sistent with this assumption.  For example, if you  wish  to  use  non-
       ASCII characters in definitions when running 'units' under Windows, you
       can use a character 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'  ...   '!endutf8'
       blocks--otherwise, they will be ignored.

       Typeset	material  other  than  code  examples usually uses the Unicode
       minus (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
       occasionally used.  To allow such material to be copied and pasted  for
       interactive  use or in units data files, 'units' converts these charac-
       ters 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	avail-
       able.   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  char-
       acters typed.  For example, if you type 'metr' and then request comple-
       tion, 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
       several 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
       containing 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
	   required.  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
	   restrictions 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
       described  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 out-
       put.

       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
	      require 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



				 19 March 2019			      UNITS(1)
