4mUNITS24m(1)			 General Commands Manual		   4mUNITS24m(1)

1mNAME0m
       units -- unit conversion and calculation program

1mSYNOPSIS0m
       1munits 22m[4mfrom-unit24m [4mto-unit24m]]

       1munits 22m[1m-hcemnSpqsv1trUVI22m] [1m-d 4m22mdigits24m] [1m-f 4m22munits24m 4mfile24m] [1m-L 4m22mlogfile24m]
	     [1m-l 4m22mlocale24m] [1m-o 4m22mformat24m] [1m-u 4m22munit24m 4msystem24m]
	     [4mfrom-unit24m [4mto-unit24m]]

       1munits 22m[1m--help22m] [1m--check22m] [1m--check-verbose22m] [1m--verbose-check22m] [1m--list-0m
	     1munits22m] [1m--digits 4m22mdigits24m] [1m--exponential22m] [1m--file 4m22munits24m 4mfile24m]
	     [1m--log 4m22mlogfile24m] [1m--locale 4m22mlocale24m] [1m--minus22m] [1m--oldstar22m]
	     [1m--newstar22m] [1m--nolists22m] [1m--show-factor22m] [1m--conformable22m]
	     [1m--output-format 4m22mformat24m] [1m--product22m] [1m--quiet22m] [1m--silent22m]
	     [1m--strict22m] [1m--verbose22m] [1m--compact22m] [1m--one-line22m] [1m--terse22m]
	     [1m--round22m] [1m--unitsfile22m] [1m--units 4m22munits24m 4msystem24m] [1m--version22m]
	     [1m--info22m]
	     [4mfrom-unit24m [4mto-unit24m]]

1mDESCRIPTION0m
       The  4munits24m	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 4mTemperature24m 4mConversions24m.  The program can also perform  conversions
       from  and  to sums of units, such as converting between meters and feet
       plus inches.

       But Fahrenheit to Celsius is linear, you insist.	 Not so.  A  transfor-
       mation  4mT24m  is  linear  if  4mT24m(4mx24m + 4my24m) = 4mT24m(4mx24m) + 4mT24m(4my24m)  and  this  fails for
       4mT24m(4mx24m) = 4max24m + 4mb24m.  This transformation	is  affine,  but  not  linear--see
       https://en.wikipedia.org/wiki/Linear_map.

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

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

       The units are defined in several external data files.  You can use  the
       extensive  data	files  that  come with the 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 files.

       You can change the default behavior of 4munits24m with various options given
       on the command line. See 4mInvoking24m 4mUnits24m for a description of the avail-
       able options.

1mADDITIONAL DOCUMENTATION0m
       This manual is also available in PDF and HTML:

	  8;;https://www.gnu.org/software/units/manual/units.pdfhttps://www.gnu.org/software/units/manual/units.pdf8;;
	  8;;https://www.gnu.org/software/units/manual/units.htmlhttps://www.gnu.org/software/units/manual/units.html8;;

1mINTERACTING WITH 4mUNITS0m
       To  invoke  4munits24m for interactive use, type 4munits24m at your shell prompt.
       The program will print something like this:

       Currency exchange rates from FloatRates (USD base) on 2023-07-08
       3612 units, 109 prefixes, 122 nonlinear units
       You have:

       At the `You have:' prompt, type the quantity and	 units	that  you  are
       converting  4mfrom24m.	For  example,  if you want to convert ten meters to
       feet, type 4m1024m 4mmeters24m.	Next, 4munits24m will print `You want:'.  You  should
       type  the  units you want to convert 4mto24m.  To convert to feet, you would
       type 4mfeet24m.	If the 4mreadline24m library was compiled in, then 4mtab24m will com-
       plete unit names. See 4mReadline24m 4mSupport24m for more information about 4mread-0m
       4mline24m.  To quit the program type 4mquit24m or 4mexit24m 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, 4munits24m 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 4munits24m program prints the inverse because sometimes  it	is  a  more
       convenient  number.   In	 the  example  above, for example, the inverse
       value is an exact conversion: a foot  is	 exactly  0.03048  dekameters.
       But the number given the other direction is inexact.

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

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

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

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

       If you request a conversion between units that measure  reciprocal  di-
       mensions,  then 4munits24m 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 4munits24m 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 4mEnter24m 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 4munits24m indicates that the jansky is defined to be  equal
       to  a  fluxunit which in turn is defined to be a certain combination of
       watts, meters, and hertz.  The fully reduced (and in this case somewhat
       more cryptic) form appears on the far right.  If the  ultimate  defini-
       tion and the fully reduced form are identical, the latter is not shown:

       You have: B
       You want:
	       Definition: byte = 8 bit

       The  fully  reduced form 4mis24m shown if it and the ultimate definition are
       equivalent but not identical:

       You have: N
       You want:
	       Definition: newton = kg m / s^2 = 1 kg m / s^2

       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 4m?24m at the `You want:' prompt.
       The program will display a list of named	 units	that  are  conformable
       with  the  unit that you entered at the `You have:' prompt above.  Con-
       formable unit 4mcombinations24m will not appear on this list.

   1mInteractive Commands0m
       Typing 4mhelp24m at either prompt displays a short help	message.   You	can
       also  type  4mhelp24m  followed by a unit name.	This will invoke a pager on
       the units database 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.	 If your pager allows, you may want to
       scroll backwards, e.g. with `b', because	 sometimes  a  longer  comment
       about  a unit or group of units will appear before the definition.  You
       can generally quit out of the pager by pressing `q'.

       Typing 4msearch24m 4mtext24m will display a list of all units whose names contain
       4mtext24m as a substring along with their definitions.  This may help in the
       case where you aren't sure of the right	unit  name.   Typing  4msearch24m 4m.0m
       will  display  a	 list  of all units; this can be helpful if you aren't
       sure of an appropriate substring, though examining the  output  can  be
       tedious.	  Here	`.' is a special argument to the 4msearch24m command, not a
       regular expression.  If you want to use a regular expression to	search
       units  4mand24m	their definitions, the `--list-units' option will display a
       list of all units, which can be sent to a filter such as 4mgrep24m.   Typing
       4msearch24m 4m_24m  will	 display a list of all assigned runtime variables--whose
       names begin with `_'--without including all units  whose	 names	simply
       4mcontain24m  `_'.   See 4mVariables24m 4mAssigned24m 4mat24m 4mRun24m 4mTime24m for more information
       on runtime variables.

       Typing 4mversion24m will	 display  the  4munits24m  version  number;  unlike  the
       `--version' option, only the version number is shown, regardless of any
       other settings.	Full information is available with the 4minfo24m command.

       Typing  4minfo24m  will display the same information as the `--info' option,
       described in 4mInvoking24m 4mUnits24m.

       Many values set by command-line options can also be  set	 interactively
       by  typing  4mset24m 4moption=value24m; typing 4mset24m 4moption24m will show the value for
       that option.  Typing 4mset24m will show a list of options that can  be  set;
       options	set  to	 other	than default values will have a prepended `*'.
       See 4mSetting24m 4mOptions24m 4mInteractively24m for more information.

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

       If you type

       units "2 liters" quarts

       then 4munits24m 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.

       4munits24m  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, 4munits24m will return	success	 (zero)	 to
       the  calling  environment.   If	you  enter non-conformable units, then
       4munits24m will print a message giving the reduced form of each unit and	 it
       will return failure (nonzero) to the calling environment.

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

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

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

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

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

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

   1mFinding Units0m
       The  4munits24m database includes many units, and it can sometimes be diffi-
       cult to remember every name.  The interactive 4msearch24m  command  examines
       only  unit  names, so it cannot be used to find units whose 4mdefinitions0m
       contain a pattern.  If 4munits24m is invoked with the `--list-units' option,
       the output can be sent to a filter such as  4mgrep24m,  examining  the  unit
       name 4mand24m the definition.  For example,

       units --list-units | grep ';'
       dms				      deg;arcmin;arcsec
       ftin				      ft;in;1|8 in
       ftin16				      ft;in;1|16 in
       ftin32				      ft;in;1|32 in
       ftin4				      ft;in;1|4 in
       ftin64				      ft;in;1|64 in
       ftin8				      ft;in;1|8 in
       hms				      hr;min;sec
       inchfine				      in;1|8 in;1|16 in;1|32 in;1|64 in
       time				      year;day;hr;min;sec
       uswt				      lb;oz
	 .  .  .

       could  find  all	 unit  lists,  which include at least one semicolon in
       their definitions.

       The 4msearch24m command doesn't support regular expressions,  but  with	the
       `--list-units'  option the output can be sent to a filter such as 4mgrep24m,
       which does.  If you expect a long list of results,  you	can  send  the
       output of the filter to a pager.	 For example,

       units --list-units | grep 'paper[[:space:]]' | more
       A0paper				      841 mm 1189 mm
       A10paper				      26 mm 37 mm
       A1paper				      594 mm 841 mm
       A2paper				      420 mm 594 mm
       A3paper				      297 mm 420 mm
       A4paper				      210 mm 297 mm
       A5paper				      148 mm 210 mm
       A6paper				      105 mm 148 mm
       A7paper				      74 mm 105 mm
       A8paper				      52 mm 74 mm
       A9paper				      37 mm 52 mm
	 .  .  .

       could show a list of all defined paper sizes.

1mUNIT DEFINITIONS0m
       The  conversion	information  is	 read  from  several units data files:
       `definitions.units',    `elements.units',     `currency.units',	   and
       `cpi.units', which are usually located in the `/usr/share/units' direc-
       tory.   If you invoke 4munits24m with the `-V' option, it will print the lo-
       cation of these files.  The default main file includes definitions  for
       all  familiar  units,  abbreviations  and metric prefixes.  It also in-
       cludes many obscure or archaic units.  Many common spelled-out  numbers
       (e.g., `seventeen') are recognized.

   1mPhysical Constants0m
       Many constants of nature are defined, including these:

       pi	   ratio of circumference of a circle to its 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 numerous other constants.  Also in-
       cluded are the densities of various ingredients used in baking so  that
       `2 cups	flour_sifted' can be converted to `grams'.  This is not an ex-
       haustive list.  Consult the units data file to see the  complete	 list,
       or to see the definitions that are used.

   1mAtomic Masses of the Elements0m
       The data file `elements.units' includes atomic masses for most elements
       and most known isotopes.	 If the mole fractions of constituent isotopes
       are known, an elemental mass is calculated from the sum of the products
       of  the	mole fractions and the masses of the constituent isotopes.  If
       the mole fractions are not known, the mass of the most stable isotope--
       if known--is given as the elemental  mass.   For	 radioactive  elements
       with  atomic  numbers 95 or greater, the mass number of the most stable
       isotope is not specified, because the list of studied isotopes is still
       incomplete.  If no stable isotope is known, no elemental mass is given,
       and you will need to choose the most appropriate isotope.

       The data are obtained from the US National Institute for Standards  and
       Technology	(NIST):	     https://physics.nist.gov/cgi-bin/Composi-
       tions/stand_alone.pl?ele=&all=all&ascii=ascii2&isotype=all.	   The
       `elements.units'	 file can be generated from these data using the 4melem-0m
       4mcvt24m command included with the distribution.

   1mCurrency Exchange Rates and Consumer Price Index0m
       The data file `currency.units' includes currency conversion rates;  the
       file  `cpi.units' includes the US Consumer Price Index (CPI), published
       by the US Bureau of Labor Statistics.  The data are updated monthly  by
       the  BLS;  see 4mUpdating24m 4mCurrency24m 4mExchange24m 4mRates24m 4mand24m 4mCPI24m for information
       on updating `currency.units' and `cpi.units'.

   1mEnglish Customary Units0m
       English customary units differ in various ways among 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 4munits24m 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  4mInterna-0m
       4mtional24m  4mYard24m.	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, pole, perch, and link) in terms of the previous
       value for the foot, which was termed the 4mUS24m 4msurvey24m 4mfoot24m.	 The  US  de-
       fined  a	 4mUS24m  4msurvey24m 4mmile24m as 5280 US survey feet, and defined a 4mstatute0m
       4mmile24m as a US survey mile.  The US values for these units differed  from
       the international values by about 2 ppm.

       The 1959 redefinition of the foot was legally binding in the US but al-
       lowed continued use of the previous definition of the foot for geodetic
       surveying.   It	was  assumed that this use would be temporary, but use
       persisted, leading to confusion and errors, and it was at odds with the
       intent of uniform standards.  Since January 1, 2023, the US survey foot
       has been officially deprecated (85 FR 62698), with its use  limited  to
       historical and legacy applications.

       The  4munits24m	program	 has always used the international values for these
       units; the legacy US values can be obtained by using either the `US' or
       the `survey' prefix.  In either case, the simple familiar relationships
       among the units are maintained, e.g., 1 `furlong' =  660	 `ft',	and  1
       `USfurlong' = 660 `USft', though the metric equivalents differ slightly
       between the two cases.  The `US' prefix or the `survey' prefix can also
       be used to obtain the US survey mile and the value of the US yard prior
       to  1959,  e.g., `USmile' or `surveymile' (but 4mnot24m `USsurveymile').	 To
       get the US value of the statute mile,  use  either  `USstatutemile'  or
       `USmile'.   The pre-1959 UK values for these units can be obtained with
       the prefix `UK'.

       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  US acre was officially defined in terms of the US survey foot, but
       4munits24m has used a definition based on the international foot; the  4munits0m
       definition  is  now the same as the official US value.  If you want the
       previous US acre, use `USacre' and similarly use `USacrefoot'  for  the
       previous	 US  version of that unit.  The difference between these units
       is about 4 parts per million.

   1mMiscellaneous Notes on Unit Definitions0m
       The `pound' is a unit of mass.  To get force,  multiply	by  the	 force
       conversion  unit `force' or use the shorthand `lbf'.  (Note that `g' is
       already taken as the standard abbreviation for  the  gram.)   The  unit
       `ounce'	is  also  a  unit of mass.  The fluid ounce is `fluidounce' or
       `floz'.	When British capacity units differ from their US counterparts,
       such as the British Imperial gallon, the unit is defined both ways with
       `br' and `us' prefixes.	Your locale settings will determine the	 value
       of  the	unprefixed  unit.  Currency is prefixed with its country name:
       `belgiumfranc', `britainpound'.

       When searching for a unit, if the specified string does not appear  ex-
       actly  as  a  unit  name,  then	the 4munits24m program will try to remove a
       trailing `s', `es'.  Next units will replace a trailing `ies' with `y'.
       If that fails, 4munits24m 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  default
       units data files; the main data file is extensively annotated.

1mUNIT EXPRESSIONS0m
   1mOperators0m
       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	4munits24m  is invoked with its default options.  Addition-
       ally, 4munits24m supports some extensions, including high priority multipli-
       cation using a space, and a high priority numerical  division  operator
       (`|') that can simplify some expressions.

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

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

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

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

       You can use parentheses for grouping:

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

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

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

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

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

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

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

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

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

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

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

       You have: 2^radian
			^
       Exponent not dimensionless

       If the base unit is not dimensionless, the exponent must be a  rational
       number  4mp24m/4mq24m,  and  the	 dimension  of the unit must be a power of 4mq24m, 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 4munits24m cannot represent dimensions  with	 exponents  greater
       than  99,  a  fully reduced exponent must have 4mq24m < 100.  When raising a
       non-dimensionless unit to a power, 4munits24m attempts to convert a  decimal
       exponent	 to  a	rational number with 4mq24m < 100.  If this is not possible
       4munits24m 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.

   1mSums and Differences of Units0m
       You  may	 sometimes want to add values of different units that are out-
       side the SI.  You may also wish to use 4munits24m 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
					     ^
       Invalid sum of non-conformable units

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

       You have: lightyear + cm

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

       You have: 2+1|2 cups
			  ^
       Invalid 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 4mmultiplication24m so
       the result is the same as `1 cup'.

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

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

       You have: 2 ft 3 ft 12 ft
       You want: stere
	       * 2.038813
	       / 0.49048148
       You have: $ 5 / yard
       You want: cents / inch
	       * 13.888889
	       / 0.072

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

   1mBuilt-in Functions0m
       Several built-in functions are provided: `sin', `cos', `tan', `secant',
       `csc',  `cot',  `asin',	`acos',	 `atan',  `asecant',  `acsc',  `acot',
       `sinh',	`cosh',	 `tanh',  `sech',  `csch',  `coth',  `asinh', `acosh',
       `atanh', `asech', `acsch', `acoth', `exp', `ln', `log', `abs', `round',
       `floor', `ceil', `factorial', `Gamma', `lnGamma',  `erf',  and  `erfc';
       the  function  `lnGamma'	 is the natural logarithm of the `Gamma' func-
       tion.

       The `sin', `cos', `tan', `secant', `csc' and  `cot'  functions  require
       either  a  dimensionless argument or an argument with dimensions of an-
       gle.

       You have: sin(30 degrees)
       You want:
	       Definition: 0.5
       You have: sin(pi/2)
       You want:
	       Definition: 1
       You have: sin(3 kg)
			 ^
       Unit not dimensionless

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

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

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

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

       You have: sqrt(acre)
       You want: feet
	       * 208.71074
	       / 0.0047913202
       You have: (400 W/m^2 / stefanboltzmann)^(1/4)
       You have:
	       Definition: 289.80882 K
       You have: cuberoot(hectare)
				 ^
       Unit not a root

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

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

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

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

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

       You have: m_
		  ^
       Parse error

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

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

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

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

       Accordingly,  `_'  serves no purpose when 4munits24m is invoked non-interac-
       tively.

       If 4munits24m is invoked with the `--verbose' option (see  4mInvoking24m	 4mUnits24m),
       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.

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

	    Delta 4mP24m = (8 / pi)^2 (4mrho24m 4mfLQ24m^2) / 4md24m^5,

       where Delta 4mP24m is the pressure drop, 4mrho24m is the mass density, 4mf24m  is  the
       (dimensionless)	friction factor, 4mL24m is the length of the pipe, 4mQ24m is the
       volumetric flow rate, and 4md24m is the pipe diameter.  You  might  want	 to
       have the equation in the form

	    Delta 4mP24m = A1 4mrho24m 4mfLQ24m^2 / 4md24m^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

   1mVariables Assigned at Run Time0m
       Unit definitions are fixed once 4munits24m has finished	reading	 the  units
       data  file(s), but at run time you can assign unit expressions to vari-
       ables whose names begin with an underscore, using the syntax

       _4mname24m = 4m<unit24m 4mexpression>0m

       This can help manage a long calculation by saving intermediate  quanti-
       ties  as	 variables  that you can use later.  For example, to determine
       the shot-noise-limited signal-to-noise ratio (SNR) of an imaging system
       using a helium-neon laser, you could do

       You have: _lambda = 632.8 nm	       # laser wavelength
       You have: _nu = c / _lambda	       # optical frequency
       You have: _photon_energy = h * _nu
       You have: _power = 550 uW
       You have: _photon_count = _power * 500 ns / _photon_energy
       You have: _snr = sqrt(_photon_count)
       You have: _snr
       You want:
	       Definition: sqrt(_photon_count) = 29597.922

       Except for beginning with an underscore, runtime variables  follow  the
       same  naming  rules as units.  Because names beginning with `_' are re-
       served for these variables and unit names cannot begin with  `_',  run-
       time  variables can never hide unit definitions.	 Runtime variables are
       undefined until you make an assignment to them, so if you give  a  name
       beginning  with	an underscore and no assignment has been made, you get
       an error message.

       When you assign a unit expression to a runtime variable,	 4munits24m  checks
       the expression to determine whether it is valid, but the resulting def-
       inition	is  stored  as	a text string that is not reduced to primitive
       units.  The text will be processed anew each time you use the  variable
       in a conversion or calculation;	this means that if your definition de-
       pends on other runtime variables (or the special variable `_'), the re-
       sult  of	 calculating  with  your  variable will change if any of those
       variables change.  A dependence need not be direct.

       Continuing the example of the laser above, suppose you  have  done  the
       calculation  as shown.  You now wonder what happens if you switch to an
       argon laser:

       You have: _lambda = 454.6 nm
       You have: _snr
       You want:
	       Definition: sqrt(_photon_count) = 25086.651

       If you then change the power:

       You have: _power = 1 mW
       You have: _snr
       You want:
	       Definition: sqrt(_photon_count) = 33826.834

       Instead of having to reenter or edit a lengthy expression when you per-
       form another calculation, you need only enter values  that  change;  in
       this respect, runtime variables are similar to a spreadsheet.

       The  more times a variable appears in an expression that depends on it,
       the greater the benefit of having a calculation using  that  expression
       reflect	changes	 to  that  variable.   For example, the length of day-
       light--the time the Sun is above the horizon--at a given	 latitude  and
       declination of the Sun is given by

	    4mL24m = acos((sin 4mh24m - sin 4m<phi>24m sin 4m<delta>24m) /
			   (cos 4m<phi>24m cos 4m<delta>24m))

       where  4mL24m  is  the day length, 4mh24m is the altitude, 4m<phi>24m is the latitude,
       and 4m<delta>24m is the Sun's declination.

       The result above is in sidereal time; the length in solar time  is  ob-
       tained by multiplying by

       siderealday / day

       By  convention,	the Sun's altitude at rise or set is -50' to allow for
       atmospheric refraction and the semidiameter of its disk.	 At the summer
       solstice in the northern hemisphere, the Sun's declination is  approxi-
       mately 23.44<degree>; to find the length of the longest day of the year
       for a latitude of 55<degree>, you could do

       You have: _alt = -50 arcmin
       You have: _lat = 55 deg
       You have: _decl = 23.44 deg
       You have: _num = sin(_alt) - sin(_lat) sin(_decl)
       You have: _denom = cos(_lat) cos(_decl)
       You have: _sday = 2 (acos(_num / _denom) / circle) 24 hr
       You have: _day = _sday siderealday / day
       You have: _day
       You want: hms
	       17 hr + 19 min + 34.895151 sec

       At   the	 winter	 solstice,  the	 Sun's	declination  is	 approximately
       -23.44<degree>, so you could calculate the length of the	 shortest  day
       of the year using:

       You have: _decl = -23.44 deg
       You have: _day
       You want: hms
	       7 hr + 8 min + 40.981084 sec

       Latitude	 and declination each appear twice in the expression for _day;
       the result in the examples above is updated by changing only the	 value
       of the declination.

       It  may	seem  easier--and less subject to error--to simply specify the
       new value of  _decl  as	the  negative  of  the	current	 value	(e.g.,
       `_decl = -_decl').  This doesn't work; when you make an assignment with
       the `=' operator, the definition is stored as entered, including possi-
       ble  dependencies  on variables.	 But if you attempt an assignment that
       is ultimately self-referential, the current definition is retained, and
       you get an error message.  For example,

       You have: _decl = 23.44 deg
       You have: _decl = -_decl
       Circular unit definition

       You can overcome this by using the `:='	operator,  which  reduces  the
       right hand side to primitive units before making the assignment, elimi-
       nating any dependencies on variables.  Returning to the example above,

       You have: _decl = 23.44 deg
       You have: _decl = -_decl
       Circular unit definition
       You have: _decl := -_decl
       You have: _decl
       You want: deg
	       * -23.44
	       / -0.042662116

       This  works  to	much the same effect as if the assignment had been en-
       tered literally, e.g.,

       You have: _decl = -23.44 deg

       but the actual definition is in primitive units--in this case, radians:

       You have: _decl = 23.44 deg
       You have: _decl := -_decl
       You have: _decl
       You want:
	       Definition: -0.40910517666747087 radian = -0.40910518 radian

       Definitions are text strings, and a redefinition using  `:='  is	 given
       with  enough  digits maintain the full precision of the current defini-
       tion when converted back to a number; because it is a string, all  dig-
       its are displayed when showing the definition, regardless of the numer-
       ical display precision, so you may see more digits than expected.

       A runtime variable must be assigned before it can be used in an assign-
       ment;  in  the  first  of  the three examples above, giving the general
       equation before the values for _alt, _lat, and _decl had been  assigned
       would result in an error message.

       You can display a list of runtime variables you have assigned by typing
       4msearch24m 4m_24m.

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

       The star operator (`*') included in this 4munits24m program has, by default,
       the same precedence as division, and hence follows the usual precedence
       rules.	For  backwards	compatibility  you  can	 invoke 4munits24m 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 4munits24m  program  treated
       it  as a multiplication operator.  Because 4munits24m provides several other
       ways to obtain unit products, and because `-' is a subtraction operator
       in general algebraic expressions, 4munits24m treats the binary `-' as a sub-
       traction operator by default.   For  backwards  compatibility  use  the
       `--product' option, which causes 4munits24m to treat the binary `-' operator
       as  a  product  operator.  When `-' is a multiplication operator it has
       the same precedence as multiplication with a space, giving it a	higher
       precedence than division.

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

1mNONLINEAR UNIT CONVERSIONS0m
       Nonlinear units are represented using functional notation.   They  make
       possible nonlinear unit conversions such as temperature.

   1mTemperature Conversions0m
       Conversions  between temperatures are different from linear conversions
       between temperature 4mincrements24m--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(4mx24m)' not as a function but as a notation that  indicates
       that  4mx24m should have units of `tempF' attached to it.  See 4mDefining24m 4mNon-0m
       4mlinear24m 4mUnits24m.	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(4mx24m)' is to ab-
       solute temperature, so that

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

       gives the same result as

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

       But  if	you  convert  `tempF(4mx24m)' 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 `temp4mX24m' units when convert-
       ing to a temperature rather than converting a temperature increment.

       The  `tempC()'  and  `tempF()'  definitions are limited to positive ab-
       solute 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

   1mUS Consumer Price Index0m
       4munits24m includes the US Consumer Price Index published by the	 US  Bureau
       of  Labor  Statistics.	Several functions that use this value are pro-
       vided: `cpi', `cpi_now', `inflation_since', and `dollars_in'.

       The `cpi' function gives the CPI for a specified decimal year.  A 4mdeci-0m
       4mmal24m 4myear24m is given as the year plus the fractional part of the year; be-
       cause of leap years and the different lengths of months, calculating an
       exact value for the fractional part can be tedious, but	for  the  pur-
       poses  of  CPI, an approximate value is usually adequate.  For example,
       1 January 2000 is 2000.0, 1 April  2000	is  2000.25,  1 July  2000  is
       2000.4986,  and 1 October 2000 is 2000.75.  Note also that the CPI data
       update monthly; values in between months are linearly interpolated.

       In the middle of 1975, the CPI was

       You have: cpi(1975.5)
       You want:
	       Definition: 53.6

       The value of the CPI for a month is usually published  sometime	around
       the  20th  day  of  the following month; the latest value of the CPI is
       available with `cpi_now'.  On 7 January 2024, the value was

       You have: cpi_now
       You want:
	       Definition: UScpi_now = 307.051

       This means that the CPI was 307.015 on 1 December 2023.	The  `cpi_now'
       variable can only present the most recent data available, so it can lag
       the  current CPI by several weeks.  The decimal year of the last update
       is available with `cpi_lastdate'.

       The `inflation_since' function provides a convenient way	 to  determine
       the  inflation factor from a specified decimal year to the latest value
       in the CPI table.  For example, on 7 January 2024:

       You have: inflation_since(1970)
       You want:
	       Definition: 8.1445889

       In other words, goods that cost 1 US$ in 1970 would cost	 8.14  US$  on
       1 December 2023.

       The  `inflation_since' function can be used to determine an annual rate
       of inflation.  The earliest US CPI data are from about 1913.1; the  ap-
       proximate time between then and 7 January 2024 is 110.9 years.  The ap-
       proximate annual inflation rate for that period is then

       You have: inflation_since(1913.1)^1|110.9 - 1
       You want: %
	       * 3.1548115
	       / 0.31697614

       The  inflation  rate for any time period can be found from the ratio of
       the CPI at the end of the period to that of the beginning:

       You have: (cpi(1982)/cpi(1972))^1|10 - 1
       You want: %
	       * 8.6247033
	       / 0.11594602

       The period 1972-1982 was indeed one of high inflation.

       The `dollars_in' function is similar to `inflation_since' but its  out-
       put is in US$ rather than dimensionless:

       You have: dollars_in(1970)
       You want:
	       Definition: 8.1445889 US$

       A typical use might be

       You have: 250 dollars_in(1970)
       You want: $
	       * 2036.1472
	       / 0.00049112362

       Because `dollars_in' includes the units, you should not include them at
       the  `You have:'	 prompt.  You can also use `dollars_in' to convert be-
       tween two specified years:

       You have: 250 dollars_in(1970)
       You want: dollars_in(1950)
	       * 156.49867
	       / 0.0063898305

       which shows that 250 US$ in 1970 would have equivalent purchasing power
       to 156 US$ in 1950.

   1mOther Nonlinear Units0m
       Some other examples of nonlinear	 units	are  numerous  different  ring
       sizes  and  wire	 gauges, screw gauges, pipe and tubing sizes, 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 circle and the volume	of  a  sphere.
       See the standard units data file for more details.

       Diameters  of  American wire sizes can be found using the `wiregauge()'
       function or its alias `awg()':

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

       Wire and screw gauges with multiple zeroes are signified using negative
       numbers, where two zeroes ("00"; "2/0") is `-1',	 three	zeros  ("000";
       "3/0")  is  `-2',  and  so on.  Alternatively, you can use the synonyms
       `g00', `g000', or `g2_0', `g3_0', and so on that	 are  defined  in  the
       standard units data file.

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

       In North America, wire sizes larger than 0000 ("4/0") are usually given
       in terms of area, either in kcmil or the older initialism MCM (thousand
       circular	 mils).	  Outside of North America, all wire sizes are usually
       given in terms of area in  mm^2.	  Wire	area  can  be  obtained	 using
       `wiregaugeA()' or its alias `awgA()':

       You have: awgA(g6_0)
       You want: kcmil
	       * 336.45718
	       / 0.0029721464
       You have: awgA(12)
       You want: mm^2
	       * 3.3087729
	       / 0.30222685

       The  closest standard metric sizes are 2.5 mm^2 and 4 mm^2; in general,
       there isn't an exact  correlation  between  American  and  metric  wire
       sizes.

       Though  based  on  the  long-established	 iron pipe size (IPS) given in
       inches, nominal pipe size (NPS) is a dimensionless quantity that corre-
       sponds to the inch size.	 Pipe size can be equivalently specified using
       metric diametre nominal (DN), which roughly corresponds to the diameter
       in mm.  For a given pipe size, outside diameter is constant  while  in-
       side diameter varies with schedule.  For example, for NPS 21/2 pipe,

       You have: npsOD(2+1|2)
       You want: in
	       * 2.875
	       / 0.34782609
       You have: nps40(2+1|2)
       You want: in
	       * 2.469
	       / 0.40502228
       You have: nps80(2+1|2)
       You want: in
	       * 2.323
	       / 0.43047783

       Pipe  size can be given equivalently in terms of the metric DN by using
       the `DN()' function, which converts nominal metric size to nominal inch
       size:

       You have: npsOD(DN(65))
       You want: mm
	       * 73.025
	       / 0.01369394
       You have: _
       You want: in
	       * 2.875
	       / 0.34782609

       Unlike with wire sizes, actual NPS and metric DN	 pipe  dimensions  are
       the same.

       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 4mEnter24m at the `You want:' prompt to get the definition
       of  a  nonlinear unit; if the definition is not valid for all real num-
       bers, the range of validity is also given.  If the definition  requires
       specific units this information is also displayed:

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

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

   1mMultivariate Functions0m
       The  4munits24m	program supports some multivariate functions for performing
       calculations with units.	 The `hypot' function computes the length of a
       hypotenuse given two sides.  It works with any pair of values that have
       compatible dimensions.

       You have: hypot(3 m, 4 m)
       You want:
	       Definition: 5 m

       You can compute wind chill, based on temperature	 and  wind  speed,  or
       heat index, based on temperature and humidity, with humidity given as a
       fraction, e.g., 0.5 for a 50% relative humidity.

       You have: windchill(tempF(28), 14 mph)
       You want: tempF
	       16.86826
       You have: heatindex(tempC(40),0.5)
       You want: tempC
	       54.767952

       Both  wind chill and heat index return a value that is nominally a tem-
       perature, so you will want to convert it to Fahrenheit  or  Celsius  as
       shown in order to get a meaningful numerical value.

1mUNIT LISTS: CONVERSION TO SUMS OF UNITS0m
       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 4mfrom24m sums of units was described in 4mSums24m 4mand24m 4mDifferences24m 4mof24m 4mUnits24m,
       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 4mto24m, the re-
       sult will not be the conversion to the units in the sum, but rather the
       conversion to the particular sum that you have entered:

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

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

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

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

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

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

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

       The order in which you list the units is important:

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

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

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

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

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

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

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

       You have: 12.28126 ft
       You want: in
	       * 147.37512
	       / 0.0067854058
       You have: 12.28126 ft
       You want: in;
	       147 in (rounded down to nearest in)

       Each  unit  that appears in the list must be conformable with the first
       unit on the list, and of course the listed  units  must	also  be  con-
       formable 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, 4munits24m reports the disagreement between units appear-
       ing  on	the  list.  In the second case, 4munits24m reports disagreement be-
       tween the unit you entered and the desired conversion.  This  conforma-
       bility error is based on the first unit on the unit list.

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

       You have: 23.437754 deg
       You want: deg;arcmin;arcsec
	   23 deg + 26 arcmin + 15.9144 arcsec
       You have: 7.2319 hr
       You want: hr;min;sec
	   7 hr + 13 min + 54.84 sec

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

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

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

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

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

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

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

   1mCooking Measure0m
       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 4munits24m 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|4mx0m
       and  its multiplier is an integer, the fraction is given as the product
       of the multiplier and the numerator; for example,

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

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

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

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

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

       A user-specified fractional unit with a numerator other than 1 is never
       overridden,  however--if a unit list specifies `3|4 cup;1|2 cup', a re-
       sult equivalent to 1 1/2 cups will always be shown  as  `2  *  3|4 cup'
       whether or not the `--show-factor' option is given.

   1mUnit List Aliases0m
       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 4munits24m program provides shorthand names
       for some common combinations:

       hms	   time: hours, minutes, seconds
       dms	   angle: degrees, minutes, seconds
       time	   time: years, days, hours, minutes and seconds
       usvol	   US cooking volume: cups and smaller
       uswt	   US weight: pounds and ounces
       ftin	   length: feet, inches and 1/8 inches
       ftin2	   length: feet, inches and 1/2 inches
       ftin4	   length: feet, inches and 1/4 inches
       ftin8	   length: feet, inches and 1/8 inches
       ftin16	   length: feet, inches and 1/16 inches
       ftin32	   length: feet, inches and 1/32 inches
       ftin64	   length: feet, inches and 1/64 inches
       inchfine	   length: inches subdivided to 1/64 inch

       Using these shorthands, or 4munit24m 4mlist24m 4maliases24m, 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

       Suppose	you  want  to  drill a clearance hole for a #10 screw and have
       about 1/64 inch clearance; you could try

       You have: screwgauge(10) + 1|64 in
       You want: ftin64
	       13.16 * 1|64 in
       You have: _
       You want: ftin32
	       6.58 * 1|32 in

       If a slightly tight fit is acceptable, a 13/64-inch drill would do  the
       job; if not, a 7/32-inch drill would work with a slightly looser fit.

       You  can	 define	 your  own  unit  list aliases; see 4mDefining24m 4mUnit24m 4mList0m
       4mAliases24m.

       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, 4munits24m 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 4mare24m included in this output
       list:

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

1mALTERNATIVE UNIT SYSTEMS0m
   1mCGS Units0m
       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
       4munits24m supports four different systems of CGS units: electrostatic units
       (ESU), electromagnetic units (EMU), the Gaussian system and the	Heavi-
       side-Lorentz  system.  The differences between these systems arise from
       different choices made for proportionality constants in electromagnetic
       equations.  Coulomb's law gives electrostatic force between two charges
       separated by a distance delim $$ 4mr24m:

	    4mF24m = 4mk24m_C 4mq24m_1 4mq24m_2 / 4mr24m^2.

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

	    4mF24m/4ml24m = 2 4mk24m_A 4mI24m_1 4mI24m_2 / 4mr24m.

       The  two constants, 4mk24m_C and 4mk24m_A, are related by the square of the speed
       of light: 4mk24m_A = 4mk24m_C / 4mc24m^2.

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

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

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

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

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

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

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

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

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

       The CGS systems define units that measure the same thing but  may  have
       conflicting dimensions.	Furthermore, the dimensions of the electromag-
       netic  CGS  units  are  never  compatible  with SI.  But if you measure
       charge in two different systems you have	 measured  the	same  physical
       thing,  so there is a 4mcorrespondence24m between the units in the different
       systems, and 4munits24m supports conversions  between  corresponding  units.
       When  running  with  SI, 4munits24m defines all of the CGS units in terms of
       SI.  When you select a CGS system, 4munits24m 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, 4munits24m converts between the current units statA
       and abA even though the abA, from the EMU system, has incompatible  di-
       mensions.   This	 works because in Gaussian mode, the abA is defined in
       terms of the statA, so it does not have the correct definition for EMU;
       consequently, you cannot convert the abA to its EMU definition.

       One challenge of conversion is that because the CGS  system  has	 fewer
       base  units,  quantities	 that have different dimensions in SI may have
       the same dimension in a CGS system.  And yet, they  may	not  have  the
       same  conversion	 factor.   For example, the unit for the E field and B
       fields are the same in the Gaussian system, but the conversion  factors
       to  SI are quite different.  This means that correct conversion is only
       possible if you keep track of what quantity  is	being  measured.   You
       cannot  convert	statV/cm  to SI without indicating which type of field
       the unit measures.  To aid in dimensional analysis, 4munits24m defines vari-
       ous 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  di-
       mensional  analysis in CGS.  You can convert them to or from CGS in or-
       der 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

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

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

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

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

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

   1mPrompt Prefix0m
       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.

1mLOGGING CALCULATIONS0m
       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 4mComplicated24m 4mUnit24m 4mExpressions24m,
       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)
					  ^
       Invalid 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,	 4munits0m
       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	4munits24m  is	in-
       voked, the new results are appended to the log file.  The time is writ-
       ten  to	the log file each time the file is opened.  The `--log' option
       is ignored when 4munits24m is used non-interactively.

1mINVOKING 4mUNITS0m
       You invoke 4munits24m like this:

       units [4moptions24m] [4mfrom-unit24m [4mto-unit24m]]

       If the 4mfrom-unit24m and 4mto-unit24m are omitted, the program will use interac-
       tive prompts to determine which conversions to perform.	 See  4mInterac-0m
       4mtive24m  4mUse24m.   If  both 4mfrom-unit24m and 4mto-unit24m are given, 4munits24m will print
       the result of that single conversion and then exit.  If only  4mfrom-unit0m
       appears	on the command line, 4munits24m will display the definition of that
       unit and exit.  Units specified on the command  line  may  need	to  be
       quoted to protect them from shell interpretation and to group them into
       two  arguments.	 Note also that the `--quiet' option is enabled by de-
       fault if you specify 4mfrom-unit24m on the command line.	 See  4mCommand24m  4mLine0m
       4mUse24m.

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

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

       Many  options  can be set interactively; this can be especially helpful
       for Windows users who start 4munits24m from a shortcut.	See 4mSetting24m 4mOptions0m
       4mInteractively24m for more information.

       The following options are available:

       1m-c22m, 1m--check0m
	      Check that all units and prefixes defined in  units  data	 files
	      reduce  to  primitive  units.   Display a list of all units that
	      cannot be reduced and a list of units with circular definitions.
	      Also display some other diagnostics about suspicious definitions
	      in the units data file.  Only definitions active in the  current
	      locale  are  checked.  You should always run 4munits24m with this op-
	      tion after modifying a units data file.

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

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

       1m--list-units0m
	      This option displays a list of all units and exits.  With output
	      redirected to a file, it can produce a list of all units in  the
	      database,	 which may comprise multiple 4munits24m data files.  It can
	      also be useful if you aren't sure of the name of a unit or  want
	      to  find	all units of a particular type and you want a more ad-
	      vanced search than is available with the interactive 4msearch24m com-
	      mand.  See 4mFinding24m 4mUnits24m for some examples of  how  this  option
	      can be used.

       1m-d 4m22mndigits24m, 1m--digits 4m22mndigits0m
	      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, 4munits24m displays one digit to the left of the dec-
	      imal  point and eleven digits to the right of the decimal point.
	      On most systems, the maximum  number  of	internally  meaningful
	      digits is 15; if you specify a greater number than your system's
	      maximum,	4munits24m  will  print a warning and set the number to the
	      largest meaningful value.	 To directly set  the  maximum	value,
	      give  an argument of max (e.g., `-d max').  Be aware, of course,
	      that "significant" here refers only to the 4mdisplay24m  of  numbers;
	      if results depend on physical constants not known to this preci-
	      sion,  the physically meaningful precision may be less than that
	      shown.  The `--digits' option is incompatible with  the  `--out-
	      put-format'  option;  if	you give them both, the format is con-
	      trolled by the last option given.

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

       1m-o 4m22mformat24m, 1m--output-format 4m22mformat0m
	      This  option  affords  complete  control over the numeric output
	      format using the specified 4mformat24m. The format is a single float-
	      ing point numeric format for the printf function in the  C  pro-
	      gramming	language.   All compilers support the format types `g'
	      and `G' to specify significant digits, `e' and  `E'  for	scien-
	      tific  notation,	and  `f' for fixed-point decimal.  The ISO C99
	      standard introduced the `F' type for fixed-point decimal and the
	      `a' and `A' types for hexadecimal floating  point;  these	 types
	      are  allowed with compilers that support them.  The default for-
	      mat  is  `%.8g';	for  greater  precision,  you  could   specify
	      `-o %.15g'.   Unlike with the `--digits' option, you can specify
	      any desired precision, though not all digits may be  meaningful.
	      See  4mNumeric24m	 4mOutput24m 4mFormat24m and the documentation for printf for
	      more detailed descriptions of  the  format  specification.   The
	      `--output-format'	 option	 affords  the  greatest control of the
	      output appearance, but requires at least	rudimentary  knowledge
	      of  the  printf format syntax.  If you don't want to bother with
	      the printf syntax, you can specify greater precision more simply
	      with the `--digits' option or  select  exponential  format  with
	      `--exponential'.	 The  `--output-format' option is incompatible
	      with the `--exponential' and `--digits' options; if you give ei-
	      ther in combination with `--output-format', the format  is  con-
	      trolled by the last option given.

       1m-f 4m22mfilename24m, 1m--file 4m22mfilename0m
	      Instruct 4munits24m to load the units file 4mfilename24m.	 You can specify
	      up to 25 units files on the command line.	 When you use this op-
	      tion,  4munits24m	 will  load  4monly24m 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 4mfilename24m is the empty
	      string (`-f ""'), the default main units file (or that specified
	      by UNITSFILE) will be loaded in addition to any others specified
	      with `-f'.

       1m-L 4m22mlogfile24m, 1m--log 4m22mlogfile0m
	      Save the results of calculations in the file 4mlogfile24m;  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
	      4mlogfile24m exits, the new results are appended to the  file.   This
	      option  is  ignored  when	 4munits24m is used non-interactively.	See
	      4mLogging24m 4mCalculations24m for a more detailed  description  and  some
	      examples.

       1m-H 4m22mfilename24m, 1m--history 4m22mfilename0m
	      Instruct	4munits24m to save history to 4mfilename24m, so that a record of
	      your commands is available for retrieval across different	 4munits0m
	      invocations.   To prevent the history from being saved set 4mfile-0m
	      4mname24m to the empty string (`-H ""').	This option has	 no  effect
	      if readline is not available.

       1m-h22m, 1m--help0m
	      Print out a summary of the options for 4munits24m.

       1m-m22m, 1m--minus0m
	      Causes `-' to be interpreted as a subtraction operator.  This is
	      the default behavior.

       1m-p22m, 1m--product0m
	      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.

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

       1m--newstar0m
	      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'.

       1m-r22m, 1m--round0m
	      When converting to a combination of units given by a unit	 list,
	      round  the value of the last unit in the list to the nearest in-
	      teger.

       1m-S22m, 1m--show-factor0m
	      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|4mx24m and its multiplier	 is
	      an integer other than 1, the fraction is given as the product of
	      the  multiplier and the numerator (e.g., `3|8 in' rather than `3
	      * 1|8 in').  In some cases, this is not what is wanted; for  ex-
	      ample, the results for a cooking recipe might show `3 * 1|2 cup'
	      as `3|2 cup'.  With the `--show-factor' option, a result equiva-
	      lent  to	1.5  cups  will	 display  as `3 * 1|2 cup' rather than
	      `3|2 cup'.  A user-specified fractional unit  with  a  numerator
	      other than 1 is never overridden, however--if a unit list speci-
	      fies  `3|4  cup;1|2 cup', a result equivalent to 1 1/2 cups will
	      always be shown as `2 * 3|4 cup' whether or not the `--show-fac-
	      tor' option is given.

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

       1m-v22m, 1m--verbose0m
	      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.

       1m-V22m, 1m--version0m
	      Print  the program version number, tell whether the 4mreadline24m li-
	      brary has been included, tell whether UTF-8 support has been in-
	      cluded; give the locale, the location of the default main	 units
	      data file, and the location of the personal units data file; in-
	      dicate 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.

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

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

       1m-U22m, 1m--unitsfile0m
	      Print the location of the default main units data file and exit;
	      if the file cannot be found, print "Units data file not found".

       1m-u 4m22munits-system24m, 1m--units 4m22munits-system0m
	      Specify  a  CGS  units system or natural units system.  The sup-
	      ported units systems are: gauss[ian], esu,  emu,	hlu,  natural,
	      natural-gauss, hartree, planck, planck-red, and si. See 4mAlterna-0m
	      4mtive24m	 4mUnit24m 4mSystems24m for further information about these unit sys-
	      tems.

       1m-l 4m22mlocale24m, 1m--locale 4m22mlocale0m
	      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 4mLocale24m for  a	de-
	      scription of locale format.

       1m-n22m, 1m--nolists0m
	      Disable conversion to unit lists.

       1m-s22m, 1m--strict0m
	      Suppress conversion of units to their reciprocal units.  For ex-
	      ample,  4munits24m  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.

       1m-122m, 1m--one-line0m
	      Give only one line of output (the forward	 conversion);  do  not
	      print  the  reverse  conversion.	 If a reciprocal conversion is
	      performed, then 4munits24m will still print the  "reciprocal  conver-
	      sion" line.

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

       1m--compact0m
	      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.

       1m-q22m, 1m--quiet22m, 1m--silent0m
	      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 4munits24m displays the results.  This option is turned on by de-
	      fault if you invoke 4munits24m with a unit expression on the  command
	      line.

1mSETTING OPTIONS INTERACTIVELY0m
       Many  command-line options can also be set interactively, obviating the
       need to quit and restart 4munits24m to change the values.  This can be espe-
       cially helpful for Windows users who start 4munits24m from a shortcut.

       Typing 4mset24m will display a list of all options that can be set  interac-
       tively,	as  well  as  the  current and possible values; options set to
       other than default values have an asterisk (`*') prepended.  For	 exam-
       ple,

       You have: set
	 q[uiet] = no	      (y|n) do/don't suppress prompting
	 o[neline] = no	      (y|n) do/don't suppress the second line of output
	 st[rict] = no	      (y|n) do/don't suppress reciprocal unit conversion
				    (e.g. Hz<->s)
	 t[erse] = no	      (y|n) do/don't give very terse output
	 c[ompact] = no	      (y|n) do/don't suppress printing tab, SETFLAG, and '/'
				    characters in results
	 v[erbose] = 1	      (0|1|2) amount of information shown
	*d[igits] = 9	      number of significant digits in output
	 e[xponential] = no   (y|n) do/don't use exponential ("scientific") notation
	*f[ormat] = %.9g      printf(3) format specification
	 u[nitlists] = yes    (y|n) do/don't allow conversion to unit lists
	 r[ound] = no	      (y|n) do/don't round last element of unit list output
				    to an integer
	 sh[owfactor] = no    (y|n) do/don't show non-unity factor before 1|x
				    in multi-unit output

       Characters  within the square brackets are optional, so settings can be
       changed by entering only one or two characters.

       The syntax for setting options is 4mset24m 4moption24m 4m=24m 4mvalue24m; the spaces around
       the `=' sign are optional.

       Some settings are Boolean, enabled by entering 4myes24m (or just 4my24m) and dis-
       abled by entering 4mno24m (or just 4mn24m).  For example,

       You have: set quiet = y
	 quiet = yes

       Other settings take an integer value; for example,

       You have: set d=11
	 digits = 11
	 format = %.11g

       The format setting takes a string, the  format  specification  for  the
       printf function in the C programming language; for example,

       You have: set format = %.9g
	 format = %.9g

       Typing 4mset24m 4moption24m will display the current value of 4moption24m, for example

       You have: set u
	 unitlists = yes
       You have: set d
	 digits = 8
	 format = %.8g

       For  the	 digits	 and  exponential options, the value of format is also
       shown.

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

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

       #!/bin/sh
       progname=`basename $0 .sh`
       umsg="Usage: $progname [<number>] unit"
       if [ $# -lt 1 ]
       then
	   echo "$progname: missing quantity to convert"
	   echo "$umsg"
	   exit 1
       fi
       for unit in `units --conformable "$*" | cut -f 1 -d ' '`
       do
	   echo "$*"   # have -- quantity to convert
	   echo $unit  # want -- conformable unit
       done | units --terse --verbose

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

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

       $ conformable 3.75g | grep 0.120

       gives

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

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

       We might run

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

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

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

1mOUTPUT STYLES0m
       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 2023-07-08
       3612 units, 109 prefixes, 122 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 2023-07-08
       3612 units, 109 prefixes, 122 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	 4munits0m
       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 4munits24m 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
       $ units --terse '1 mile'
       1609.344 m
       $ units --terse mile
       5280 ft = 1609.344 m

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

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

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

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

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

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

   1mDefining New Units and Prefixes0m
       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 cannot begin or end with an underscore (`_')	or  a  decimal
       point  (`.'),  and  cannot  contain any of the operator characters `+',
       `-', `*', `/', `|', `^', `;', `~', a comma (`,'), the comment character
       `#', or parentheses.  To facilitate copying and pasting from documents,
       several typographical characters are converted to operators: the figure
       dash (U+2012), minus (`-'; U+2212), and en dash (`-'; U+2013) are  con-
       verted  to  the operator `-'; the multiplication sign (`x'; U+00D7), N-
       ary times operator (U+2A09), dot operator (`.'; U+22C5), and middle dot
       (`.'; U+00B7) are converted to the  operator  `*';  the	division  sign
       (`/';  U+00F7) is converted to the operator `/'; and the fraction slash
       (U+2044) is converted to the operator `|'; accordingly, none  of	 these
       characters can appear in unit names.

       Names  cannot  begin  with a digit, and if a name ends in a digit other
       than zero or one, then the name must end with an underscore followed by
       a string consisting only of digits and decimal points.	 For  example,
       `foo_2',	 `foo_3.14',  and  `foo_3...\&9' are valid names but `foo2' or
       `foo_a2' are invalid.  The underscore is necessary because without  it,
       4munits24m  cannot  determine  whether  `foo2'  is a unit name or represents
       `foo^2'.	 Zero and one are exceptions because  4munits24m  never	 interprets
       them as exponents.

       You could define nitrous oxide as

       N2O     nitrogen 2  + oxygen

       but would need to define nitrogen dioxide as

       NO_2    nitrogen + oxygen 2

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

       When adding new units, be sure to use the `-c' option to check that the
       new  units  reduce  properly and that there are no circular definitions
       that lead to endless loops.  Because some errors may hide other errors,
       you should run 4munits24m with the `-c' option again  after  correcting	any
       errors, and keep doing so until no errors are displayed.

       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 4munits24m.  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, 4munits24m displays a warning message about the redefi-
       nition.	You can suppress these warnings by redefining a unit  using  a
       `+'  at the beginning of the unit name.	Do not include any white space
       between the `+' and the redefined unit name.

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

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

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

   1mDefining Nonlinear Units0m
       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 4munits24m uses to convert values in inches into
       primitive units of meters.  For nonlinear units, you give a  functional
       definition that provides the same information.

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

       Here is an example nonlinear unit definition:

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

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

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

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

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

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

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

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

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

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

       square(x)       x^2

       can  have  any  arbitrary  units, and can also take dimensionless argu-
       ments.  In such a case, you should 4mnot24m 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,
       4munits24m 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  two
       numerical endpoints given in brackets.  No spaces can appear before the
       `='.   In accord with mathematical convention, square brackets indicate
       a closed interval (one that includes its	 endpoints),  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 decibel (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 intervals given for the domain and range  must  be
       numbers and cannot include units or any calculations.

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

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

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

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

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

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

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

       fahrenheit()  tempF

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

       fahrenheit()  meter

       will result in an error message when 4munits24m 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)

   1mDefining Piecewise Linear Units0m
       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, 4munits24m 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-monoto-
       nic in the vicinity of 800 grit:

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

       Running `units --check' would give the error message

       Table 'ansicoated' lacks unique inverse around entry 800

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

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

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

   1mDefining Multivariate Functions0m
       Some common dimensional calculations such as wind chill	or  body  mass
       index  have  more  than	one parameter.	To support these calculations,
       units allows multivariate functions as unit  definitions.   Unlike  the
       nonlinear  units described above, multivariate functions provide only a
       forward evaluation and are not invertible:  it is impossible to convert
       a wind chill output back to the temperature and wind speed that	gener-
       ated it.

       A multivariate function definition is similar to that for other nonlin-
       ear  units.   For  example,  you could define `bmi' like this, starting
       with the unit's name followed immediately  without  white  space	 by  a
       comma-separated parameter list:

       bmi(ht,wt) units=[m,kg] domain=(0,)(0,) (wt/kg)/(ht/m)^2

       This  defines a new unit, `bmi', that has two parameters, `height', and
       `weight'.  You are allowed to use white space in	 the  parameter	 list.
       The optional `units=' specification (with no space before the `=') pro-
       vides  a	 comma-separated list in square brackets of units that provide
       the dimensions of the parameters.  (Since  multivariate	units  require
       the  use	 of  commas,  you  cannot use them to specify the units in the
       `units=' specification.)	 If you list fewer units than  the  number  of
       parameters, the remaining parameters will allow any unit.  For univari-
       ate  nonlinear  units, a semicolon introduces the units of the inverse.
       The semicolon is not permitted in the `units='  list  for  multivariate
       functions.

       You  specify the domain, if desired, using `domain=', followed (without
       white space) by the intervals defining the domain  of  each  parameter,
       either  juxtaposed  or separated by commas.  The above example requires
       that both arguments be strictly positive.  As usual, use square	brack-
       ets  to	indicate closed intervals.  The rules for domain intervals are
       the same as those described above for nonlinear units.  If you need  to
       indicate an unconstrained input give the interval `(,)'.	 The intervals
       in  the	domain specification must use numerical values; you cannot use
       units or calculations in the domain.

       The final part of the definition is the	expression  that  defines  the
       unit.   Since inverses are not well-defined for multivariate units, you
       cannot provide an inverse.  Since you cannot provide  an	 inverse,  you
       also  cannot  provide a range, so the `range=' specification is invalid
       for multivariate functions.

       If you need to specify that a particular unit is of arbitrary dimension
       when units appearing after it in the parameter list  are	 of  specified
       dimension,  you	can do this using the special dimension specification,
       `*'.  Here is a toy example:

       func(a,b) units=[*,1] domain=(,),[-1,1] a asin(b)

       In this example the first argument is permitted to be of any dimension,
       but the second argument must be dimensionless.  The first argument  has
       no domain bounds, but the second one must lie in the domain of the arc-
       sine function.

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

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

       Unit list aliases are only for unit lists, so the definition  must  in-
       clude  a	 `;'.	Unit  list aliases can never be combined with units or
       other unit list aliases, so the definition of `time' shown above	 could
       4mnot24m 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.

1mNUMERIC OUTPUT FORMAT0m
       By default, units shows results to eight significant digits in  general
       number  format.	 You can change this with the `--exponential', `--dig-
       its', and `--output-format' options.  The  first	 sets  an  exponential
       format  (i.e., scientific notation) like that used in the original Unix
       4munits24m program, the second allows you to specify a different	 number	 of
       significant  digits,  and the last allows you to control the output ap-
       pearance 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  `--exponen-
       tial'  options.	The `--output-format' option affords the greatest con-
       trol of the output appearance, but requires at least rudimentary knowl-
       edge of the printf format syntax.  See 4mInvoking24m 4mUnits24m for  descriptions
       of these options.

   1mFormat Specification0m
       The  format  specification recognized with the `--output-format' option
       is a subset of that for printf.	The format specification has the  form
       %[4mflags24m][4mwidth24m][.4mprecision24m]4mtype24m;  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  4munits24m  is `%.8g'; for greater precision, you
       could specify `-o %.15g'.  The `g' and `G' format types use exponential
       format whenever the exponent would  be  less  than  -4,	so  the	 value
       0.000013	 displays as `1.3e-005'.  These types also use exponential no-
       tation when the exponent is greater than or equal to the precision,  so
       with  the default format, the value 5 x 10^7 displays as `50000000' and
       the value 5 x 10^8 displays as `5e+008'.	  If  you  prefer  fixed-point
       display,	 you might specify `-o %.8f'; however, small numbers will dis-
       play very few significant digits, and values less than 5 x  10^-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.

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

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

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

   1mPrecision0m
       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 maximum
       internal precision with 4munits24m is 15 decimal digits (or  13	hexadecimal
       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  artifacts.
       For  example,  a	 pound	is  exactly  7000  grains, but with the format
       `%.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  4mdisplay24m  of numbers; if a result relies on physical constants that
       are not known to the specified  precision,  the	number	of  physically
       meaningful digits may be less than the number of digits shown.

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

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

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

   1mLocale0m
       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 4munits24m program attempts to determine	the  locale
       from  the POSIX setlocale function; if this cannot be done, 4munits24m exam-
       ines the environment variables LC_CTYPE and LANG.  On POSIX systems,  a
       locale is of the form 4mlanguage24m_4mcountry24m, where 4mlanguage24m is the two-char-
       acter  code  from  ISO 639-1 and 4mcountry24m is the two-character code from
       ISO 3166-1; 4mlanguage24m is lower case and 4mcountry24m is upper case. For exam-
       ple, the POSIX locale for the United Kingdom is en_GB.

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

	    4mWindows-locale24m	  4mPOSIX-locale0m

       where 4mPOSIX-locale24m is as described above, and 4mWindows-locale24m  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 4munits24m to run in a desired locale by using  the  `-l'	op-
       tion.

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

       !locale en_GB
       gallon	    4.54609 liter
       !endlocale

   1mAdditional Localization0m
       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, 4munits24m allows specifying definitions that
       depend on environment variable settings.	 The environment variables can
       be controlled based on the current locale, or the user can set them  to
       force a particular group of definitions.

       A conditional block of definitions in a units data file begins with ei-
       ther  `!var' or `!varnot' following by an environment variable name and
       then a space separated list of values.  The leading `!' must appear  in
       the  first  column  of  a units data file, and the conditional block is
       terminated by `!endvar'.	 Definitions in blocks beginning  with	`!var'
       are  executed  only if the environment variable is exactly equal to one
       of the listed values.  Definitions in blocks beginning  with  `!varnot'
       are executed only if the environment variable does 4mnot24m 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 4muncia24m meaning "one twelfth," referring to
       its relationship with the foot.	By the 20th century, the inch was  of-
       ficially	 defined  in  English-speaking countries relative to the yard,
       but until 1959, the yard differed slightly among those  countries.   In
       France  the  customary  inch, which was displaced in 1799 by the meter,
       had a different length based on a french foot.  These customary defini-
       tions could be accommodated as follows:

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

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

       In order to create default values that are overridden by user  settings
       the  data  file	can  use the `!set' command, which sets an environment
       variable 4monly24m 4mif24m 4mit24m 4mis24m 4mnot24m 4malready24m 4mset24m;  these settings  are	only  for
       the  current  4munits24m	 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 4munits24m, then 4munits24m 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 4mpreceding24m 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
       4munits24m  prints an error message and ignores the definitions that follow.
       Use `!set' to create defaults to prevent this situation	from  arising.
       The  `-c'  option  only	checks the definitions that are active for the
       current environment and locale, so when	adding	new  definitions  take
       care to check that all cases give rise to a well defined set of defini-
       tions.

1mENVIRONMENT VARIABLES0m
       The 4munits24m program uses the following environment variables:

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

       1mLC_CTYPE, LANG0m
	      Checked to determine the locale if 4munits24m cannot obtain  it  from
	      the  operating  system.  Sections of the default main units data
	      file are specific to certain locales.

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

       1mPAGER	22mSpecifies  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'4mn24m syntax for specifying a line
	      number.  The default pager is 4mmore24m; PAGER can be used to specify
	      alternatives such as 4mless24m, 4mpg24m, 4memacs24m, or 4mvi24m.

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

       1mUNITSFILE0m
	      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 ""').

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

       1mUNITS_SYSTEM0m
	      This  environment variable is used in the default main data file
	      to select CGS measurement systems.  Currently supported  systems
	      are    `esu',    `emu',	 `gauss[ian]',	  `hlu',    `natural',
	      `natural-gauss', `planck',  `planck-red',	 `hartree'  and	 `si'.
	      The default is `si'.

1mDATA FILES0m
       The  4munits24m	program	 uses  four default data files: the main data file,
       `definitions.units';   the   atomic    masses	of    the    elements,
       `elements.units'; currency exchange rates, `currency.units', and the US
       Consumer	 Price Index, `cpi.units'.  The last three files are loaded by
       means of `!include' directives in the main file (see  4mDatabase24m  4mCommand0m
       4mSyntax24m).  The program can also use an optional personal units data file
       `.units' (`unitdef.units' under Windows) located in the user's home di-
       rectory.	  The  personal units data file is described in more detail in
       4mUnits24m 4mData24m 4mFiles24m.

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

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

       If    4munits24m	   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 main units data file is not an absolute pathname,	 4munits0m
       will  look  for	the file in the directory that contains the 4munits24m pro-
       gram; if the file is not found there, 4munits24m will look  in  a  directory
       ../share/units relative to the directory with the 4munits24m program.

       You   can   determine   the   location	of   the   files   by  running
       `units --version'.  Running `units --info' will give you additional in-
       formation about the files, how 4munits24m will attempt to find them, and the
       status of the related environment variables.

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

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

       When Unicode support is available, 4munits24m 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, 4munits24m ignores the entire line.	 In
       addition to checking validity, 4munits24m determines the	 display  width	 of
       non-ASCII  characters  to  ensure  proper positioning of the pointer in
       some error messages and to align columns for the `search' and `?'  com-
       mands.

       Microsoft  Windows  supports  UTF-8  in console applications running in
       Windows Terminal; UTF-8 is not supported in applications running in the
       older Windows Console Host--see 4mUnicode24m 4mSupport24m 4mon24m 4mWindows24m.	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	 4mUnits0m
       4mData24m  4mFiles24m,  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, 4munits24m makes no assumptions about
       character encoding, except that characters in the range 00-7F hexadeci-
       mal  correspond to ASCII encoding.  Non-ASCII characters are simply se-
       quences of bytes, and have no special meanings; for definitions in sup-
       plementary units data files, you can use any encoding  consistent  with
       this  assumption.  For example, if you wish to use non-ASCII characters
       in definitions when running 4munits24m under Windows, you can use a  charac-
       ter  set	 such  as Windows "ANSI" (code page 1252 in the US and Western
       Europe); if this is done, the console code page must be set to the same
       encoding for the characters to display  properly.   You	can  even  use
       UTF-8,  though  some messages may be improperly aligned, and 4munits24m 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 4moutside24m `!utf8' ... `!endutf8' blocks--otherwise,
       they will be ignored.

       Except for code examples, typeset material  usually  uses  the  Unicode
       symbols	for mathematical operators.  To facilitate copying and pasting
       from such sources, several typographical characters  are	 converted  to
       the  ASCII  operators  used  in	4munits24m: the figure dash (U+2012), minus
       (`-'; U+2212), and en dash (`-'; U+2013) are converted to the  operator
       `-';  the  multiplication  sign	(`x';  U+00D7),	 N-ary	times operator
       (U+2A09), dot operator (`.'; U+22C5), and middle dot (`.'; U+00B7)  are
       converted  to the operator `*'; the division sign (`/'; U+00F7) is con-
       verted to the operator `/'; and the fraction  slash  (U+2044)  is  con-
       verted to the operator `|'.

   1mUnicode Support on Windows0m
       Microsoft  Windows  supports  UTF-8  in console applications running in
       Windows Terminal but not in applications running in the	older  Windows
       Console	Host.  In Windows Terminal, the code page must be set to 65001
       for UTF-8 to be enabled.	 With the UTF-8 code  page,  running  units -V
       might show

       GNU Units version 2.24
       Without readline, with UTF-8, locale English_United States (en_US)

       Two  values  are shown for the locale: the first is the one returned by
       the system; the second is the POSIX value to which the system value  is
       mapped.

       With a different code page, the result might be

       GNU Units version 2.24
       Without readline, with UTF-8 (disabled), locale English_United States (en_US)
       To enable UTF-8: set code page to 65001

       If  4munits24m  is  running  in Windows Console Host, regardless of the code
       page, the result might be

       GNU Units version 2.24
       Without readline, with UTF-8 (disabled), locale English_United States (en_US)
       To enable UTF-8: run in Windows Terminal and set code page to 65001

       The UTF-8 code page can be set by running chcp 65001.

       As of late 2024, the Windows build of 4munits24m does not  identify  charac-
       ters--typically East Asian--that occupy more than one column, and error
       messages involving those characters may not be properly aligned.

1mREADLINE SUPPORT0m
       If  the	4mreadline24m package has been compiled in, then when 4munits24m is used
       interactively, numerous command line editing  features  are  available.
       To check if your version of 4munits24m includes 4mreadline24m, invoke the program
       with the `--version' option.

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

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

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

       If there is a unique way to complete a unit name, you can hit  the  4mTAB0m
       key  and 4munits24m will provide the rest of the unit name.  If 4munits24m beeps,
       it means that there is no unique completion.  Pressing the  4mTAB24m  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 4munits24m 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 4munits24m to units --history .units_history so that  4munits24m  would
       save  separate  history	in  the current directory.  The length of each
       history file is limited to 5000 lines.  Note also that if you run  sev-
       eral  concurrent	 copies of 4munits24m each one will save its new history to
       the history file upon exit.

1mUPDATING CURRENCY EXCHANGE RATES AND CPI0m
   1mCurrency Exchange Rates0m
       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 4munits24m cannot provide real-time values.	To
       update the exchange rates, run 4munits_cur24m, which rewrites the file con-
       taining the currency rates, typically `/var/lib/units/currency.units'
       or `/usr/local/com/units/currency.units' on a Unix-like system or
       `C:\Program Files (x86)\GNU\units\definitions.units' on a Windows sys-
       tem.

       This program requires Python 3 (https://www.python.org).	  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:

	*  ExchangeRate-API.com (https://www.exchangerate-api.com).
	   The default currency server.	 Allows open  access  without  an  API
	   key,	 with unlimited API requests.  Rates update once a day, the US
	   dollar (`USD') is the default base currency,	 and  you  can	choose
	   your	 base  currency with the `-b' option described below.  You can
	   optionally sign up for an API key to access paid benefits  such  as
	   faster data update rates.

	*  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 up-
	   date daily.	This source offers a more limited list	of  currencies
	   than the others.

	*  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 encryp-
	   tion (https protocol) is not available.  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  currency	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.

   1mUS Consumer Price Index0m
       The 4munits24m program includes the US Consumer Price Index (CPI)  published
       by  the US Bureau of Labor Statistics: specifically, the Consumer Price
       Index for All Urban Consumers (CPI-U), not seasonally  adjusted--Series
       CUUR0000SA0.   The  4munits_cur24m command updates the CPI and saves the re-
       sult in `cpi.units' in the same location as `currency.units'.  The data
       are obtained via the BLS Public Data API	 (https://www.bls.gov/develop-
       ers/).	These  data  update once a month.  When 4munits_cur24m runs it will
       only attempt to update the CPI data if the current  CPI	data  file  is
       from  a previous month, or if the current date is after the 18th of the
       month.

   1mInvoking 4munits_cur0m
       You invoke 4munits_cur24m like this:

       units_cur [4moptions24m] [4mcurrency_file24m] [4mcpi_file24m]

       By default, the output is written to the default currency and CPI files
       described above; this is usually what you want, because this  is	 where
       4munits24m  looks  for  the  files.   If you wish, you can specify different
       filenames on the command line and 4munits_cur24m	 will  write  the  data	 to
       those files.  If you give `-' for a file it will write to standard out-
       put.

       The following options are available:

       1m-h22m, 1m--help0m
	      Print a summary of the options for 4munits_cur24m.

       1m-V22m, 1m--version0m
	      Print the 4munits_cur24m version number.

       1m-v22m, 1m--verbose0m
	      Give slightly more verbose output when attempting to update cur-
	      rency exchange rates.

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

       1m-b 4m22mbase24m, 1m--base 4m22mbase0m
	      Set  the	base  currency (when allowed by the site providing the
	      data).  4mbase24m should be  a  3-letter	ISO  currency  code,  e.g.,
	      `USD'.   The  specified  currency will be the primitive currency
	      unit used by 4munits24m.	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  4mEnter24m	 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.)

       1m-k 4m22mkey24m, 1m--key 4m22mkey0m
	      Set the API key to 4mkey24m for currency sources that require it.

       1m--blskey 4m22mBLSkey0m
	      Set the US Bureau of Labor Statistics (BLS) key for fetching CPI
	      data.   Without  a  BLS  key you should be able to fetch the CPI
	      data exactly one time per day.  If you want to  use  a  key  you
	      must request a personal key from BLS.

1mDATABASE COMMAND SYNTAX0m
       4munit24m 4mdefinition0m
	      Define a regular unit.

       4mprefix24m1m- 4m22mdefinition0m
	      Define a prefix.

       4mfuncname24m1m(4m22mvar24m1m) noerror units=[4m22min-units24m1m,4m22mout-units24m1m] domain=[4m22mx124m1m,4m22mx224m1m]0m
       1mrange=[4m22my124m1m,4m22my224m1m] 4m22mdefinition(var)24m 1m; 4m22minverse(funcname)0m
	      Define  a	 nonlinear  unit  or unit function.  The four optional
	      keywords 4mnoerror24m, `units=', `range=' and `domain=' can appear in
	      any order.  The definition of the inverse is optional.

       4mtabname24m1m[4m22mout-units24m1m] noerror 4m22mpair-list0m
	      Define a piecewise linear unit.  The pair list gives the	points
	      on  the table listed in ascending order.	The 4mnoerror24m keyword is
	      optional.

       1m!endlocale0m
	      End a block of definitions beginning with `!locale'

       1m!endutf80m
	      End a block of definitions begun with `!utf8'

       1m!endvar0m
	      End a block of definitions begun with `!var' or `!varnot'

       1m!include 4m22mfile0m
	      Include the specified file.

       1m!locale 4m22mvalue0m
	      Load the following definitions only of  the  locale  is  set  to
	      4mvalue24m.

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

       1m!prompt 4m22mtext0m
	      Prefix  the  `You have:' prompt with the specified text.	If you
	      omit 4mtext24m, then any existing prefix is canceled.

       1m!set 4m22mvariable24m 4mvalue0m
	      Sets the environment variable, 4mvariable24m, to the specified  value
	      4monly24m 4mif24m it is not already set.

       1m!unitlist 4m22malias24m 4mdefinition0m
	      Define a unit list alias.

       1m!utf8	22mLoad	 the  following	 definitions  only if 4munits24m is running with
	      UTF-8 enabled.

       1m!var 4m22menvar24m 4mvalue-list0m
	      Load the block of definitions that follows only if the  environ-
	      ment  variable  4menvar24m  is set to one of the values listed in the
	      space-separated value list.  If 4menvar24m is not set,  4munits24m  prints
	      an error message and ignores the block of definitions.

       1m!varnot 4m22menvar24m 4mvalue-list0m
	      Load  the block of definitions that follows only if the environ-
	      ment variable 4menvar24m is set to value that is 4mnot24m	 listed	 in  the
	      space-separated  value  list.  If 4menvar24m is not set, 4munits24m prints
	      an error message and ignores the block of definitions.

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

1mAUTHOR0m
       4munits24m was written by Adrian Mariano

				14 January 2026			      4mUNITS24m(1)