1This manual is for GNU Units (version 2.00), which performs units
2conversions and units calculations.  A copy of the license is in‐
3cluded  in  the  section  entitled  ‘‘GNU  Free Documentation Li‐
4UNITS(1)                    General Commands Manual                   UNITS(1)
5
6
7
8cense’’.
9

NAME

11       units — unit conversion and calculation program
12

SYNOPSIS

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

DESCRIPTION

17       The 'units' program converts quantities expressed in various systems of
18       measurement to their equivalents in other systems of measurement.  Like
19       many similar programs, it can handle multiplicative scale  changes.  It
20       can  also  handle  nonlinear conversions such as Fahrenheit to Celsius.
21       See the examples below.  The program can also perform conversions  from
22       and  to  sums of units, such as converting between meters and feet plus
23       inches.
24
25       Beyond simple unit conversions, 'units' can be used as  a  general-pur‐
26       pose  scientific  calculator  that keeps track of units in its calcula‐
27       tions.  You can form  arbitrary  complex  mathematical  expressions  of
28       dimensions  including sums, products, quotients, powers, and even roots
29       of dimensions.  Thus you can ensure accuracy  and  dimensional  consis‐
30       tency  when  working  with long expressions that involve many different
31       units that may combine in complex ways.
32
33       The units are defined in an external data file.  You can use the exten‐
34       sive  data  file  that comes with this program, or you can provide your
35       own data file to suit your needs.  You can also use your own data  file
36       to supplement the standard data file.
37
38       Basic operation is simple: you enter the units that you want to convert
39       from and the units that you want to convert to.  You can use  the  pro‐
40       gram  interactively  with  prompts,  or you can use it from the command
41       line.
42

INTERACTING WITH UNITS

44       To invoke units for interactive use, type 'units' at your shell prompt.
45       The program will print something like this:
46
47          Currency exchange rates from 04/23/12
48          2516 units, 85 prefixes, 65 nonlinear units
49
50          You have:
51
52       At  the  'You  have:'  prompt, type the quantity and units that you are
53       converting from.  For example, if you want to  convert  ten  meters  to
54       feet,  type  '10  meters'.   Next, 'units' will print 'You want:'.  You
55       should type the units you want to convert to.  To convert to feet,  you
56       would  type 'feet'.  If the 'readline' library was compiled in then the
57       tab key can be used to complete unit names. See  Readline  Support  for
58       more information about 'readline'.  To quit the program press Ctrl-C or
59       Ctrl-D under Unix.  Under Windows press Ctrl-Z.
60
61       The answer will be displayed in two ways.  The first  line  of  output,
62       which is marked with a '*' to indicate multiplication, gives the result
63       of the conversion you have asked for.  The second line of output, which
64       is  marked  with  a  '/' to indicate division, gives the inverse of the
65       conversion factor.  If you convert 10  meters  to  feet,  'units'  will
66       print
67
68              * 32.808399
69              / 0.03048
70
71       which tells you that 10 meters equals about 32.8 feet.  The second num‐
72       ber gives the conversion in the opposite direction.  In this  case,  it
73       tells  you  that  1  foot  is  equal to about 0.03 dekameters since the
74       dekameter is 10 meters.  It also tells you that 1/32.8 is about 0.03.
75
76       The 'units' program prints the inverse because sometimes it is  a  more
77       convenient  number.   In  the  example  above, for example, the inverse
78       value is an exact conversion: a foot  is  exactly  0.03048  dekameters.
79       But the number given the other direction is inexact.
80
81       If you convert grains to pounds, you will see the following:
82
83          You have: grains
84          You want: pounds
85                  * 0.00014285714
86                  / 7000
87
88          From  the  second  line of the output you can immediately see that a
89       grain is equal to a seven thousandth of a pound.  This is not so  obvi‐
90       ous  from the first line of the output.  If you find  the output format
91       confusing, try using the '--verbose' option:
92
93          You have: grain
94          You want: aeginamina
95                  grain = 0.00010416667 aeginamina
96                  grain = (1 / 9600) aeginamina
97
98       If you request a  conversion  between  units  that  measure  reciprocal
99       dimensions,  then  'units'  will display the conversion results with an
100       extra note indicating that reciprocal conversion has been done:
101
102          You have: 6 ohms
103          You want: siemens
104                  reciprocal conversion
105                  * 0.16666667
106                  / 6
107
108       Reciprocal conversion can be suppressed by using the '--strict' option.
109       As usual, use the '--verbose' option to get more comprehensible output:
110
111          You have: tex
112          You want: typp
113                  reciprocal conversion
114                  1 / tex = 496.05465 typp
115                  1 / tex = (1 / 0.0020159069) typp
116
117          You have: 20 mph
118          You want: sec/mile
119                  reciprocal conversion
120                  1 / 20 mph = 180 sec/mile
121                  1 / 20 mph = (1 / 0.0055555556) sec/mile
122
123       If  you enter incompatible unit types, the 'units' program will print a
124       message indicating that the units are not conformable and it will  dis‐
125       play the reduced form for each unit:
126
127          You have: ergs/hour
128          You want: fathoms kg^2 / day
129          conformability error
130                  2.7777778e-11 kg m^2 / sec^3
131                  2.1166667e-05 kg^2 m / sec
132
133       If you only want to find the reduced form or definition of a unit, sim‐
134       ply press Enter at the 'You want:' prompt.  Here is an example:
135
136          You have: jansky
137          You want:
138                  Definition: fluxunit = 1e-26 W/m^2 Hz = 1e-26 kg / s^2
139
140       The output from 'units' indicates that the  jansky  is  defined  to  be
141       equal  to  a fluxunit which in turn is defined to be a certain combina‐
142       tion of watts, meters, and hertz.  The fully reduced (and in this  case
143       somewhat more cryptic) form appears on the far right.
144
145       Some  named  units  are  treated  as  dimensionless in some situations.
146       These units include the radian and  steradian.   These  units  will  be
147       treated  as  equal to 1 in units conversions.  Power is equal to torque
148       times angular velocity.  This conversion can only be performed  if  the
149       radian is dimensionless.
150
151          You have: (14 ft lbf) (12 radians/sec)
152          You want: watts
153                  * 227.77742
154                  / 0.0043902509
155
156       Named  dimensionless  units  are  not treated as dimensionless in other
157       contexts.   They  cannot  be  used  as  exponents   so   for   example,
158       'meter^radian' is not allowed.
159
160       If  you  want  a  list  of options you can type '?'  at the 'You want:'
161       prompt.  The program will display a list of named units that  are  con‐
162       formable  with  the  unit  that  you  entered at the 'You have:' prompt
163       above.  Conformable unit combinations will not appear on this list.
164
165       Typing 'help' at either prompt displays a short help message.  You  can
166       also  type 'help' followed by a unit name.  This will invoke a pager on
167       the units data base at the point where that unit is defined.   You  can
168       read the definition and comments that may give more details or histori‐
169       cal information about the unit.  (You can generally  quit  out  of  the
170       page by pressing 'q'.)
171
172       Typing  'search'  text  will  display  a list of all of the units whose
173       names contain text as a substring along with their  definitions.   This
174       may help in the case where you aren't sure of the right unit name.
175

USING UNITS NON-INTERACTIVELY

177       The  'units'  program  can  perform units conversions non-interactively
178       from the command line.  To do this, type the command, type the original
179       unit  expression,  and type the new units you want.  If a units expres‐
180       sion contains non-alphanumeric characters, you may need to  protect  it
181       from  interpretation  by the shell using single or double quote charac‐
182       ters.
183
184       If you type
185
186          units "2 liters" quarts
187
188       then 'units' will print
189
190              * 2.1133764
191              / 0.47317647
192
193       and then exit.  The output tells you that 2 liters is about 2.1 quarts,
194       or alternatively that a quart is about 0.47 times 2 liters.
195
196       If  the  conversion  is  successful,  then  'units' will return success
197       (zero) to the calling environment.  If you enter  non-conformable units
198       then  'units' will print a message giving the reduced form of each unit
199       and it will return failure (nonzero) to the calling environment.
200
201       When you invoke 'units' with only one argument, it will print  out  the
202       definition  of  the specified unit.  It will return failure if the unit
203       is not defined and success if the unit is defined.
204

UNIT DEFINITIONS

206       The conversion information is read from  a  units  data  file  that  is
207       called    'definitions.units'   and   is   usually   located   in   the
208       '/usr/share/units' directory.  If you  invoke  'units'  with  the  '-V'
209       option,  it  will  print  the  location of this file.  The default file
210       includes definitions for all familiar units, abbreviations  and  metric
211       prefixes.  It also includes many obscure or archaic units.
212
213       Many constants of nature are defined, including these:
214
215          pi          ratio of circumference to diameter
216          c           speed of light
217          e           charge on an electron
218          force       acceleration of gravity
219          mole        Avogadro's number
220          water       pressure per unit height of water
221          Hg          pressure per unit height of mercury
222          au          astronomical unit
223          k           Boltzman's constant
224          mu0         permeability of vacuum
225          epsilon0    permittivity of vacuum
226          G           Gravitational constant
227          mach        speed of sound
228
229       The  standard  data file includes atomic masses for all of the elements
230       and numerous other constants.  Also included are the densities of vari‐
231       ous  ingredients  used  in  baking so that '2 cups flour_sifted' can be
232       converted to 'grams'.  This is not an  exhaustive  list.   Consult  the
233       units  data  file  to  see the complete list, or to see the definitions
234       that are used.
235
236       The 'pound' is a unit of mass.  To get force,  multiply  by  the  force
237       conversion  unit 'force' or use the shorthand 'lbf'.  (Note that 'g' is
238       already taken as the standard abbreviation for  the  gram.)   The  unit
239       'ounce'  is  also  a  unit of mass.  The fluid ounce is 'fluidounce' or
240       'floz'.  British capacity units that differ from their US counterparts,
241       such  as the British Imperial gallon, are prefixed with 'br'.  Currency
242       is prefixed with its country name: 'belgiumfranc', 'britainpound'.
243
244       When searching for a unit, if the  specified  string  does  not  appear
245       exactly  as  a unit name, then the 'units' program will try to remove a
246       trailing 's', 'es'.  Next units will replace a trailing 'ies' with 'y'.
247       If  that fails, 'units' will check for a prefix.  The database includes
248       all of the standard metric prefixes.  Only one prefix is permitted  per
249       unit,  so  'micromicrofarad'  will  fail.  However, prefixes can appear
250       alone with no unit following them, so 'micro*microfarad' will work,  as
251       will 'micro microfarad'.
252
253       To  find  out which units and prefixes are available, read the standard
254       units data file, which is extensively annotated.
255
256   English Customary Units
257       English customary units differ in various ways  in  different  regions.
258       In  Britain  a complex system of volume measurements featured different
259       gallons for different materials such as a wine gallon  and  ale  gallon
260       that  different  by  twenty percent.  This complexity was swept away in
261       1824 by a reform that created an entirely new gallon, the British Impe‐
262       rial  gallon  defined  as  the  volume occupied by ten pounds of water.
263       Meanwhile in the USA the gallon is derived  from  the  1707  Winchester
264       wine  gallon, which is 231 cubic inches.  These gallons differ by about
265       twenty percent.  By default if 'units' runs in the 'en_GB'  locale  you
266       will get the British volume measures.  If it runs in the 'en_US' locale
267       you will get the US volume measures.  In other locales the default val‐
268       ues are the US definitions.  If you wish to force different definitions
269       then set the environment variable 'UNITS_ENGLISH'  to  either  'US'  or
270       'GB' to set the desired definitions independent of the locale.
271
272       Before 1959, the value of a yard (and other units of measure defined in
273       terms of it) differed slightly among  English-speaking  countries.   In
274       1959,  Australia,  Canada,  New Zealand, the United Kingdom, the United
275       States, and South  Africa  adopted  the  Canadian  value  of  1 yard  =
276       0.9144 m  (exactly), which was approximately halfway between the values
277       used by the UK and the US; it had the additional  advantage  of  making
278       1 inch  = 2.54 cm (exactly).  This new standard was termed the Interna‐
279       tional Yard.  Australia, Canada, and the UK then defined all  customary
280       lengths  in  terms  of the International Yard (Australia did not define
281       the furlong or rod); because many US land surveys were in terms of  the
282       pre-1959  units,  the US continued to define customary surveyors' units
283       (furlong, chain, rod, and link) in terms of the previous value for  the
284       foot,  which was termed the US survey foot.  The US defined a US survey
285       mile as 5280 US survey feet, and defined a statute mile as a US  survey
286       mile.  The US values for these units differ from the international val‐
287       ues by about 2 ppm.
288
289       The 'units' program uses the international values for these units;  the
290       US values can be obtained by using either the 'US' or the 'survey' pre‐
291       fix.  In either case, the simple familiar relationships among the units
292       are  maintained,  e.g., 1 'furlong' = 660 'ft', and 1 'USfurlong' = 660
293       'USft', though the metric equivalents differ slightly between  the  two
294       cases.   The  'US'  prefix  or  the 'survey' prefix can also be used to
295       obtain the US survey mile and the value of the US yard prior  to  1959,
296       e.g., 'USmile' or 'surveymile' (but not 'USsurveymile').  To get the US
297       value of the statute mile, use either 'USstatutemile' or 'USmile'.
298
299       Except for distances that extend over hundreds of miles (such as in the
300       US  State  Plane  Coordinate  System), the differences in the miles are
301       usually insignificant:
302
303          You have: 100 surveymile - 100 mile
304          You want: inch
305                  * 12.672025
306                  / 0.078913984
307
308       The pre-1959 UK values for these units can be obtained with the  prefix
309       'UK'.
310
311       In  the  US,  the  acre is officially defined in terms of the US survey
312       foot, but 'units' uses a definition based on  the  international  foot.
313       If  you  want  the  official  US  acre  use  'USacre' and similarly use
314       'USacrefoot' for the official US version of that unit.  The  difference
315       between these units is about 4 parts per million.
316

UNIT EXPRESSIONS

318   Operators
319       You can enter more complicated units by combining units with operations
320       such as powers, multiplication, division,  addition,  subtraction,  and
321       parentheses  for grouping.  You can use the customary symbols for these
322       operators when 'units' is invoked with its default options.   Addition‐
323       ally,  'units' supports some extensions, including high priority multi‐
324       plication using a space, and a high priority numerical
325        division operator ('|') that can simplify some expressions.
326
327       Powers of units can be specified using the '^' character  as  shown  in
328       the  following  example,  or  by simple concatenation of a unit and its
329       exponent: 'cm3' is equivalent to 'cm^3'; if the exponent is  more  than
330       one  digit, the '^' is required.  An exponent like '2^3^2' is evaluated
331       right to left as usual.  The '^' operator has the second highest prece‐
332       dence.  You can also use '**' as an exponent operator.
333
334          You have: cm^3
335          You want: gallons
336                  * 0.00026417205
337                  / 3785.4118
338
339          You have: arabicfoot * arabictradepound * force
340          You want: ft lbf
341                  * 0.7296
342                  / 1.370614
343
344       You  multiply  units  using  a space or an asterisk ('*').  The example
345       above shows both forms.  You can divide units using the slash ('/')  or
346       with 'per'.
347
348          You have: furlongs per fortnight
349          You want: m/s
350                  * 0.00016630986
351                  / 6012.8727
352
353       When a unit includes a prefix, exponent operators apply to the combina‐
354       tion, so 'centimeter^3' gives cubic centimeters.  If you  separate  the
355       prefix  from  the unit with any multiplication operator, such as 'centi
356       meter^3', then the prefix is treated as a separate unit, so  the  expo‐
357       nent  does  not  apply.   The  second example would be a hundredth of a
358       cubic meter, not a centimeter.
359
360       Multiplication using a space  has a  higher  precedence  than  division
361       using  a slash and is evaluated left to right; in effect, the first '/'
362       character marks the beginning of the denominator of a unit  expression.
363       This  makes  it  simple  to  enter a quotient with several terms in the
364       denominator: 'W / m^2 Hz'.  If you multiply  with  '*'  then  you  must
365       group the terms in the denominator with parentheses: 'W / (m^2 * Hz)'.
366
367       The  higher precedence of the space operator may not always be advanta‐
368       geous.  For example, 'm/s s/day' is equivalent to 'm / s s day' and has
369       dimensions  of length per time cubed.  Similarly, '1/2 meter' refers to
370       a unit of reciprocal length equivalent to 0.5/meter, perhaps  not  what
371       you  would  intend if you entered that expression.  The '*' operator is
372       convenient for multiplying a sequence of quotients.  With the '*' oper‐
373       ator,  the  example above becomes 'm/s * s/day', which is equivalent to
374       'm/day'.  Similarly, you could write '1/2 * meter' to get half a meter.
375       Alternatively,  parentheses  can  be used for grouping: you could write
376       '(1/2) meter' to get half a meter.  See  Complicated  Unit  Expressions
377       for an illustration of the various options.
378
379       The  'units'  program  supports another option for numerical fractions.
380       You can indicate division of numbers with the vertical bar ('|'), so if
381       you wanted half a meter you could write '1|2 meter'.  This operator has
382       the highest precedence, so you can write the square root of two  thirds
383       '2|3^1|2'.   You  cannot  use  the vertical bar to indicate division of
384       non-numerical units (e.g., 'm|s' results in an error message).
385
386          You have: 1|2 inch
387          You want: cm
388                  * 1.27
389                  / 0.78740157
390
391       You can use parentheses for grouping:
392
393          You have: (1/2) kg / (kg/meter)
394          You want: league
395                  * 0.00010356166
396                  / 9656.0833
397
398   Sums and Differences of Units
399       Outside of the SI, it is sometimes desirable to add values of different
400       units.   You  may  also  wish to use 'units' as a calculator that keeps
401       track of units.  Sums of conformable units are  written  with  the  '+'
402       character, and differences with the '-' character.
403
404          You have: 2 hours + 23 minutes + 32 seconds
405          You want: seconds
406                  * 8612
407                  / 0.00011611705
408
409          You have: 12 ft + 3 in
410          You want: cm
411                  * 373.38
412                  / 0.0026782366
413
414          You have: 2 btu + 450 ft lbf
415          You want: btu
416                  * 2.5782804
417                  / 0.38785542
418
419       The  expressions  that are added or subtracted must reduce to identical
420       expressions in primitive units, or an error message will be displayed:
421
422          You have: 12 printerspoint - 4 heredium
423                                                ^
424          Illegal sum of non-conformable units
425
426       As usual, the precedence for '+' and '-' is  lower  than  that  of  the
427       other operators.  A fractional quantity such as 2 1/2 cups can be given
428       as '(2+1|2) cups'; the parentheses are necessary because multiplication
429       has  higher  precedence  than  addition.   If you omit the parentheses,
430       'units' attempts to add '2' and '1|2 cups', and you get an  error  mes‐
431       sage:
432
433          You have: 2+1|2 cups
434                             ^
435          Illegal sum or difference of non-conformable units
436
437       The  expression  could also be correctly written as '(2+1/2) cups'.  If
438       you write '2 1|2 cups' the space is interpreted  as  multiplication  so
439       the result is the same as '1 cup'.
440
441       The  '+'  and  '-'  characters  sometimes  appears  in  exponents  like
442       '3.43e+8'.  This leads to an ambiguity in an expression like '3e+2 yC'.
443       The  unit  'e'  is  a  small unit of charge, so this can be regarded as
444       equivalent to '(3e+2)  yC'  or  '(3  e)+(2  yC)'.   This  ambiguity  is
445       resolved  by  always interpreting '+' and '-' as part of an exponent if
446       possible.
447
448   Numbers as Units
449       For 'units', numbers are just another kind of unit.  They can appear as
450       many  times  as  you  like  and in any order in a unit expression.  For
451       example, to find the volume of a box that is 2 ft by 3 ft by 12  ft  in
452       steres, you could do the following:
453
454          You have: 2 ft 3 ft 12 ft
455          You want: stere
456                  * 2.038813
457                  / 0.49048148
458
459          You have: $ 5 / yard
460          You want: cents / inch
461                  * 13.888889
462                  / 0.072
463
464       And  the  second example shows how the dollar sign in the units conver‐
465       sion can precede the five.  Be careful:  'units'  will  interpret  '$5'
466       with no space as equivalent to 'dollar^5'.
467
468   Built-in Functions
469       Several  built-in  functions  are  provided: 'sin', 'cos', 'tan', 'ln',
470       'log', 'log2', 'exp', 'acos', 'atan' and 'asin'.  The 'sin', 'cos', and
471       'tan'  functions require either a dimensionless argument or an argument
472       with dimensions of angle.
473
474          You have: sin(30 degrees)
475          You want:
476                  Definition: 0.5
477
478          You have: sin(pi/2)
479          You want:
480                  Definition: 1
481
482          You have: sin(3 kg)
483                            ^
484          Unit not dimensionless
485
486       The other functions on the list require dimensionless  arguments.   The
487       inverse  trigonometric  functions  return  arguments with dimensions of
488       angle.
489
490       If you wish to  take  roots  of  units,  you  may  use  the  'sqrt'  or
491       'cuberoot'  functions.   These functions require that the argument have
492       the appropriate root.  You can obtain higher roots by using  fractional
493       exponents:
494
495          You have: sqrt(acre)
496          You want: feet
497                  * 208.71074
498                  / 0.0047913202
499
500          You have: (400 W/m^2 / stefanboltzmann)^(1/4)
501          You have:
502                  Definition: 289.80882 K
503
504          You have: cuberoot(hectare)
505                                    ^
506          Unit not a root
507
508   Complicated Unit Expressions
509       The  'units'  program  is  especially  helpful in ensuring accuracy and
510       dimensional consistency when converting lengthy unit expressions.   For
511       example, one form of the Darcy-Weisbach fluid-flow equation is
512
513            Delta P = (8 / pi)^2 (rho fLQ^2) / d^5,
514
515       where  Delta  P is the pressure drop, rho is the mass density, f is the
516       (dimensionless) friction factor, L is the length of the pipe, Q is  the
517       volumetric  flow rate, and d is the pipe diameter.  It might be desired
518       to have the equation in the form
519
520            Delta P = A1 rho fLQ^2 / d^5
521
522       that accepted the user's normal units; for typical units  used  in  the
523       US, the required conversion could be something like
524
525          You have: (8/pi^2)(lbm/ft^3)ft(ft^3/s)^2(1/in^5)
526          You want: psi
527                  * 43.533969
528                  / 0.022970568
529
530       The  parentheses allow individual terms in the expression to be entered
531       naturally, as they might be read from the formula.  Alternatively,  the
532       multiplication  could  be  done  with the '*' rather than a space; then
533       parentheses are needed only around 'ft^3/s' because of its exponent:
534
535          You have: 8/pi^2 * lbm/ft^3 * ft * (ft^3/s)^2 /in^5
536          You want: psi
537                  * 43.533969
538                  / 0.022970568
539
540       Without parentheses, and using spaces for multiplication, the  previous
541       conversion would need to be entered as
542
543          You have: 8 lb ft ft^3 ft^3 / pi^2 ft^3 s^2 in^5
544          You want: psi
545                  * 43.533969
546                  / 0.022970568
547
548   Backwards Compatibility:
549       '*'  and  '-'  The  original  'units'  assigned multiplication a higher
550       precedence than division using the slash.  This differs from the  usual
551       precedence  rules,  which give multiplication and division equal prece‐
552       dence, and can be confusing for people who think of units as a calcula‐
553       tor.
554
555       The  star  operator  ('*')  included  in  this  'units' program has, by
556       default, the same precedence as division, and hence follows  the  usual
557       precedence  rules.   For backwards compatibility you can invoke 'units'
558       with the '--oldstar' option.  Then '*' has  a  higher  precedence  than
559       division, and the same precedence as multiplication using the space.
560
561       Historically,  the hyphen ('-') has been used in technical publications
562       to indicate products of units, and the original 'units' program treated
563       it  as  a  multiplication  operator.   Because 'units' provides several
564       other ways to obtain unit products, and because '-'  is  a  subtraction
565       operator  in  general  algebraic expressions, 'units' treats the binary
566       '-' as a subtraction operator by default.  For backwards  compatibility
567       use  the  '--product'  option, which causes 'units' to treat the binary
568       '-' operator as a product operator.  When '-' is a multiplication oper‐
569       ator  it has the same precedence as multiplication with a space, giving
570       it a higher precedence than division.
571
572       When '-' is used as a unary operator it negates its  operand.   Regard‐
573       less of the 'units' options, if '-' appears after '(' or after '+' then
574       it will act as a negation operator.   So  you  can  always  compute  20
575       degrees  minus  12  minutes by entering '20 degrees + -12 arcmin'.  You
576       must use this construction when you define new units because you cannot
577       know what options will be in force when your definition is processed.
578

NONLINEAR UNIT CONVERSIONS

580       Nonlinear  units  are represented using functional notation.  They make
581       possible nonlinear unit conversions such as temperature.
582
583   Temperature Conversions
584       Conversions between temperatures are different from linear  conversions
585       between  temperature  increments—see  the  example below.  The absolute
586       temperature conversions are handled by units starting with 'temp',  and
587       you  must  use  functional notation.  The temperature-increment conver‐
588       sions are done using units starting with 'deg' and they do not  require
589       functional notation.
590
591          You have: tempF(45)
592          You want: tempC
593                  7.2222222
594
595          You have: 45 degF
596          You want: degC
597                  * 25
598                  / 0.04
599
600       Think  of 'tempF(x)' not as a function but as a notation that indicates
601       that x should have units of 'tempF' attached to it.  See Defining  Non‐
602       linear  Units.   The  first  conversion  shows  that if it's 45 degrees
603       Fahrenheit outside, it's 7.2 degrees Celsius.   The  second  conversion
604       indicates  that  a  change  of  45  degrees Fahrenheit corresponds to a
605       change of 25 degrees Celsius.  The conversion  from  'tempF(x)'  is  to
606       absolute temperature, so that
607
608          You have: tempF(45)
609          You want: degR
610                  * 504.67
611                  / 0.0019814929
612
613       gives the same result as
614
615          You have: tempF(45)
616          You want: tempR
617                  * 504.67
618                  / 0.0019814929
619
620       But  if  you  convert  'tempF(x)' to 'degC', the output is probably not
621       what you expect:
622
623          You have: tempF(45)
624          You want: degC
625                  * 280.37222
626                  / 0.0035666871
627
628       The result is the temperature in K, because 'degC' is defined  as  'K',
629       the Kelvin. For consistent results, use the 'tempX' units when convert‐
630       ing to a temperature rather than converting a temperature increment.
631
632   Other Nonlinear Units
633       Some other examples of nonlinear  units  are  numerous  different  ring
634       sizes  and  wire gauges, the grit sizes used for abrasives, the decibel
635       scale, shoe size, scales for the density of sugar  (e.g.  baume).   The
636       standard data file also supplies units for computing the area of a cir‐
637       cle and the volume of a sphere.  See the standard units data  file  for
638       more  details.   Wire  gauges  with multiple zeroes are signified using
639       negative numbers where two zeroes is '-1'.  Alternatively, you can  use
640       the  synonyms 'g00', 'g000', and so on that are defined in the standard
641       units data file.
642
643          You have: wiregauge(11)
644          You want: inches
645                  * 0.090742002
646                  / 11.020255
647
648          You have: brwiregauge(g00)
649          You want: inches
650                  * 0.348
651                  / 2.8735632
652
653          You have: 1 mm
654          You want: wiregauge
655                  18.201919
656
657          You have: grit_P(600)
658          You want: grit_ansicoated
659                  342.76923
660
661       The last example shows the conversion from P graded sand  paper,  which
662       is the European standard and may be marked ``P600'' on the back, to the
663       USA standard.
664
665       You can compute  the  area  of  a  circle  using  the  nonlinear  unit,
666       'circlearea'.   You  can  also  do  this using the circularinch or cir‐
667       cleinch.  The next example shows two ways to compute the area of a cir‐
668       cle  with  a  five  inch  radius and one way to compute the volume of a
669       sphere with a radius of one meter.
670
671          You have: circlearea(5 in)
672          You want: in2
673                  * 78.539816
674                  / 0.012732395
675
676          You have: 10^2 circleinch
677          You want: in2
678                  * 78.539816
679                  / 0.012732395
680
681          You have: spherevol(meter)
682          You want: ft3
683                  * 147.92573
684                  / 0.0067601492
685

UNIT LISTS: CONVERSION TO SUMS OF UNITS

687       Outside of the SI, it is sometimes desirable to convert a  single  unit
688       to  a  sum of units—for example, feet to feet plus inches.  The conver‐
689       sion from sums of units was described in Sums and Differences of  Units
690       and is a simple matter of adding the units with the '+' sign:
691
692          You have: 12 ft + 3 in + 3|8 in
693          You want: ft
694                  * 12.28125
695                  / 0.081424936
696
697       Although  you  can  similarly  write  a sum of units to convert to, the
698       result will not be the conversion to the units in the sum,  but  rather
699       the conversion to the particular sum that you have entered:
700
701          You have: 12.28125 ft
702          You want: ft + in + 1|8 in
703                  * 11.228571
704                  / 0.089058524
705
706       The  unit  expression  given at the 'You want:' prompt is equivalent to
707       asking for conversion to multiples of '1 ft + 1 in + 1|8 in', which  is
708       1.09375 ft, so the conversion in the previous example is equivalent to
709
710          You have: 12.28125 ft
711          You want: 1.09375 ft
712                  * 11.228571
713                  / 0.089058524
714
715       In  converting to a sum of units like miles, feet and inches, you typi‐
716       cally want the largest integral value for the first unit,  followed  by
717       the largest integral value for the next, and the remainder converted to
718       the last unit.  You can do this conversion easily with 'units' using  a
719       special  syntax for lists of units.  You must list the desired units in
720       order from largest to smallest, separated by the semicolon (';')  char‐
721       acter:
722
723          You have: 12.28125 ft
724          You want: ft;in;1|8 in
725                  12 ft + 3 in + 3|8 in
726
727       The  conversion  always  gives integer coefficients on the units in the
728       list, except possibly the last unit when the conversion is not exact:
729
730          You have: 12.28126 ft
731          You want: ft;in;1|8 in
732                  12 ft + 3 in + 3.00096 * 1|8 in
733
734       The order in which you list the units is important:
735
736          You have: 3 kg
737          You want: oz;lb
738                  105 oz + 0.051367866 lb
739
740          You have: 3 kg
741          You want: lb;oz
742                  6 lb + 9.8218858 oz
743
744       Listing ounces before pounds produces a technically correct result, but
745       not  a very useful one.  You must list the units in descending order of
746       size in order to get the most useful result.
747
748       Ending a unit list with the  separator  ';'  has  the  same  effect  as
749       repeating  the  last unit on the list, so 'ft;in;1|8 in;' is equivalent
750       to 'ft;in;1|8 in;1|8 in'.  With the example above, this gives
751
752          You have: 12.28126 ft
753          You want: ft;in;1|8 in;
754                  12 ft + 3 in + 3|8 in + 0.00096 * 1|8 in
755
756       in effect separating the integer and fractional parts  of  the  coeffi‐
757       cient for the last unit.  If you instead prefer to round the last coef‐
758       ficient to an integer you can do this with the '--round' ('-r') option.
759       With the previous example, the result is
760
761          You have: 12.28126 ft
762          You want: ft;in;1|8 in
763                  12 ft + 3 in + 3|8 in (rounded down to nearest 1|8 in)
764
765       When  you  use the '-r' option, repeating the last unit on the list has
766       no effect (e.g., 'ft;in;1|8 in;1|8  in'  is  equivalent  to  'ft;in;1|8
767       in'),  and  hence neither does ending a list with a ';'.  With a single
768       unit and the '-r' option, a terminal ';' does have an effect: it causes
769       'units'  to treat the single unit as a list and produce a rounded value
770       for the single unit.  Without the extra ';', the  '-r'  option  has  no
771       effect  on single unit conversions.  This example shows the ouput using
772       the '-r' option:
773
774          You have: 12.28126 ft
775          You want: in
776                  * 147.37512
777                  / 0.0067854058
778
779          You have: 12.28126 ft
780          You want: in;
781                  147 in (rounded down to nearest in)
782
783       Each unit that appears in the list must be conformable with  the  first
784       unit  on  the  list,  and  of course the listed units must also be com‐
785       formable with the You have unit that you enter.
786
787          You have: meter
788          You want: ft;kg
789                       ^
790          conformability error
791                  ft = 0.3048 m
792                  kg = 1 kg
793
794          You have: meter
795          You want: lb;oz
796          conformability error
797                  1 m
798                  0.45359237 kg
799
800       In the first case,  'units'  reports  the  disagreement  between  units
801       appearing  on  the list.  In the second case, 'units' reports disagree‐
802       ment between the unit you entered and  the  desired  conversion.   This
803       conformability error is based on the first unit on the unit list.
804
805       Other  common candidates for conversion to sums of units are angles and
806       time:
807
808          You have: 23.437754 deg
809          You want; deg;arcmin;arcsec
810              23 deg + 26 arcmin + 15.9144 arcsec
811
812              You have: 7.2319 hr
813              You want: hr;min;sec
814                  7 hr + 13 min + 54.84 sec
815
816       In North America, recipes for cooking typically measure ingredients  by
817       volume,  and use units that are not always convenient multiples of each
818       other.  Suppose that you have a recipe for 6 and you  wish  to  make  a
819       portion  for  1.   If the recipe calls for 2 1/2 cups of an ingredient,
820       you might wish to know the measurements in terms of  measuring  devices
821       you have available, you could use 'units' and enter
822
823          You have: (2+1|2) cup / 6
824          You want: cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
825                  1|3 cup + 1 tbsp + 1 tsp
826
827       By  default,  if  a unit in a list begins with fraction of the form 1|x
828       and its multiplier is an integer, the fraction is given as the  product
829       of the multiplier and the numerator; for example,
830
831          You have: 12.28125 ft
832          You want: ft;in;1|8 in;
833                  12 ft + 3 in + 3|8 in
834
835       In  many  cases, such as the example above, this is what is wanted, but
836       sometimes it is not.  For example, a cooking recipe for  6  might  call
837       for  5 1/4 cup of an ingredient, but you want a portion for 2, and your
838       1-cup measure is not available; you might try
839
840          You have: (5+1|4) cup / 3
841          You want: 1|2 cup;1|3 cup;1|4 cup
842                  3|2 cup + 1|4 cup
843
844       This result might be fine for a baker who has a 1 1/2-cup measure  (and
845       recognizes  the  equivalence),  but  it may not be as useful to someone
846       with more limited set of measures, who does want to do additional  cal‐
847       culations, and only wants to know ``How many 1/2-cup measures to I need
848       to add?''  After  all,  that's  what  was  actually  asked.   With  the
849       '--show-factor'  option,  the  factor will not be combined with a unity
850       numerator, so that you get
851
852          You have: (5+1|4) cup / 3
853          You want: 1|2 cup;1|3 cup;1|4 cup
854                  3 * 1|2 cup + 1|4 cup
855
856       A user-specified fractional unit with a numerator other than 1 is never
857       overridden,  however—if  a  unit  list  specifies  '3|4 cup;1|2 cup', a
858       result equivalent to 1 1/2 cups will always be shown as '2 *  3|4  cup'
859       whether or not the '--show-factor' option is given.
860
861       Some applications for unit lists may be less obvious.  Suppose that you
862       have a postal scale and wish to ensure that it's accurate at 1 oz,  but
863       have only metric calibration weights.  You might try
864
865          You have: 1 oz
866          You want: 100 g;50 g; 20 g;10 g;5 g;2 g;1 g;
867                  20 g + 5 g + 2 g + 1 g + 0.34952312 * 1 g
868
869       You might then place one each of the 20 g, 5 g, 2 g, and 1 g weights on
870       the scale and hope that it indicates close to
871
872          You have: 20 g + 5 g + 2 g + 1 g
873          You want: oz;
874                  0.98767093 oz
875
876       Appending ';' to 'oz' forces a one-line display that includes the unit;
877       here the integer part of the result is zero, so it is not displayed.
878
879       A unit list such as
880
881          cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
882
883       can  be tedious to enter.  The 'units' program provides shorthand names
884       for some common combinations:
885
886          hms         hours, minutes, seconds
887          dms         angle: degrees, minutes, seconds
888          time        years, days, hours, minutes and seconds
889          usvol       US cooking volume: cups and smaller
890
891       Using these shorthands, or unit list aliases, you can do the  following
892       conversions:
893
894          You have: anomalisticyear
895          You want: time
896                  1 year + 25 min + 3.4653216 sec
897          You have: 1|6 cup
898          You want: usvol
899                  2 tbsp + 2 tsp
900
901       You  cannot  combine a unit list alias with other units: it must appear
902       alone at the 'You want:' prompt.
903
904       You can display the definition of a unit list alias by entering  it  at
905       the 'You have:' prompt:
906
907          You have: dms
908                  Definition: unit list, deg;arcmin;arcsec
909
910       When you specify compact output with '--compact', '--terse' or '-t' and
911       perform conversion to a unit list, 'units' lists the conversion factors
912       for each unit in the list, separated by semicolons.
913
914          You have: year
915          You want: day;min;sec
916          365;348;45.974678
917
918       Unlike  the  case  of regular output, zeros are included in this output
919       list:
920
921          You have: liter
922          You want: cup;1|2 cup;1|4 cup;tbsp
923          4;0;0;3.6280454
924

INVOKING UNITS

926       You invoke 'units' like this:
927
928          units [options] [from-unit [to-unit]]
929
930       If the from-unit and to-unit are omitted, then  the  program  will  use
931       interactive  prompts  to  determine  which conversions to perform.  See
932       Interactive Use.  If both from-unit and to-unit are given, 'units' will
933       print  the  result  of  that  single conversion and then exit.  If only
934       from-unit appears on the command line, 'units' will display the defini‐
935       tion  of  that  unit and exit.  Units specified on the command line may
936       need to be quoted to protect them  from  shell  interpretation  and  to
937       group them into two arguments.  See Command Line Use.
938
939       The  following  options allow you to read in an alternative units file,
940       check your units file, or change the output format:
941
942       -c, --check
943              Check that all units and prefixes defined in the units data file
944              reduce  to primitive units.  Print a list of all units that can‐
945              not be reduced.  Also display some other diagnostics about  sus‐
946              picious  definitions  in  the units data file.  Only definitions
947              active in the current locale are checked.  You should always run
948              'units' with this option after modifying a units data file.
949
950       --check-verbose, --verbose-check
951              Like  the  '--check'  option, this option prints a list of units
952              that cannot be reduced.  But to help find unit  definitions that
953              cause endless loops, it lists the units as they are checked.  If
954              'units' hangs, then the last unit to be printed has a bad  defi‐
955              nition.   Only  definitions  active  in  the  current locale are
956              checked.
957
958       -o format, --output-format format
959              Use the specified format for numeric output;  the  format  is  a
960              subset  of  that for the printf function in the ANSI C standard.
961              Only a numeric format ('E' or 'e' for scientific  notation,  'f'
962              for  fixed-point decimal, or 'G' or 'g' to specify the number of
963              significant figures) is allowed.  The default format is  '%.8g';
964              for  greater  precision,  you  could  specify  '-o  %.15g'.  See
965              Numeric Output Format and the  documentation  for  printf()  for
966              more detailed descriptions of the format specification.
967
968       -e, --exponential
969              Set  the  numeric output format to exponential (i.e., scientific
970              notation), like that used in the Unix 'units' program.
971
972       -f filename, --file filename
973              Instruct 'units' to load the units  file  'filename'.   You  can
974              specify  up to 25 units files on the command line.  When you use
975              this option, 'units' will load only the files you  list  on  the
976              command  line;  it  will not load the standard file or your per‐
977              sonal units file unless you explicitly list them.   If  filename
978              is  the  empty string ('-f ""'), the default units file (or that
979              specified by 'UNITSFILE') will be loaded in addition to any oth‐
980              ers specified with '-f'.
981
982       -h, --help
983              Print out a summary of the options for 'units'.
984
985       -m, --minus
986              Causes '-' to be interpreted as a subtraction operator.  This is
987              the default behavior.
988
989       -p, --product
990              Causes '-' to be interpreted as a multiplication  operator  when
991              it has two operands.  It will act as a negation operator when it
992              has only one operand: '(-3)'.  By default '-' is  treated  as  a
993              subtraction operator.
994
995       --oldstar
996              Causes  '*'  to  have  the old-style precedence, higher than the
997              precedence of division so that '1/2*3' will equal '1/6'.
998
999       --newstar
1000              Forces '*' to have the new (default) precedence that follows the
1001              usual rules of algebra: the precedence of '*' is the same as the
1002              precedence of '/', so that '1/2*3' will equal '3/2'.
1003
1004       --compact
1005              Give compact output featuring only the conversion factor.   This
1006              turns off the '--verbose' option.
1007
1008       -q, --quiet, --silent
1009              Suppress prompting of the user for units and the display of sta‐
1010              tistics about the number of units loaded.
1011
1012       -n, --nolists
1013              Disable conversion to unit lists.
1014
1015       -r, --round
1016              When converting to a combination of units given by a unit  list,
1017              round  the  value  of  the  last unit in the list to the nearest
1018              integer.
1019
1020       -S, --show-factor
1021              When converting to a combination of units specified in  a  list,
1022              always  show a non-unity factor before a unit that begins with a
1023              fraction with a unity denominator.  By default, if the unit in a
1024              list  begins with fraction of the form 1|x and its multiplier is
1025              an integer other than 1, the fraction is given as the product of
1026              the  multiplier and the numerator (e.g., '3|8 in' rather than '3
1027              * 1|8 in').  In some cases, this is  not  what  is  wanted;  for
1028              example,  the  results  for a cooking recipe might show '3 * 1|2
1029              cup' as '3|2 cup'.  With the '--show-factor'  option,  a  result
1030              equivalent to 1.5 cups will display as '3 * 1|2 cup' rather than
1031              '3|2 cup'.  A user-specified fractional unit  with  a  numerator
1032              other  than 1 is never overridden, however—if a unit list speci‐
1033              fies '3|4 cup;1|2 cup', a result equivalent to 1 1/2  cups  will
1034              always  be  shown  as  '2 * 3|4 cup' whether or not the '--show-
1035              factor' option is given.
1036
1037       -s, --strict
1038              Suppress conversion of units to  their  reciprocal  units.   For
1039              example,  'units' will normally convert hertz to seconds because
1040              these units are reciprocals of each other.   The  strict  option
1041              requires that units be strictly conformable to perform a conver‐
1042              sion, and will give an error if you attempt to convert hertz  to
1043              seconds.
1044
1045       -1, --one-line
1046              Give  only  one line of output (the forward conversion).  Do not
1047              print the reverse conversion.  If  a  reciprocal  conversion  is
1048              performed then 'units' will still print the ``reciprocal conver‐
1049              sion'' line.
1050
1051       -t, --terse
1052              Give terse output when converting units.   This  option  can  be
1053              used  when calling 'units' from another program so that the out‐
1054              put is easy to parse.  This option has the  combined  effect  of
1055              these options: '--strict' '--quiet' '--one-line' '--compact'.
1056
1057       -v, --verbose
1058              Give  slightly  more verbose output when converting units.  When
1059              combined with the '-c' option this  gives  the  same  effect  as
1060              '--check-verbose'.
1061
1062       -V, --version
1063              Print  program  version  number,  tell  whether  the  'readline'
1064              library has been included, and give the location of the  default
1065              units data file.
1066
1067       -l locale, --locale locale
1068              Force  a specified locale such as 'en_GB' to get British defini‐
1069              tions by default.  This overrides  the  locale  determined  from
1070              system  settings  or  environment  variables.   See Locale for a
1071              description of locale format.
1072

ADDING YOUR OWN DEFINITIONS

1074   Units Data Files
1075       The units and prefixes that 'units' can  convert  are  defined  in  the
1076       units   data   file,   typically  '/usr/share/units/definitions.units'.
1077       Although you can extend or modify this data file if you have  appropri‐
1078       ate  user privileges, it's usually better to put extensions in separate
1079       files so that  the  definitions  will  be  preserved  when  you  update
1080       'units'.
1081
1082       You  can  include additional data files in the units database using the
1083       '!include' command in the standard units data file. For example
1084
1085          !include    /usr/local/share/units/local.units
1086
1087       might be appropriate for a site-wide supplemental data file.  The loca‐
1088       tion  of  the  '!include'  statement in the standard units data file is
1089       important; later definitions replace earlier ones, so  any  definitions
1090       in  an  included  file  will override definitions before the '!include'
1091       statement in the standard units data file.  With normal invocation,  no
1092       warning  is given about redefinitions; to ensure that you don't have an
1093       unintended redefinition, run 'units -c' after  making  changes  to  any
1094       units data file.
1095
1096       If  you  want to add your own units in addition to or in place of stan‐
1097       dard or site-wide supplemental units data files, you can  include  them
1098       in the '.units' file in your home directory.  If this file exists it is
1099       read after the standard units data file, so  that  any  definitions  in
1100       this  file  will  replace definitions of the same units in the standard
1101       data file or in files included from the standard data file.  This  file
1102       will  not be read if any units files are specified on the command line.
1103       (Under Windows the personal units file is named 'unitdef.units'.)
1104
1105       The 'units' program first tries to determine your home  directory  from
1106       the 'HOME' environment variable.  On systems running Microsoft Windows,
1107       if 'HOME' does not exist, 'units' attempts to find your home  directory
1108       from  'HOMEDRIVE'  and 'HOMEPATH'.  Running 'units -V' will display the
1109       location and name of your personal units file.
1110
1111       You can specify an arbitrary file as your personal units data file with
1112       the  'MYUNITSFILE'  environment  variable; if this variable exists, its
1113       value is used without searching your home directory.
1114
1115   Defining New Units and Prefixes
1116       A unit is specified on a single line by giving its name and an  equiva‐
1117       lence.   Comments start with a '#' character, which can appear anywhere
1118       in a line.  The backslash character ('\') acts as a continuation  char‐
1119       acter if it appears as the last character on a line, making it possible
1120       to spread definitions out over several lines if desired.  A file can be
1121       included  by giving the command '!include' followed by the file's name.
1122       The '!'  must be the first character on the line.   The  file  will  be
1123       sought  in the same directory as the parent file unless you give a full
1124       path.  The name of the file to be included cannot contain  the  comment
1125       character '#'.
1126
1127       Unit  names  must  not contain any of the operator characters '+', '-',
1128       '*', '/', '|', '^', ';', '~', the comment character '#',  or  parenthe‐
1129       ses.   They cannot begin or end with an underscore ('_'), a comma (',')
1130       or a decimal point ('.').  Names cannot begin with a digit,  and  if  a
1131       name  ends  in a digit other than zero, the digit must be preceded by a
1132       string beginning with an underscore, and afterwards consisting only  of
1133       digits, decimal points, or commas.  For example, 'foo_2', 'foo_2,1', or
1134       'foo_3.14' would be  valid  names  but  'foo2'  or  'foo_a2'  would  be
1135       invalid.  You could define nitrous oxide as
1136
1137          N2O     nitrogen 2  + oxygen
1138
1139       but would need to define nitrogen dioxide as
1140
1141          NO_2    nitrogen + oxygen 2
1142
1143       Be careful to define new units in terms of old ones so that a reduction
1144       leads to the primitive units, which are marked  with  '!'   characters.
1145       Dimensionless  units are indicated by using the string '!dimensionless'
1146       for the unit definition.
1147
1148       When adding new units, be sure to use the '-c' option to check that the
1149       new  units  reduce properly.  If you create a loop in the units defini‐
1150       tions, then 'units' will hang when invoked with the '-c'  option.   You
1151       will  need  to  use the '--check-verbose' option, which prints out each
1152       unit as it is checked.  The program will still hang, but the last  unit
1153       printed will be the unit that caused the infinite loop.
1154
1155       If  you  define  any units that contain '+' characters, carefully check
1156       them because the '-c' option will not catch non-conformable  sums.   Be
1157       careful with the '-' operator as well.  When used as a binary operator,
1158       the '-' character can perform addition or multiplication  depending  on
1159       the  options used to invoke 'units'.  To ensure consistent behavior use
1160       '-' only as a unary negation operator when writing  units  definitions.
1161       To  multiply two units leave a space or use the '*' operator with care,
1162       recalling that it has two possible precedence values  and  may  require
1163       parentheses  to  ensure consistent behavior.  To compute the difference
1164       of 'foo' and 'bar' write 'foo+(-bar)' or even 'foo+-bar'.
1165
1166       Here is an example of a short data file that defines some basic units:
1167
1168          m       !               # The meter is a primitive unit
1169          sec     !               # The second is a primitive unit
1170          rad     !dimensionless  # A dimensionless primitive unit
1171          micro-  1e-6            # Define a prefix
1172          minute  60 sec          # A minute is 60 seconds
1173          hour    60 min          # An hour is 60 minutes
1174          inch    0.0254 m        # Inch defined in terms of meters
1175          ft      12 inches       # The foot defined in terms of inches
1176          mile    5280 ft         # And the mile
1177
1178       A unit that ends with a '-' character is a prefix.  If a prefix defini‐
1179       tion  contains any '/' characters, be sure they are protected by paren‐
1180       theses.  If you define 'half- 1/2' then 'halfmeter' would be equivalent
1181       to '1 / (2 meter)'.
1182
1183   Defining Nonlinear Units
1184       Some  unit conversions of interest are nonlinear; for example, tempera‐
1185       ture conversions between the Fahrenheit and Celsius  scales  cannot  be
1186       done by simply multiplying by conversion factors.
1187
1188       When  you  give a linear unit definition such as 'inch 2.54 cm' you are
1189       providing information that 'units' uses to  convert  values  in  inches
1190       into  primitive units of meters.  For nonlinear units, you give a func‐
1191       tional definition that provides the same information.
1192
1193       Nonlinear units are represented using a  functional  notation.   It  is
1194       best  to  regard  this  notation not as a function call but as a way of
1195       adding units to a number, much the same way that writing a linear  unit
1196       name  after  a number adds units to that number.  Internally, nonlinear
1197       units are defined by a pair of functions that convert to and from  lin‐
1198       ear units in the data file, so that an eventual conversion to primitive
1199       units is possible.
1200
1201       Here is an example nonlinear unit definition:
1202
1203          tempF(x) units=[1;K] (x+(-32)) degF + stdtemp ; \
1204                               (tempF+(-stdtemp))/degF + 32
1205
1206       A nonlinear unit definition comprises a unit name,  a  dummy  parameter
1207       name,  two  functions, and two corresponding units.  The functions tell
1208       'units' how to convert to and from the new unit.  In order  to  produce
1209       valid  results,  the arguments of these functions need to have the cor‐
1210       rect dimensions.  To facilitate  error  checking,  you  may  optionally
1211       indicate units for these arguments.
1212
1213       The  definition begins with the unit name followed immediately (with no
1214       spaces) by a '(' character.  In parentheses is the name of the  parame‐
1215       ter.   Next  is  an optional specification of the units required by the
1216       functions in this definition.  In the example above, the 'tempF'  func‐
1217       tion  requires an input argument conformable with '1'.  For normal non‐
1218       linear units definitions the forward function will always take a dimen‐
1219       sionless  argument.   The  inverse  function requires an input argument
1220       conformable with 'K'.  In general the inverse function will need  units
1221       that  match  the quantity measured by your nonlinear unit.  The purpose
1222       of the expression in brackets to enable 'units' to perform error check‐
1223       ing on function arguments, and also to assign units to range and domain
1224       specifications, which are described later.
1225
1226       Next the function  definitions  appear.   In  the  example  above,  the
1227       'tempF' function is defined by
1228
1229          tempF(x) = (x+(-32)) degF + stdtemp
1230
1231       This  gives  a  rule  for converting 'x' in the units 'tempF' to linear
1232       units of absolute temperature, which makes it possible to convert  from
1233       tempF to other units.
1234
1235       In  order  to  make conversions to Fahrenheit possible, you must give a
1236       rule for the inverse conversions. The inverse will  be  'x(tempF)'  and
1237       its  definition  appears  after  a  ';' character.  In our example, the
1238       inverse is
1239
1240          x(tempF) = (tempF+(-stdtemp))/degF + 32
1241
1242       This inverse definition takes an absolute temperature as  its  argument
1243       and  converts  it  to  the  Fahrenheit temperature.  The inverse can be
1244       omitted by leaving out the ';' character, but then conversions  to  the
1245       unit  will be impossible.  If the inverse is omitted then the '--check'
1246       option will display a warning.  It is up to you to calculate and  enter
1247       the  correct  inverse  function  to  obtain  proper  conversions.   The
1248       '--check' option tests the inverse at one point and prints an error  if
1249       it is not valid there, but this is not a guarantee that your inverse is
1250       correct.
1251
1252       If you wish to make synonyms for nonlinear units,  you  still  need  to
1253       define  both  the forward and inverse functions.  Inverse functions can
1254       be obtained using the '~' operator.  So to create a synonym for 'tempF'
1255       you could write
1256
1257          fahrenheit(x) units=[1;K] tempF(x); ~tempF(fahrenheit)
1258
1259       You  may  define  a function whose range and domain do not cover all of
1260       the real numbers.  In this case 'units' can handle errors better if you
1261       specify  an  appropriate  range  and domain.  You specify the range and
1262       domain as shown below.
1263
1264          baume(d) units=[1;g/cm^3] domain=[0,130.5] range=[1,10] \
1265                   (145/(145-d)) g/cm^3 ; (baume+-g/cm^3) 145 / baume
1266
1267       In this example the domain is specified after the  'domain='  with  the
1268       endpoints  given  in brackets.  One of the end points can be omitted to
1269       get an interval that goes to infinity.  So the range could be specified
1270       as  nonnegative by writing 'range=[0,]'.  Both the range and domain are
1271       optional and can appear independently and in any order along  with  the
1272       'units' specification.  The values in the range and domain are attached
1273       to the units given in the 'units' specification.  If you don't  specify
1274       the  units then the parameter inputs are reduced to primitive units for
1275       the numeric comparison to the values you give in the range  or  domain.
1276       In  this  case you should only use 'range' or 'domain' if the endpoints
1277       are zero and infinity.
1278
1279       Specifying the range and domain allows 'units' to perform better  error
1280       checking and give more helpful error messages when you invoke nonlinear
1281       units conversions outside of their bounds.  It also  enables  the  '-c'
1282       option to find a point in the domain to use for its point check of your
1283       inverse definition.
1284
1285       You may occasionally wish to define a function that operates on  units.
1286       This  can  be done using a nonlinear unit definition.  For example, the
1287       definition below provides conversion between radius and the area  of  a
1288       circle.   This  definition  requires  a length as input and produces an
1289       area as output, as indicated by the 'units=' specification.  Specifying
1290       the  range  as  the  nonnegative numbers can prevent cryptic error mes‐
1291       sages.
1292
1293          circlearea(r) units=[m;m^2] range=[0,]   pi r^2 ; sqrt(circlearea/pi)
1294
1295       Sometimes you may be interested in a piecewise linear unit such as many
1296       wire  gauges.  Piecewise linear units can be defined by specifying con‐
1297       versions to linear units on a list  of  points.   Conversion  at  other
1298       points  will  be done by linear interpolation.  A partial definition of
1299       zinc gauge is
1300
1301          zincgauge[in] 1 0.002, 10 0.02, 15 0.04, 19 0.06, 23 0.1
1302
1303       In this example, 'zincgauge' is the name of the piecewise linear  unit.
1304       The  definition of such a unit is indicated by the embedded '[' charac‐
1305       ter.  After the bracket, you should indicate the units to  be  attached
1306       to the numbers in the table.  No spaces can appear before the ']' char‐
1307       acter, so a definition like 'foo[kg meters]' is illegal; instead  write
1308       'foo[kg*meters]'.   The  definition  of  the unit consists of a list of
1309       pairs optionally separated by commas.  This list defines a function for
1310       converting  from  the piecewise linear unit to linear units.  The first
1311       item in each pair is the function argument;  the  second  item  is  the
1312       value  of  the  function  at  that  argument (in the units specified in
1313       brackets).  In this example, we define 'zincgauge' at five points.  For
1314       example,  we  set 'zincgauge(1)' equal to '0.002 in'.  Definitions like
1315       this may be  more readable  if written using   continuation  characters
1316       as
1317
1318          zincgauge[in] \
1319               1 0.002  \
1320              10 0.02   \
1321              15 0.04   \
1322              19 0.06   \
1323              23 0.1
1324
1325       With  the  preceding  definition,  the following conversion can be per‐
1326       formed:
1327
1328          You have: zincgauge(10)
1329          You want: in
1330              * 0.02
1331              / 50
1332          You have: .01 inch
1333          You want: zincgauge
1334              5
1335
1336       If you define a piecewise linear unit that is not  strictly  monotonic,
1337       then the inverse will not be well defined.  If the inverse is requested
1338       for such a  unit,  'units'  will  return  the  smallest  inverse.   The
1339       '--check' option will print a warning if a non-monotonic piecewise lin‐
1340       ear unit is encountered.
1341
1342   Defining Unit List Aliases
1343       Unit list  aliases  are  treated  differently  from  unit  definitions,
1344       because  they  are a data entry shorthand rather than a true definition
1345       for a new unit.  A unit list alias definition begins  with  '!unitlist'
1346       and  includes  the  alias and the definition;  for example, the aliases
1347       included in the standard units data file are
1348
1349          !unitlist   hms     hr;min;sec
1350          !unitlist   time    year;day;hr;min;sec
1351          !unitlist   dms     deg;arcmin;arcsec
1352          !unitlist   ftin    ft;in;1|8 in
1353          !unitlist   usvol   cup;3|4 cup;2|3 cup;1|2 cup;1|3 cup;1|4 cup;\
1354                              tbsp;tsp;1|2 tsp;1|4 tsp;1|8 tsp
1355
1356       Unit list aliases are only for  unit  lists,  so  the  definition  must
1357       include  a  ';'.  Unit list aliases can never be combined with units or
1358       other unit list aliases, so the definition of 'time' shown above  could
1359       not  have  been  shortened to 'year;day;hms'.  As usual, be sure to run
1360       'units --check' to ensure that the units listed in  unit  list  aliases
1361       are conformable.
1362

NUMERIC OUTPUT FORMAT

1364       By  default, results of conversions are shown to eight significant fig‐
1365       ures; this can be  changed  with  the  '--exponential'  and  '--output-
1366       format'  options.   The former sets an exponential format (i.e., scien‐
1367       tific notation) like that used in the original  Unix  'units'  program;
1368       the latter allows the format to be given as that of the printf function
1369       in the ANSI C standard.
1370
1371       The format recognized with the '--output-format' option is a subset  of
1372       that   for   printf().   Only  a  floating-point  format  of  the  form
1373       '%'[flag][width]['.'precision]type is allowed: it must begin with  '%',
1374       and  must end with a floating-point type specifier ('E' or 'e' for sci‐
1375       entific notation, 'f' for fixed-point decimal, or 'G' or 'g' to specify
1376       the  number  of  significant  figures).   The  format specification may
1377       include one optional flag ('+', '-', '#', or a space), followed  by  an
1378       optional  value  for the minimum field width, and an optional precision
1379       specification that begins with a period (e.g., '.6').  In  addition  to
1380       the  digits,  the field width includes the decimal point, the exponent,
1381       and the sign if any of these are shown.  A width specification is typi‐
1382       cally used with fixed-point decimal to have columns of numbers align at
1383       the decimal point; it normally is not useful with 'units'.   Non-float‐
1384       ing-point type specifiers make no sense for 'units', and are forbidden.
1385
1386       The  default format is '%.8g'; for greater precision, you could specify
1387       '-o %.15g'.  The 'G' and 'g' formats use  exponential  format  whenever
1388       the  exponent  would be less than -5, so the value 0.000013 displays as
1389       '1.3e-005'.  If you prefer fixed-point display, you might  specify  '-o
1390       %.8f';  however,  very  small  numbers may display very few significant
1391       figures, and for very small numbers, may show nothing but zeros.
1392
1393       See the documentation for printf() for more  detailed  descriptions  of
1394       the format specification.
1395

LOCALIZATION

1397       Some units have different values in different locations.  The localiza‐
1398       tion feature accommodates this by allowing a units data file to specify
1399       definitions that depend on the user's locale.
1400
1401   Locale
1402       A  locale is a subset of a user's environment that indicates the user's
1403       language and country, and some attendant preferences, such as the  for‐
1404       matting of dates.  The 'units' program attempts to determine the locale
1405       from the POSIX setlocale function; if  this  cannot  be  done,  'units'
1406       examines  the  environment  variables  'LC_CTYPE' and 'LANG'.  On POSIX
1407       systems, a locale is of the form language'_'country, where language  is
1408       the  two-character code from ISO 639-1 and country is the two-character
1409       code from ISO 3166-1; language is lower case and country is upper case.
1410       For example, the POSIX locale for the United Kingdom is 'en_GB'.
1411
1412       On systems running Microsoft Windows, the value returned by setlocale()
1413       is different from that on POSIX systems; 'units' attempts  to  map  the
1414       Windows  value  to  a  POSIX  value  by  means  of  a table in the file
1415       'locale.map' in the same directory, typically '/usr/local/share/units',
1416       as  the  default  units data files.  The file includes entries for many
1417       combinations of language and country, and can be  extended  to  include
1418       other  combinations.  The 'locale.map' comprises two tab-separated col‐
1419       umns; each entry is of the form
1420
1421          Windows-locale   POSIX-locale
1422
1423       where POSIX-locale is as described above, and Windows-locale  typically
1424       spells  out  both the language and country.  For example, the entry for
1425       the United States is
1426
1427          English_United States   en_US
1428
1429       You can force 'units' to run in a desired  locale  by  using  the  '-l'
1430       option.
1431
1432       In order to create unit definitions for a particular locale you begin a
1433       block of definitions in a unit datafile with '!locale'  followed  by  a
1434       locale  name.   The  '!'  must be the first character on the line.  The
1435       'units' program reads the following definitions  only  if  the  current
1436       locale   matches.    You   end   the  block  of  localized  units  with
1437       '!endlocale'.  Here is an example, which defines the British gallon.
1438
1439          !locale en_GB
1440          gallon       4.54609 liter
1441          !endlocale
1442
1443   Additional Localization
1444       Sometimes the locale isn't sufficient to  determine  unit  preferences.
1445       There  could  be regional preferences, or a company could have specific
1446       preferences.  Though probably uncommon, such  differences  could  arise
1447       with  the choice of English customary units outside of English-speaking
1448       countries.  To address this, 'units' allows specifying definitions that
1449       depend on environment variable settings.  The environment variables can
1450       be controled based on the current locale, or the user can set  them  to
1451       force a particular group of definitions.
1452
1453       A  conditional  block  of  definitions in a units data file begins with
1454       either '!var' or '!varnot' following by an  environment  variable  name
1455       and  then  a  space  separated  list  of values.  The leading '!'  must
1456       appear in the first column of a units data file,  and  the  conditional
1457       block is terminated by '!endvar'.  Definitions in blocks beginning with
1458       '!var' are executed only if the environment variable is  exactly  equal
1459       to  one  of  the  listed  values.  Definitions in blocks beginning with
1460       '!varnot' are executed only if the environment variable does not  equal
1461       any of the list values.
1462
1463       The  inch  has  long been a customary measure of length in many places.
1464       The word comes from the latin uncia meaning ``one twelfth,''  referring
1465       to  its  relationship with the foot.  By the 20th century, the inch was
1466       officially defined in English-speaking countries relative to the  yard,
1467       but  until  1959, the yard differed slightly among those countries.  In
1468       France the customary inch, which was displaced in 1799  by  the  meter,
1469       had a different length based on a french foot.  These customary defini‐
1470       tions could be accomodated as follows:
1471
1472          !var INCH_UNIT usa
1473          yard          3600|3937 m
1474          !endvar
1475          !var INCH_UNIT canada
1476          yard          0.9144 meter
1477          !endvar
1478          !var INCH_UNIT uk
1479          yard          0.91439841 meter
1480          !endvar
1481          !var INCH_UNIT canada uk usa
1482          foot          1|3 yard
1483          inch          1|12 foot
1484          !endvar
1485          !var INCH_UNIT france
1486          foot          144|443.296 m
1487          inch          1|12 foot
1488          line          1|12 inch
1489          !endvar
1490          !varnot INCH_UNIT usa uk france canada
1491          !message Unknown value for INCH_UNIT
1492          !endvar
1493
1494       When 'units' reads the above definitions it will check the  environment
1495       variable  'INCH_UNIT' and load only the definitions for the appropriate
1496       section.  If 'INCH_UNIT' is unset or is not set to one of the four val‐
1497       ues  listed  then  'units'  will run the last block.  In this case that
1498       block uses the '!message' command to display a warning message.  Alter‐
1499       natively that block could set default values.
1500
1501       In  order to create default values that are overridden by user settings
1502       the data file can use the '!set' command,  which  sets  an  environment
1503       variable  only  if  it is not already set;  these settings are only for
1504       the current 'units' invocation and do not persist.  So if  the  example
1505       above  were  preceded  by  '!set INCH_UNIT france' then this would make
1506       'france' the default value for 'INCH_UNIT'.  If the user  had  set  the
1507       variable in the environment before invoking 'units', then 'units' would
1508       use the user's value.
1509
1510       To link these settings to the user's locale you combine the '!set' com‐
1511       mand  with  the  '!locale' command.  If you wanted to combine the above
1512       example with suitable locales you could do by preceding the above defi‐
1513       nition with the following:
1514
1515          !locale en_US
1516          !set INCH_UNIT usa
1517          !endlocale
1518          !locale en_GB
1519          !set INCH_UNIT uk
1520          !endlocale
1521          !locale en_CA
1522          !set INCH_UNIT canada
1523          !endlocale
1524          !locale fr_FR
1525          !set INCH_UNIT france
1526          !endlocale
1527          !set INCH_UNIT france
1528
1529       These  definitions  set the overall default for 'INCH_UNIT' to 'france'
1530       and set default values for four  locales  appropriately.   The  overall
1531       default setting comes last so that it only applies when 'INCH_UNIT' was
1532       not set by one of the other commands or by the user.
1533
1534       If the variable given after  '!var'  or  '!varnot'  is  undefined  then
1535       'units'  prints  an  error  message  and  ignores  the definitions that
1536       follow.  Use '!set' to create defaults to prevent this  situation  from
1537       arising.   The  '-c' option only checks the definitions that are active
1538       for the current environment and locale, so when adding new  definitions
1539       take  care  to  check that all cases give rise to a well defined set of
1540       definitions.
1541

ENVIRONMENT VARIABLES

1543       The 'units' program uses the following environment variables:
1544
1545       HOME   Specifies the location of your home directory;  it  is  used  by
1546              'units' to find a personal units data file '.units'.  On systems
1547              running Microsoft Windows, 'units' tries to determine your  home
1548              directory  from the 'HOMEDRIVE' and 'HOMEPATH' environment vari‐
1549              ables if 'HOME' does not exist.
1550
1551       LC_CTYPE, LANG
1552              Checked to determine the locale if 'units' cannot obtain it from
1553              the  operating system.  Sections of the standard units data file
1554              are specific to certain locales.
1555
1556       MYUNITSFILE
1557              Specifies your personal  units  data  file.   If  this  variable
1558              exists,  'units'  uses its value rather than searching your home
1559              directory for '.units'.  The personal units  file  will  not  be
1560              loaded if any data files are given using the '-f' option.
1561
1562       PAGER  Specifies  the pager to use for help and for displaying the con‐
1563              formable units.  The help function browses  the  units  database
1564              and calls the pager using the '+n'n syntax for specifying a line
1565              number.  The default pager is 'more'; 'PAGER'  can  be  used  to
1566              specify alternatives such as 'less', 'pg', 'emacs', or 'vi'.
1567
1568       UNITS_ENGLISH
1569              Set  to  either  'US' or 'GB' to choose United States or British
1570              volume definitions, overriding the default from your locale.
1571
1572       UNITSFILE
1573              Specifies the units data file to use (instead of  the  default).
1574              You  can  only specify a single units data file using this envi‐
1575              ronment variable.  If units data files are given using the  '-f'
1576              option,  the file specified by 'UNITSFILE' will be not be loaded
1577              unless  the  '-f'  option  is  given  with  the   empty   string
1578              ('units -f ""').
1579

UNICODE SUPPORT

1581       The  standard  units  data  file  is written in Unicode using the UTF-8
1582       encoding.  Portions of the file that are not  plain  ASCII  begin  with
1583       '!utf8' and end with '!endutf8'.  As usual, the '!'  must appear as the
1584       first character on the line.  If a line of a data  file  contains  byte
1585       sequences  that  are  invalid  UTF-8 or non-printing UTF-8 then 'units'
1586       ignores the entire line.
1587
1588       When 'units' runs it checks the locale to determine the character  set.
1589       If  UTF-8  is  listed, then 'units' reads the utf8 definitions.  If any
1590       other character set is in use, then 'units' works in plain ASCII  with‐
1591       out support for extended characters.
1592

READLINE SUPPORT

1594       If  the  'readline'  package has been compiled in, then when 'units' is
1595       used interactively, numerous command line editing features  are  avail‐
1596       able.   To check if your version of 'units' includes 'readline', invoke
1597       the program with the '--version' option.
1598
1599       For complete information about 'readline',  consult  the  documentation
1600       for  the  'readline'  package.  Without any configuration, 'units' will
1601       allow editing in the style of emacs.  Of particular  use  with  'units'
1602       are the completion commands.
1603
1604       If  you  type  a  few characters and then hit ESC followed by '?'  then
1605       'units' will display a list of all the units that start with the  char‐
1606       acters typed.  For example, if you type 'metr' and then request comple‐
1607       tion, you will see something like this:
1608
1609          You have: metr
1610          metre             metriccup         metrichorsepower  metrictenth
1611          metretes          metricfifth       metricounce       metricton
1612          metriccarat       metricgrain       metricquart       metricyarncount
1613          You have: metr
1614
1615       If there is a unique way to complete a unitname, you can  hit  the  TAB
1616       key  and  'units'  will  provide the rest of the unit name.  If 'units'
1617       beeps, it means that there is no unique completion.  Pressing  the  TAB
1618       key a second time will print the list of all completions.
1619

UPDATING CURRENCY EXCHANGE RATES

1621       The  units program includes currency exchange rates and prices for some
1622       precious metals in the database.  Of course, these values  change  over
1623       time, sometimes very rapidly, and 'units' cannot provide real time val‐
1624       ues.  To update the exchange rates run the 'units_cur', which  rewrites
1625       the     files     containing     the    currency    rates,    typically
1626       '/usr/local/share/units/currency.units'.  This program must be run with
1627       suitable  permissions  to  write  the  file.  To keep the rates updated
1628       automatically, it could be run by a cron job on a Unix-like system,  or
1629       a  similar scheduling program on a different system.  Currency exchange
1630       rates are taken from Time Genie (http://www.timegenie.com) and precious
1631       metals  pricing  from  Packetizer  (www.packetizer.com).   These  sites
1632       update once per day, so there is  no  benefit  in  running  the  update
1633       script  more often than daily.  You can run 'units_cur' with a filename
1634       specified on the command line and it will write the data to that  file.
1635       If you give '-' for the file it will write to standard output.
1636

DATABASE COMMAND SYNTAX

1638       unit definition
1639              Define a regular unit.
1640
1641       prefix- definition
1642              Define a prefix.
1643
1644       funcname(var)  units=[in-units,out-units]  domain=[x1,x2] range=[y1,y2]
1645       definition(var) ; inverse(funcname)
1646              Define a nonlinear unit or unit function.   The  three  optional
1647              keywords  'units=',  'range='  and  'domain='  can appear in any
1648              order.  The definition of the inverse is optional.
1649
1650       tabname[out-units] pair-list
1651              Define a piecewise linear unit.  The pair list gives the  points
1652              on the table listed in ascending order.
1653
1654       !endlocale
1655              End a block of definitions beginning with '!locale'
1656
1657       !endutf8
1658              End a block of definitions begun with '!utf8'
1659
1660       !endvar
1661              End a block of definitions begun with '!var' or '!varnot'
1662
1663       !include file
1664              Include the specified file.
1665
1666       !locale value
1667              Load  the  following  definitions  only  of the locale is set to
1668              value.
1669
1670       !message text
1671              Display text when the database is read unless the  quiet  option
1672              ('-q') is enabled.
1673
1674       !set variable value
1675              Sets  the environment variable, variable, to the specified value
1676              only if it is not already set.
1677
1678       !unitlist alias definition
1679              Define a unit list alias.
1680
1681       !utf8  Load the following definitions only if 'units' is  running  with
1682              UTF-8 enabled.
1683
1684       !var variable value-list
1685              Load the following definitions only if the environment variable,
1686              variable is set to one of the values listed on the  space  sepa‐
1687              rated  value list. If variable is not set then 'units' prints an
1688              error message and ignores the following definitions.
1689
1690       !varnot variable value-list
1691              Load the following definitions only if the environment variable,
1692              variable  is  not  set  to one of the values listed on the space
1693              separated value list.  If  variable  is  not  set  then  'units'
1694              prints an error message and ignores the following definitions.
1695

GNU FREE DOCUMENTATION LICENSE

FILES

1698       /usr/share/units/definitions.units — the standard units data file
1699

AUTHO

1701                                 27 April 2012                        UNITS(1)
Impressum