Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
UNITS(1)		    General Commands Manual		      UNITS(1)

       units --	unit conversion	and calculation	program

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

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

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

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

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

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

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

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

	  You have:

       At  the	'You have:'  prompt,  type the quantity	and units that you are
       converting from.	 For example, if you want to  convert  ten  meters  to
       feet,  type  '10	 meters'.   Next, 'units' will print 'You want:'.  You
       should type the units you want to convert to.  To convert to feet,  you
       would  type 'feet'.  If the 'readline' library was compiled in then tab
       will complete unit names. See Readline  Support	for  more  information
       about  'readline'.   To	quit  the  program under Unix, press Ctrl-C or
       Ctrl-D. Under Windows, press Ctrl-C or Ctrl-Z; with the latter, you may
       also need to press Enter.

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

	      *	32.808399
	      /	0.03048

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       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-

       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.

       The  conversion	information  is	 read  from  a units data file that is
       called	'definitions.units'   and   is	 usually   located   in	   the
       '/usr/share/units'  directory.	If  you	 invoke	 'units' with the '-V'
       option, it will print the location of  this  file.   The	 default  file
       includes	 definitions  for all familiar units, abbreviations and	metric
       prefixes.  It also includes many	obscure	or archaic units.  Many	common
       spelled-out numbers (e.g., 'seventeen') are recognized.

       Many constants of nature	are defined, including these:

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

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

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

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

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

   English Customary Units
       English customary units differ in various ways  in  different  regions.
       In  Britain  a complex system of	volume measurements featured different
       gallons for different materials such as a wine gallon  and  ale	gallon
       that  different	by  twenty percent.  This complexity was swept away in
       1824 by a reform	that created an	entirely new gallon, the British Impe-
       rial  gallon  defined  as  the  volume occupied by ten pounds of	water.
       Meanwhile in the	USA the	gallon is derived  from	 the  1707  Winchester
       wine  gallon, which is 231 cubic	inches.	 These gallons differ by about
       twenty percent.	By default if 'units' runs in the 'en_GB'  locale  you
       will get	the British volume measures.  If it runs in the	'en_US'	locale
       you will	get the	US volume measures.  In	other locales the default val-
       ues are the US definitions.  If you wish	to force different definitions
       then set	the environment	variable 'UNITS_ENGLISH'  to  either  'US'  or
       'GB' to set the desired definitions independent of the locale.

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

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

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

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

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

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

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

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

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

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

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

       You can use parentheses for grouping:

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

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

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

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

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

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

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

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

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

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

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

	  You have: 2^radian
	  Exponent not dimensionless

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

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

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

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

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

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

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

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

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

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

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

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

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

   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

       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

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

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

	  You have: cuberoot(hectare)
	  Unit not a root

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

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

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

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

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

	  You have: m_
	  Parse	error

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

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

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

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

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

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

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

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

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

   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-

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

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

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

       Nonlinear 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

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

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

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

       gives the same result as

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

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

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

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

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

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

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

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

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

	  You have: 1 mm
	  You want: wiregauge

	  You have: grit_P(600)
	  You want: grit_ansicoated

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

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

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

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

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

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

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

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

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

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

       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-

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

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

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

       The order in which you list the units is	important:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       A unit list such	as

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

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

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

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

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

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

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

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

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

	  You have: year
	  You want: day;min;sec

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

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

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

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

       were logged, the	log file would contain

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

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

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

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

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

       The log file would contain

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

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

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

       You invoke 'units' like this:

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

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

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

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

       The following options are available:

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

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

       -d ndigits, --digits ndigits
	      Set  the number of significant digits in the output to the value
	      specified	(which must  be	 greater  than	zero).	 For  example,
	      '-d 12' sets the number of significant digits to 12.  With expo-
	      nential output 'units' displays one digit	to  the	 left  of  the
	      decimal  point  and  eleven  digits  to the right	of the decimal
	      point.  On most systems, the maximum number of internally	 mean-
	      ingful  digits  is 15; if	you specify a greater number than your
	      system's maximum,	'units'	will print a warning and set the  num-
	      ber  to the largest meaningful value.  To	directly set the maxi-
	      mum value, give an  argument  of	'max'  (e.g.,  '-d max').   Be
	      aware,  of  course, that ``significant'' here refers only	to the
	      display of numbers; if results depend on physical	constants  not
	      known to this precision, the physically meaningful precision may
	      be less than that	shown.	The '--digits' option  conflicts  with
	      the '--output-format' option.

       -e, --exponential
	      Set  the	numeric	output format to exponential (i.e., scientific
	      notation), like that used	in  the	 Unix  'units'	program.   The
	      default  precision  is eight significant digits (seven digits to
	      the right	of the decimal point); this can	be  changed  with  the
	      '--digits'  option.   The	 '--exponential' option	conflicts with
	      the '--output-format' option.

       -o format, --output-format format
	      This option affords complete control  over  the  numeric	output
	      format using the specified format. The format is a single	float-
	      ing point	numeric	format for the 'printf()' function  in	the  C
	      programming  language.   All  compilers support the format types
	      'g' and 'G' to specify significant digits, 'e' and 'E' for  sci-
	      entific  notation, and 'f' for fixed-point decimal.  The ISO C99
	      standard introduced the 'F' type for fixed-point decimal and the
	      'a'  and	'A'  types for hexadecimal floating point; these types
	      are allowed with compilers that support them.  The default  for-
	      mat   is	'%.8g';	 for  greater  precision,  you	could  specify
	      '-o %.15g'.  See Numeric Output Format and the documentation for
	      'printf()' for more detailed descriptions	of the format specifi-
	      cation.  The '--output-format' option affords the	greatest  con-
	      trol of the output appearance, but requires at least rudimentary
	      knowledge	of the 'printf()' format syntax.  If you don't want to
	      bother  with the 'printf()' syntax, you can specify greater pre-
	      cision more simply with the '--digits' option or select exponen-
	      tial  format with	'--exponential'.  The '--output-format'	option
	      is incompatible with the '--exponential' and '--digits' options.

       -f filename, --file filename
	      Instruct 'units' to load the units file filename.	 You can spec-
	      ify up to	25 units files on the command line.  When you use this
	      option, 'units' will load	only the files you list	on the command
	      line;  it	will not load the standard file	or your	personal units
	      file unless you explicitly list them.  If	filename is the	 empty
	      string  ('-f ""'),  the default units file (or that specified by
	      'UNITSFILE') will	be loaded in addition to any others  specified
	      with '-f'.

       -L logfile, --log logfile
	      Save  the	 results of calculations in the	file logfile; this can
	      be useful	if it is important to have a record  of	 unit  conver-
	      sions  or	 other calculations that are to	be used	extensively or
	      in a critical activity such as a program or design project.   If
	      logfile  exits,  the new results are appended to the file.  This
	      option is	ignored	when 'units' is	used  non-interactively.   See
	      Logging  Calculations  for  a more detailed description and some

       -H filename, --history filename
	      Instruct 'units' to save history to filename, so that  a	record
	      of  your	commands  is  available	for retrieval across different
	      'units' invocations.  To prevent the history  from  being	 saved
	      set  filename to the empty string	('-H ""').  This option	has no
	      effect if	readline is not	available.

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

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

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

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

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

	      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

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

       -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

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

       -t, --terse
	      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'.
	      When  combined  with  '--version'	 it produces a display showing
	      only the program name and	version	number.

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

       -V, --version
	      Print  the  program  version number, tell	whether	the 'readline'
	      library has been included, tell whether UTF-8 support  has  been
	      included;	 give  the  locale,  the location of the default units
	      data file, and the location of the  personal  units  data	 file;
	      indicate if the personal units data file does not	exist.

       When given in combination with the '--terse' option, the	program	prints
       only the	version	number and exits.

       When given in combination with the '--verbose' option, the program, the
       '--version' option has the same effect as the '--info' option below.

       -I, --info
	      Print  the  information  given with the '--version' option, show
	      the pathname of the  units  program,  show  the  status  of  the
	      'UNITSFILE'  and	'MYUNITSFILE' environment variables, and addi-
	      tional information about how 'units' locates the related	files.
	      On   systems  running  Microsoft	Windows,  the  status  of  the
	      'UNITSLOCALE' environment	variable  and  information  about  the
	      related  locale  map  are	also given.  This option is usually of
	      interest only to developers and administrators, but it can some-
	      times be useful for troubleshooting.

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

       -U, --unitsfile
	      Print the	location of the	default	units data file	and  exit;  if
	      the file cannot be found,	print ``Units data file	not found''.

       -l locale, --locale locale
	      Print  the  information  given with the '--version' option, show
	      the Force	a specified locale such	as 'en_GB' to get British def-
	      initions	by default.  This overrides the	locale determined from
	      system settings or environment  variables.   See	Locale	for  a
	      description of locale format.

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

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

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

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

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

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

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

       Unit names must not contain any of the operator	characters  '+',  '-',
       '*',  '/',  '|',	'^', ';', '~', the comment character '#', or parenthe-
       ses.  They cannot begin or end with an underscore ('_'),	a comma	 (',')
       or  a  decimal  point  ('.').   The figure dash (U+2012), typographical
       minus (`-'; U+2212), and	en dash	(`-'; U+2013)  are  converted  to  the
       operator	 '-',  so  none	 of these characters can appear	in unit	names.
       Names cannot begin with a digit,	and if a name ends in  a  digit	 other
       than  zero,  the	 digit	must be	preceded by a string beginning with an
       underscore, and afterwards consisting only of digits,  decimal  points,
       or  commas.   For  example, 'foo_2', 'foo_2,1', or 'foo_3.14' are valid
       names but 'foo2'	or 'foo_a2' are	invalid.   You	could  define  nitrous
       oxide as

	  N2O	  nitrogen 2  +	oxygen

       but would need to define	nitrogen dioxide as

	  NO_2	  nitrogen + oxygen 2

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

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

       If  you	define	any units that contain '+' characters, 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 database, so that an eventual conversion to primitive
       units is	possible.

       Here is an example nonlinear unit definition:

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

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

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

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

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

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

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

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

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

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

	  square(x)	  x^2

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

	  squirt(x)	  sqrt(x)

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

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

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

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

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

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

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

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

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

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

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

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

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

	  fahrenheit()	tempF

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

	  fahrenheit()	meter

       will result in an error message when 'units' starts.

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

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

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

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

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

	  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-

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

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

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

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

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

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

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

	  Table	'ansicoated' lacks unique inverse around entry 800

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

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

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

   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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       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-

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

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

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

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

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

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

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

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

       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.

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

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

	  Windows-locale   POSIX-locale

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

	  English_United States	  en_US

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

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

	  !locale en_GB
	  gallon       4.54609 liter

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

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

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

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

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

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

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

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

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

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

       The 'units' program uses	the following environment variables:

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

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

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

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

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

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

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

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

       On  Unix-like  systems,	the  data  files  are  typically  located   in
       '/usr/share/units' if 'units' is	provided with the operating system, or
       in '/usr/local/share/units' if 'units' is compiled from the source dis-

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

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

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

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

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

       When 'units' starts, it checks the locale to  determine	the  character
       set.  If	'units'	is compiled with Unicode support and definitions; oth-
       erwise these definitions	are ignored.  When Unicode support is  active,
       'units'	will  check  every  line  of  all  of the units	data files for
       invalid or non-printing	UTF-8  sequences;  if  such  sequences	occur,
       'units'	ignores	 the  entire  line.  In	addition to checking validity,
       'units' determines the display width of non-ASCII characters to	ensure
       proper  positioning  of the pointer in some error messages and to align
       columns for the 'search'	and '?'	 commands.

       At present, 'units' does	not support Unicode under  Microsoft  Windows.
       The UTF-16 and UTF-32 encodings are not supported on any	systems.

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

       When  Unicode support is	not active, 'units' makes no assumptions about
       character encoding, except that characters in the range 00-7F hexadeci-
       mal  correspond	to  ASCII  encoding.   Non-ASCII characters are	simply
       sequences of bytes, and have no special meanings;  for  definitions  in
       supplementary  units  data  files,  you can use any encoding consistent
       with this assumption.  For example, if you wish to use non-ASCII	 char-
       acters in definitions when running 'units' under	Windows, you can use a
       character set such as Windows ``ANSI'' (code page 1252 in  the  US  and
       Western	Europe).   You can even	use UTF-8, though some messages	may be
       improperly  aligned,  and  'units'  will	 not  detect   invalid	 UTF-8
       sequences.   If	you  use  UTF-8	 encoding  when	Unicode	support	is not
       active, you should place	any definitions	with non-ASCII characters out-
       side '!utf8' ...	 '!endutf8' blocks--otherwise, they will be ignored.

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

       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.

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

       The  units program includes currency exchange rates and prices for some
       precious	metals in the database.	 Of course, these values  change  over
       time, sometimes very rapidly, and 'units' cannot	provide	real time val-
       ues.  To	update the exchange rates run the 'units_cur', which  rewrites
       the     files	 containing	the    currency	   rates,    typically
       '/usr/share/units/currency.units'.  This	program	requires 'python', and
       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.  Cur-
       rency exchange rates are	taken  from  Yahoo  (
       and  precious  metals  pricing  from  Packetizer	 (
       These sites update once per day,	so there is no benefit in running  the
       update  script  more  often than	daily.	You can	run 'units_cur'	with a
       filename	specified on the command line and it will write	 the  data  to
       that file.  If you give '-' for the file	it will	write to standard out-

       unit definition
	      Define a regular unit.

       prefix- definition
	      Define a prefix.

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

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

	      End a block of definitions beginning with	'!locale'

	      End a block of definitions begun with '!utf8'

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

       !include	file
	      Include the specified file.

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

       !message	text
	      Display text when	the database is	read unless the	 quiet	option
	      ('-q') is	enabled.

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

       !unitlist alias definition
	      Define a unit list alias.

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

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

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

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

				16 October 2017			      UNITS(1)


Want to link to this manual page? Use this URL:

home | help