UNITS(1)							      UNITS(1)



NAME
       units — unit conversion and calculation program

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

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

       Beyond  simple  unit conversions, 'units' can be used as a general-pur‐
       pose scientific calculator that keeps track of units  in  its  calcula‐
       tions.	You  can  form	arbitrary  complex mathematical expressions of
       dimensions including sums, products, quotients, powers, and even  roots
       of  dimensions.	 Thus  you can ensure accuracy and dimensional consis‐
       tency when working with long expressions that  involve  many  different
       units that may combine in complex ways.

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

       Basic operation is simple: you enter the units that you want to convert
       from  and  the units that you want to convert to.  You can use the pro‐
       gram interactively with prompts, or you can use	it  from  the  command
       line.   This  document describes the basic as well as the advanced fea‐
       tures of 'units' in detail, with many examples.

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

	  2131 units, 53 prefixes, 24 nonlinear units

	  You have:

       At  the	'You  have:'  prompt, type the quantity and units that you are
       converting from.  For example, if you want to  convert  ten  meters  to
       feet,  type  '10  meters'.   Next, 'units' will print 'You want:'.  You
       should type the units you want to convert to.  To convert to feet,  you
       would type 'feet'.  Note that if the 'readline' library was compiled in
       then the tab key can be used to complete unit names. See Readline  Sup‐
       port for more information about 'readline'.

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

	      * 32.808399
	      / 0.03048

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       If you type

	  units "2 liters" quarts

       then 'units' will print

	      * 2.1133764
	      / 0.47317647

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

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

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

UNIT DEFINITIONS
       The  conversion	information  is  read  from  a units data file that is
       called 'units.dat' and is usually located in  the  '/usr/share'	direc‐
       tory.   If  you	invoke 'units' with the '-V' option, it will print the
       location of this file.  The default file includes definitions  for  all
       familiar  units,  abbreviations	and metric prefixes.  It also includes
       many obscure or archaic units.

       Many constants of nature are defined, including these:

	  pi	      ratio of circumference to diameter
	  c	      speed of light
	  e	      charge on an electron
	  force       acceleration of gravity
	  mole	      Avogadro's number
	  water       pressure per unit height of water
	  Hg	      pressure per unit height of mercury
	  au	      astronomical unit
	  k	      Boltzman's constant
	  mu0	      permeability of vacuum
	  epsilon0    permittivity of vacuum
	  G	      Gravitational constant
	  mach	      speed of sound

       The standard data file includes atomic masses for all of  the  elements
       and numerous other constants.  Also included are the densities of vari‐
       ous ingredients used in baking so that '2  cups	flour_sifted'  can  be
       converted  to  'grams'.	 This  is not an exhaustive list.  Consult the
       units data file to see the complete list, or  to  see  the  definitions
       that are used.

       The  unit  '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'.   British capacity units that differ from their US counter‐
       parts, such as the British Imperial gallon,  are  prefixed  with  'br'.
       Currency   is   prefixed   with	 its   country	name:  'belgiumfranc',
       'britainpound'.

       When searching for a unit, if the  specified  string  does  not	appear
       exactly	as  a unit name, then the 'units' program will try to remove a
       trailing 's', 'es' or 'ies'.  If that fails, 'units' will check	for  a
       prefix.	 The  database	includes  all of the standard metric prefixes.
       Only one prefix is permitted per unit, so 'micromicrofarad' will  fail.
       However,  prefixes  can	appear	alone  with no unit following them, so
       'micro*microfarad' will work, as will 'micro microfarad'.

       To find out which units and prefixes are available, read  the  standard
       units data file, which is extensively annotated.

   English Customary Length Measure
       Before 1959, the value of a yard (and other units of measure defined in
       terms of it) differed slightly among  English-speaking  countries.   In
       1959,  Australia,  Canada,  New Zealand, the United Kingdom, the United
       States, and South  Africa  adopted  the	Canadian  value  of  1 yard  =
       0.9144 m  (exactly), which was approximately halfway between the values
       used by the UK and the US; it had the additional  advantage  of	making
       1 inch  = 2.54 cm (exactly).  This new standard was termed the Interna‐
       tional Yard.  Australia, Canada, and the UK then defined all  customary
       lengths	in  terms  of the International Yard (Australia did not define
       the furlong or rod); because many US land surveys were in terms of  the
       pre-1959  units,  the US continued to define customary surveyors' units
       (furlong, chain, rod, and link) in terms of the previous value for  the
       foot,  which was termed the US survey foot.  The US defined a US survey
       mile as 5280 US survey feet, and defined a statute mile as a US	survey
       mile.  The US values for these units differ from the international val‐
       ues by about 2 ppm.

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

       Except for distances that extend over hundreds of miles (such as in the
       US  State  Plane  Coordinate  System), the differences in the miles are
       usually insignificant:

	  You have: 100 surveymile - 100 mile
	  You want: inch
		  * 12.672025
		  / 0.078913984

       The pre-1959 UK values for these units can be obtained with the	prefix
       'UK'.

       In  the	US,  the  acre is officially defined in terms of the US survey
       foot, and here 'units' uses that  definition.   If  you	want  an  acre
       defined according to the international foot, use 'intacre'; the differ‐
       ence between these units is about 4 parts per million.

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

       Powers of units can be specified using the '^' character  as  shown  in
       the  following  example,  or  by simple concatenation of a unit and its
       exponent: 'cm3' is equivalent to 'cm^3'; if the exponent is  more  than
       one  digit, the '^' is required.  An exponent like '2^3^2' is evaluated
       right to left as usual.	The '^' operator has the second highest prece‐
       dence.  You can also use '**' as an exponent operator.

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

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

       You  multiply  units  using  a space or an asterisk ('*').  The example
       above shows both forms.	You can divide units using the slash ('/')  or
       with 'per'.

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

       When a unit includes a prefix, exponent operators apply to the combina‐
       tion, so 'centimeter^3' gives cubic centimeters.  If you  separate  the
       prefix  from  the unit with any multiplication operator, such as 'centi
       meter^3', then the prefix is treated as a separate unit, so  the  expo‐
       nent  does  not	apply.	 The  second example would be a hundredth of a
       cubic meter, not a centimeter.

       Multiplication using a space  has a  higher  precedence	than  division
       using  a slash and is evaluated left to right; in effect, the first '/'
       character marks the beginning of the denominator of a unit  expression.
       This  makes  it	simple	to  enter a quotient with several terms in the
       denominator: 'W / m^2 Hz'.  If you multiply  with  '*'  then  you  must
       group the terms in the denominator with parentheses: '@ / (m^2 * Hz)'.

       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 '*' operator is
       convenient for multiplying a sequence of quotients.  With the '*' oper‐
       ator,  the  example above becomes 'm/s * s/day', which is equivalent to
       'm/day'.  Similarly, you could write '1/2 * meter' to get half a meter.
       Alternatively,  parentheses  can  be used for grouping: you could write
       '(1/2) meter)' to get half a meter.  See Complicated  Unit  Expressions
       for an illustration of the various options.

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

	  You have: 1|2 inch
	  You want: cm
		  * 1.27
		  / 0.78740157

       You can use parentheses for grouping:

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

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

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

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

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

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

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

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

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

       The expression could also be correctly written as '(2+1/2) cups'.  Note
       that if you write '2 1|2 cups' the space is interpreted as  multiplica‐
       tion so the result is the same as '1 cup'.

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

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

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

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

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

   Built-in Functions
       Several	built-in  functions  are  provided: 'sin', 'cos', 'tan', 'ln',
       'log', 'log2', 'exp', 'acos', 'atan' and 'asin'.  The 'sin', 'cos', and
       'tan'  functions require either a dimensionless argument or an argument
       with dimensions of angle.

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

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

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

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

       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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       gives the same result as

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

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

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

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

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

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

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

	  You have: 1 mm
	  You want: wiregauge
		  18.201919

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       Note that 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 ';' adds the previous unit to the list; 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.  In many cases, you may prefer to round the
       last coefficient to an integer; you can	do  this  with	the  '--round'
       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)

       Each  unit  that appears on the list must be conformable with the first
       unit on the list, and of course the listed  units  must	also  be  com‐
       formable with the You have unit that you enter.

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

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

       In  the	first  case,  'units'  reports	the disagreement between units
       appearing on the list.  In the second case, 'units'  reports  disagree‐
       ment  between  the  unit  you entered and the desired conversion.  Note
       that the conformability error is based on the first unit  on  the  unit
       list.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       Appending ';' to 'oz' forces a one-line display that includes the unit.

       A unit list such as

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

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

	  hms	      hours, minutes, seconds
	  dms	      angle: degrees, minutes, seconds
	  time	      years, days, hours, minutes and seconds
	  usvol       US cooking volume: cups and smaller

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

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

       Note that unit list aliases have no effect at the 'You  have:'  prompt,
       and  'units'  treats  them as unknown units.  You cannot combine a unit
       list alias with other units: it must appear alone at  the  'You	want:'
       prompt.

       When you specify compact output with '--compact', '--terse' or '-t' and
       perform conversion to a unit list, 'units' lists the conversion factors
       for  each  unit in the list, separated by semicolons.  Note that unlike
       the case of regular output, zeros are included in this output list:

	  You have: year
	  You want: day;min;sec
		  365 day + 348 min + 45.974678 sec
	  You have: liter
	  You want: cup;1|2 cup;1|4 cup;tbsp
		  4;0;0;3.6280454

INVOKING UNITS
       You invoke 'units' like this:

	  units [options] [from-unit [to-unit]]

       If the from-unit and to-unit are omitted, then  the  program  will  use
       interactive  prompts  to  determine  which conversions to perform.  See
       Interactive Use.  If both from-unit and to-unit are given, 'units' will
       print  the  result  of  that  single conversion and then exit.  If only
       from-unit appears on the command line, 'units' will display the defini‐
       tion  of  that  unit and exit.  Units specified on the command line may
       need to be quoted to protect them  from	shell  interpretation  and  to
       group them into two arguments.  See Command Line Use.

       The  following  options allow you to read in an alternative units file,
       check your units file, or change the output format:

       -c, --check
	      Check that all units and prefixes defined in the units data file
	      reduce  to primitive units.  Print a list of all units that can‐
	      not be reduced.  Also display some other diagnostics about  sus‐
	      picious  definitions  in	the units data file.  Only definitions
	      active in the current locale are checked.  You should always run
	      'units' with this option after modifying a units data file.

       --check-verbose
	      Like  the  '--check'  option, this option prints a list of units
	      that cannot be reduced.  But to help find unit  definitions that
	      cause endless loops, it lists the units as they are checked.  If
	      'units' hangs, then the last unit to be printed has a bad  defi‐
	      nition.	Only  definitions  active  in  the  current locale are
	      checked.

       -o format, --output-format format
	      Use the specified format for numeric output;  the  format  is  a
	      subset  of  that for the printf function in the ANSI C standard.
	      Only a numeric format ('E' or 'e' for scientific	notation,  'f'
	      for  fixed-point decimal, or 'G' or 'g' to specify the number of
	      significant figures) is allowed.	The default format is  '%.8g';
	      for  greater  precision,	you  could  specify  '-o  %.15g'.  See
	      Numeric Output Format and the documentation for printf for  more
	      detailed descriptions of the format specification.

       -e, --exponential
	      Set  the	numeric output format to exponential (i.e., scientific
	      notation), like that used in the Unix 'units' program.

       -f filename, --file filename
	      Instruct 'units' to load the units file 'filename'.  If filename
	      is  the  empty string ('-f ""') then the default units file will
	      be loaded.  This enables you to load the	default  file  plus  a
	      personal	units  file.   You can specify up to 25 units files on
	      the command line.  When you use this option, 'units'  will  load
	      only  the  files you list on the command line.  It will not load
	      the standard file nor will it  load  your  personal  units  file
	      unless you explicitly list them.

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

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

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

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

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

       --compact
	      Give compact output featuring only the conversion factor.   This
	      turns off the '--verbose' option.

       -q, --quiet, --silent
	      Suppress prompting of the user for units and the display of sta‐
	      tistics about the number of units loaded.

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

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

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

       -s, --strict
	      Suppress conversion of units to  their  reciprocal  units.   For
	      example,	'units' will normally convert hertz to seconds because
	      these units are reciprocals of each other.   The	strict	option
	      requires that units be strictly conformable to perform a conver‐
	      sion, and will give an error if you attempt to convert hertz  to
	      seconds.

       -1, --one-line
	      Give  only  one line of output (the forward conversion).	Do not
	      print the reverse conversion.  Note that if a reciprocal conver‐
	      sion is performed then 'units' will still print the ``reciprocal
	      conversion'' line.

       -t, --terse
	      Give terse output when converting units.	 This  option  can  be
	      used  when calling 'units' from another program so that the out‐
	      put is easy to parse.  This option has the  combined  effect  of
	      these options: '--strict' '--quiet' '--one-line' '--compact'.

       -v, --verbose
	      Give  slightly  more verbose output when converting units.  When
	      combined with the '-c' option this  gives  the  same  effect  as
	      '--check-verbose'.

       -V, --version
	      Print  program  version  number,	tell  whether  the  'readline'
	      library has been included, and give the location of the  default
	      units data file.

ADDING YOUR OWN DEFINITIONS
   Units Data Files
       The  units  and	prefixes  that	'units' can convert are defined in the
       units data file, typically '/usr/share/units.dat'.   Although  you  can
       extend  or  modify  this  data file if you have appropriate user privi‐
       leges, it's usually better to put extensions in separate files so  that
       the definitions will be preserved if the 'units' program is updated.

       Additional  data  files can be included in the units database by use of
       the '!include' command in the standard units data file, for example

	  !include    /usr/local/share/localunits.dat

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

       If  you	want to add your own units in addition to or in place of stan‐
       dard or site-wide supplemental units data files, you can  include  them
       in  the	'.units.dat' 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.

       The  'units'  program first tries to determine your home directory from
       the 'HOME' environment variable.  On systems running Microsoft Windows,
       if  'HOME' does not exist, 'units' attempts to find your home directory
       from 'HOMEDRIVE' and 'HOMEPATH'.

       You can specify an arbitrary file as your personal units data file with
       the  'MYUNITSFILE'  environment	variable; if this variable exists, its
       value is used without searching your home directory.

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

       Unit  names  must  not contain any of the operator characters '+', '-',
       '*', '/', '|', '^', ';', the comment  character	'#',  or  parentheses.
       They  cannot  begin  with a digit, or a decimal point ('.'), and cannot
       begin or end with an underscore ('_').  If a name ends in a digit other
       than  zero,  the  digit	must be preceded by a string beginning with an
       underscore, and afterwards consisting only of digits,  decimal  points,
       or  commas.   For  example,  'foo_2', 'foo_2,1', or 'foo_3.14' would be
       valid names but 'foo2' or 'foo_a2' would be invalid.  You could	define
       nitrous oxide as

	  N2O	  nitrogen 2  + oxygen

       but would need to define nitrogen dioxide as

	  NO_2	  nitrogen + oxygen 2

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

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

       If  you	define	any units that contain '+' characters, 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 multiplication  depending  on
       the  options used to invoke 'units'.  To ensure consistent behavior use
       '-' only as a unary negation operator when writing  units  definitions.
       To  multiply two units leave a space or use the '*' operator with care,
       recalling that it has two possible precedence values  and  may  require
       parentheses  to	ensure consistent behavior.  To compute the difference
       of 'foo' and 'bar' write 'foo+(-bar)' or even 'foo+-bar'.

       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	  0.0254 m	  # Inch defined in terms of meters
	  ft	  12 inches	  # The foot defined in terms of inches
	  mile	  5280 ft	  # And the mile

       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 equivalent
       to '1 / (2 meter)'.

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

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

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

       Here is an example nonlinear unit definition:

	  tempF(x) [1;K] (x+(-32)) degF + stdtemp ; (tempF+(-stdtemp))/degF + 32

       A nonlinear unit definition comprises a unit name,  a  dummy  parameter
       name,  two  functions, and two corresponding units.  The functions tell
       'units' how to convert to and from the new unit.  In order  to  produce
       valid  results,	the arguments of these functions need to have the cor‐
       rect dimensions.  To facilitate error checking,	you  may  specify  the
       dimensions.

       The  definition begins with the unit name followed immediately (with no
       spaces) by a '(' character.  In parentheses is the name of the  parame‐
       ter.   Next  is	an optional specification of the units required by the
       functions in this definition.  In the example above, the 'tempF'  func‐
       tion  requires an input argument conformable with '1'.  For normal non‐
       linear units definitions the forward function will always take a dimen‐
       sionless  argument.   The  inverse  function requires an input argument
       conformable with 'K'.  In general the inverse function will need  units
       that match the quantity measured by your nonlinear unit.  The sole pur‐
       pose of the expression in brackets to enable 'units' to	perform  error
       checking on function arguments.

       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.

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

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

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

       If  you	wish  to  make synonyms for nonlinear units, you still need to
       define 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) [1;K] tempF(x); ~tempF(fahrenheit)

       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.	 Note that this definition requires a length as input and pro‐
       duces an area as output, as indicated by the specification in brackets.

	  circlearea(r) [m;m^2] pi r^2 ; sqrt(circlearea/pi)

       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 illegal; instead  write
       'foo[kg*meters]'.   The	definition  of	the unit consists of a list of
       pairs optionally separated by commas.  This list defines a function for
       converting  from  the piecewise linear unit to linear units.  The first
       item in each pair is the function argument;  the  second  item  is  the
       value  of  the  function  at  that  argument (in the units specified in
       brackets).  In this example, we define 'zincgauge' at five points.  For
       example,  we  set 'zincgauge(1)' equal to '0.002 in'.  Definitions like
       this may be  more readable  if written using   continuation  characters
       as

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

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

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

       If you define a piecewise linear unit that is not  strictly  monotonic,
       then the inverse will not be well defined.  If the inverse is requested
       for such a  unit,  'units'  will  return  the  smallest	inverse.   The
       '--check' option will print a warning if a non-monotonic piecewise lin‐
       ear unit is encountered.

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

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

       Unit list aliases are only for  unit  lists,  so  the  definition  must
       include	a  ';'.  Unit list aliases can never be combined with units or
       other unit list aliases, so the definition of 'time' shown above  could
       not  have  been	shortened to 'year;day;hms'.  As usual, be sure to run
       'units --check' to ensure that the units listed in  unit  list  aliases
       are conformable.

NUMERIC OUTPUT FORMAT
       By  default, results of conversions are shown to eight significant fig‐
       ures; this can be  changed  with  the  '--exponential'  and  '--output-
       format'	options.   The former sets an exponential format (i.e., scien‐
       tifc notation) like that used in the original Unix 'units' program; the
       latter  allows the format to be given as that of the printf function in
       the ANSI C standard.

       The format recognized with the '--output-format' option is a subset  of
       that   for   printf.    Only   a  floating-point  format  of  the  form
       '%'[flag][width]['.'precision]type is allowed: it must begin with  '%',
       and  must end with a floating-point type specifier ('E' or 'e' for sci‐
       entific notation, 'f' for fixed-point decimal, or 'G' or 'g' to specify
       the  number  of	significant  figures).	 The  format specification may
       include one optional flag ('+', '-', '#', or a space), followed	by  an
       optional  value	for the minimum field width, and an optional precision
       specification that begins with a period (e.g., '.6').  In  addition  to
       the  digits,  the field width includes the decimal point, the exponent,
       and the sign if any of these are shown.	A width specification is typi‐
       cally used with fixed-point decimal to have columns of numbers align at
       the decimal point; it normally is not useful with 'units'.   Non-float‐
       ing-point type specifiers make no sense for 'units', and are forbidden.

       The  default format is '%.8g'; for greater precision, you could specify
       '-o %.15g'.  The 'G' and 'g' formats use  exponential  format  whenever
       the  exponent  would be less than -5, so the value 0.000013 displays as
       '1.3e-005'.  If you prefer fixed-point display, you might  specify  '-o
       %.8f';  however,  very  small  numbers may display very few significant
       figures, and for very small numbers, may show nothing but zeros.

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

LOCALIZATION
       Some units have different values in different locations.  The localiza‐
       tion feature accommodates this by allowing a units data file to specify
       region  dependent  definitions.	  A locale region in a units data file
       begins with '!locale' followed by the name of the locale.  The  leading
       '!'   must appear in the first column of a units data file.  The locale
       region is terminated by '!endlocale'.  The following example shows  how
       to define a couple units in a locale.

	  !locale en_GB
	  ton			  brton
	  gallon		  brgallon
	  !endlocale

       The  current  locale  is specified using the standard environment vari‐
       ables 'LC_CTYPE' or 'LANG'.  Note that the '-c' option only checks  the
       definitions that are active for the current locale.

ENVIRONMENT VARIABLES
       The 'units' program uses the following environment variables:

       HOME   Specifies  the  location	of  your home directory; it is used by
	      'units' to find a personal units	data  file  '.units.dat'.   On
	      systems  running	Microsoft  Windows, 'units' tries to determine
	      your home directory from the 'HOMEDRIVE' and 'HOMEPATH' environ‐
	      ment variables if 'HOME' does not exist.

       LANG   Specifies  the locale.  The default is 'en_US'.  Sections of the
	      standard units data file are specific to certain locales.

       MYUNITSFILE
	      Specifies your personal  units  data  file.   If	this  variable
	      exists,  'units'	uses its value rather than searching your home
	      directory for '.units.dat'.

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

       UNITSFILE
	      Specifies the units data file to use (instead of	the  default).
	      This  will  be overridden by the '-f' option.  Note that you can
	      only specify a single units data	file  using  this  environment
	      variable.   You can override this variable and cause the default
	      data file to be loaded either by invoking units with 'UNITSFILE'
	      set  to  null  ('UNITSFILE= units') or by giving the '-f' option
	      with the empty string ('units -f ""').

UNICODE SUPPORT
       The standard units data file is written	in  Unicode  using  the  UTF-8
       encoding.   Portions  of  the  file that are not plain ASCII begin with
       '!utf8' and end with '!endutf8'.  As usual, the '!'  must appear as the
       first  character  on  the line.	If a line of a data file contains byte
       sequences that are invalid UTF-8 or  non-printing  UTF-8  then  'units'
       ignores the entire line.

       When  'units' runs it checks the locale to determine the character set.
       If UTF-8 is listed, then the utf8 definitions are read  into  the  pro‐
       gram.   If  any	other  character  set is in use, then 'units' works in
       plain ASCII without support for extended characters.

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

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

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

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

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

FILES
       /usr/local/share/units.dat — the standard units data file

AUTHOR
       Adrian Mariano (adrianm@gnu.org)



			       17 November 2011 		      UNITS(1)
