1UNITS(1)                    General Commands Manual                   UNITS(1)
2
3
4

NAME

6       units — unit conversion and calculation program
7

SYNOPSIS

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

DESCRIPTION

12       The 'units' program converts quantities expressed in various systems of
13       measurement to their equivalents in other systems of measurement.  Like
14       many  similar  programs, it can handle multiplicative scale changes. It
15       can also handle nonlinear conversions such as  Fahrenheit  to  Celsius;
16       see  Temperature Conversions.  The program can also perform conversions
17       from and to sums of units, such as converting between meters  and  feet
18       plus inches.
19
20       Basic operation is simple: you enter the units that you want to convert
21       from and the units that you want to convert to.  You can use  the  pro‐
22       gram  interactively  with  prompts,  or you can use it from the command
23       line.
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; for an illustration,  see  Com‐
32       plicated Unit Expressions.
33
34       The units are defined in an external data file.  You can use the exten‐
35       sive data file that comes with this program, or you  can  provide  your
36       own  data file to suit your needs.  You can also use your own data file
37       to supplement the standard data file.
38
39       You can change the default behavior of  'units'  with  various  options
40       given  on the command line. See Invoking Units for a description of the
41       available options.
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 www.timegenie.com on 2014-03-05
48          2860 units, 109 prefixes, 85 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 tab
57       will complete unit names. See Readline  Support  for  more  information
58       about  'readline'.   To  quit  the  program under Unix, press Ctrl-C or
59       Ctrl-D. Under Windows, press Ctrl-C or Ctrl-Z; with the latter, you may
60       also need to press Enter.
61
62       The  result  will  be displayed in two ways.  The first line of output,
63       which is marked with a '*' to indicate multiplication, gives the result
64       of the conversion you have asked for.  The second line of output, which
65       is marked with a '/' to indicate division, gives  the  inverse  of  the
66       conversion  factor.   If  you  convert  10 meters to feet, 'units' will
67       print
68
69              * 32.808399
70              / 0.03048
71
72       which tells you that 10 meters equals about 32.8 feet.  The second num‐
73       ber  gives  the conversion in the opposite direction.  In this case, it
74       tells you that 1 foot is equal  to  about  0.03  dekameters  since  the
75       dekameter is 10 meters.  It also tells you that 1/32.8 is about 0.03.
76
77       The  'units'  program prints the inverse because sometimes it is a more
78       convenient number.  In the example  above,  for  example,  the  inverse
79       value  is  an  exact  conversion: a foot is exactly 0.03048 dekameters.
80       But the number given the other direction is inexact.
81
82       If you convert grains to pounds, you will see the following:
83
84          You have: grains
85          You want: pounds
86                  * 0.00014285714
87                  / 7000
88
89          From the second line of the output you can immediately  see  that  a
90       grain  is equal to a seven thousandth of a pound.  This is not so obvi‐
91       ous from the first line of the output.  If you find  the output  format
92       confusing, try using the '--verbose' option:
93
94          You have: grain
95          You want: aeginamina
96                  grain = 0.00010416667 aeginamina
97                  grain = (1 / 9600) aeginamina
98
99       If  you  request  a  conversion  between  units that measure reciprocal
100       dimensions, then 'units' will display the conversion  results  with  an
101       extra note indicating that reciprocal conversion has been done:
102
103          You have: 6 ohms
104          You want: siemens
105                  reciprocal conversion
106                  * 0.16666667
107                  / 6
108
109       Reciprocal conversion can be suppressed by using the '--strict' option.
110       As usual, use the '--verbose' option to get more comprehensible output:
111
112          You have: tex
113          You want: typp
114                  reciprocal conversion
115                  1 / tex = 496.05465 typp
116                  1 / tex = (1 / 0.0020159069) typp
117
118          You have: 20 mph
119          You want: sec/mile
120                  reciprocal conversion
121                  1 / 20 mph = 180 sec/mile
122                  1 / 20 mph = (1 / 0.0055555556) sec/mile
123
124       If you enter incompatible unit types, the 'units' program will print  a
125       message  indicating that the units are not conformable and it will dis‐
126       play the reduced form for each unit:
127
128          You have: ergs/hour
129          You want: fathoms kg^2 / day
130          conformability error
131                  2.7777778e-11 kg m^2 / sec^3
132                  2.1166667e-05 kg^2 m / sec
133
134       If you only want to find the reduced form or definition of a unit, sim‐
135       ply press Enter at the 'You want:' prompt.  Here is an example:
136
137          You have: jansky
138          You want:
139                  Definition: fluxunit = 1e-26 W/m^2 Hz = 1e-26 kg / s^2
140
141       The  output  from  'units'  indicates  that the jansky is defined to be
142       equal to a fluxunit which in turn is defined to be a  certain  combina‐
143       tion  of watts, meters, and hertz.  The fully reduced (and in this case
144       somewhat more cryptic) form appears on the far right.
145
146       Some named units are  treated  as  dimensionless  in  some  situations.
147       These  units  include  the  radian  and steradian.  These units will be
148       treated as equal to 1 in units conversions.  Power is equal  to  torque
149       times  angular  velocity.  This conversion can only be performed if the
150       radian is dimensionless.
151
152          You have: (14 ft lbf) (12 radians/sec)
153          You want: watts
154                  * 227.77742
155                  / 0.0043902509
156
157       It is also possible to compute roots and other  non-integer  powers  of
158       dimensionless  units;  this allows computations such as the altitude of
159       geosynchronous orbit:
160
161          You have: cuberoot(G earthmass / (circle/siderealday)^2) - earthradius
162          You want: miles
163                  * 22243.267
164                  / 4.4957425e-05
165
166       Named dimensionless units are not treated  as  dimensionless  in  other
167       contexts.    They   cannot   be  used  as  exponents  so  for  example,
168       'meter^radian' is forbidden.
169
170       If you want a list of options you can  type  '?'   at  the  'You want:'
171       prompt.   The  program will display a list of named units that are con‐
172       formable with the unit that  you  entered  at  the  'You have:'  prompt
173       above.  Conformable unit combinations will not appear on this list.
174
175       Typing  'help' at either prompt displays a short help message.  You can
176       also type 'help' followed by a unit name.  This will invoke a pager  on
177       the  units  data base at the point where that unit is defined.  You can
178       read the definition and comments that may give more details or histori‐
179       cal  information  about  the  unit.  (You can generally quit out of the
180       page by pressing 'q'.)
181
182       Typing 'search' text will display a list of  all  of  the  units  whose
183       names  contain  text as a substring along with their definitions.  This
184       may help in the case where you aren't sure of the right unit name.
185

USING UNITS NON-INTERACTIVELY

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

UNIT DEFINITIONS

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

UNIT EXPRESSIONS

331   Operators
332       You can enter more complicated units by combining units with operations
333       such as multiplication, division, powers,  addition,  subtraction,  and
334       parentheses  for grouping.  You can use the customary symbols for these
335       operators when 'units' is invoked with its default options.   Addition‐
336       ally,  'units' supports some extensions, including high priority multi‐
337       plication using a space, and a high priority numerical division  opera‐
338       tor ('|') that can simplify some expressions.
339
340       You  multiply units using a space or an asterisk ('*').  The next exam‐
341       ple shows both forms:
342
343          You have: arabicfoot * arabictradepound * force
344          You want: ft lbf
345                  * 0.7296
346                  / 1.370614
347
348       You can divide units using the slash ('/') or with 'per':
349
350          You have: furlongs per fortnight
351          You want: m/s
352                  * 0.00016630986
353                  / 6012.8727
354
355       You can use parentheses for grouping:
356
357          You have: (1/2) kg / (kg/meter)
358          You want: league
359                  * 0.00010356166
360                  / 9656.0833
361
362       White space surrounding operators is optional, so the previous  example
363       could  have  used  '(1/2)kg/(kg/meter)'.   As  a  consequence, however,
364       hyphenated spelled-out numbers  (e.g.,  'forty-two')  cannot  be  used;
365       'forty-two' is interpreted as '40 - 2'.
366
367       Multiplication  using  a  space  has  a higher precedence than division
368       using a slash and is evaluated left to right; in effect, the first  '/'
369       character  marks the beginning of the denominator of a unit expression.
370       This makes it simple to enter a quotient  with  several  terms  in  the
371       denominator:  'J / mol K'.   The  '*'  and  '/' operators have the same
372       precedence, and are evaluated left to right; if you multiply with  '*',
373       you   must  group  the  terms  in  the  denominator  with  parentheses:
374       'J / (mol * K)'.
375
376       The higher precedence of the space operator may not always be  advanta‐
377       geous.  For example, 'm/s s/day' is equivalent to 'm / s s day' and has
378       dimensions of length per time cubed.  Similarly, '1/2 meter' refers  to
379       a  unit  of reciprocal length equivalent to 0.5/meter, perhaps not what
380       you would intend if you entered that expression.  The get a half  meter
381       you  would need to use parentheses: '(1/2) meter'.  The '*' operator is
382       convenient for multiplying  a  sequence  of  quotients.   For  example,
383       'm/s * s/day'  is  equivalent  to  'm/day'.  Similarly, you could write
384       '1/2 * meter' to get half a meter.
385
386       The 'units' program supports another option  for  numerical  fractions:
387       you can indicate division of numbers with the vertical bar ('|'), so if
388       you wanted half a meter you could write '1|2 meter'.   You  cannot  use
389       the  vertical  bar  to  indicate division of non-numerical units (e.g.,
390       'm|s' results in an error message).
391
392       Powers of units can be specified using the '^' character, as  shown  in
393       the  following  example,  or  by simple concatenation of a unit and its
394       exponent: 'cm3' is equivalent to 'cm^3'; if the exponent is  more  than
395       one  digit,  the '^' is required.  You can also use '**' as an exponent
396       operator.
397
398          You have: cm^3
399          You want: gallons
400                  * 0.00026417205
401                  / 3785.4118
402
403       Concatenation only  works  with  a  single  unit  name:  if  you  write
404       '(m/s)2',  'units'  will  treat it as multiplication by 2.  When a unit
405       includes a prefix, exponent operators  apply  to  the  combination,  so
406       'centimeter3' gives cubic centimeters.  If you separate the prefix from
407       the unit with any multiplication operator (e.g., 'centi meter^3'),  the
408       prefix  is  treated as a separate unit, so the exponent applies only to
409       the unit without the prefix.   The  second  example  is  equivalent  to
410       'centi  *  (meter^3)',  and  gives  a hundredth of a cubic meter, not a
411       cubic centimeter.  The 'units' program is limited internally  to  prod‐
412       ucts   of  99  units;  accordingly,  expressions  like  'meter^100'  or
413       'joule^34' (represented internally as 'kg^34 m^68 / s^68') will fail.
414
415       The '|' operator has the highest  precedence,  so  you  can  write  the
416       square  root of two thirds as '2|3^1|2'.  The '^' operator has the sec‐
417       ond highest precedence, and is evaluated right to left, as usual:
418
419          You have: 5 * 2^3^2
420          You want:
421                  Definition: 2560
422
423       With a dimensionless base unit, any dimensionless exponent is  meaning‐
424       ful (e.g., 'pi^exp(2.371)').  Even though angle is sometimes treated as
425       dimensionless, exponents cannot have dimensions of angle:
426
427          You have: 2^radian
428                           ^
429          Exponent not dimensionless
430
431       If the base unit is not dimensionless, the exponent must be a  rational
432       number  p/q,  and  the  dimension  of the unit must be a power of q, so
433       'gallon^2|3' works but 'acre^2|3' fails.  An exponent using  the  slash
434       ('/') operator (e.g., 'gallon^(2/3)') is also acceptable; the parenthe‐
435       ses are needed because the precedence of '^' is  higher  than  that  of
436       '/'.   Since 'units' cannot represent dimensions with exponents greater
437       than 99, a fully reduced exponent must have q < 100.   When  raising  a
438       non-dimensionless  unit to a power, 'units' attempts to convert a deci‐
439       mal exponent to a rational number with q < 100.  If this is not  possi‐
440       ble 'units' displays an error message:
441
442          You have: ft^1.234
443          Base unit not dimensionless; rational exponent required
444
445       A  decimal  exponent  must match its rational representation to machine
446       precision, so 'acre^1.5' works but 'gallon^0.666' does not.
447
448   Sums and Differences of Units
449       You may sometimes want to add values of different units that  are  out‐
450       side  the  SI.   You  may also wish to use 'units' as a calculator that
451       keeps track of units.  Sums of conformable units are written  with  the
452       '+' character, and differences with the '-' character.
453
454          You have: 2 hours + 23 minutes + 32 seconds
455          You want: seconds
456                  * 8612
457                  / 0.00011611705
458
459          You have: 12 ft + 3 in
460          You want: cm
461                  * 373.38
462                  / 0.0026782366
463
464          You have: 2 btu + 450 ft lbf
465          You want: btu
466                  * 2.5782804
467                  / 0.38785542
468
469       The  expressions  that are added or subtracted must reduce to identical
470       expressions in primitive units, or an error message will be displayed:
471
472          You have: 12 printerspoint - 4 heredium
473                                                ^
474          Illegal sum of non-conformable units
475
476       As usual, the precedence for '+' and '-' is  lower  than  that  of  the
477       other operators.  A fractional quantity such as 2 1/2 cups can be given
478       as '(2+1|2) cups'; the parentheses are necessary because multiplication
479       has  higher  precedence  than  addition.   If you omit the parentheses,
480       'units' attempts to add '2' and '1|2 cups', and you get an  error  mes‐
481       sage:
482
483          You have: 2+1|2 cups
484                             ^
485          Illegal sum or difference of non-conformable units
486
487       The  expression  could also be correctly written as '(2+1/2) cups'.  If
488       you write '2 1|2 cups' the space is interpreted  as  multiplication  so
489       the result is the same as '1 cup'.
490
491       The  '+'  and  '-'  characters  sometimes  appears  in  exponents  like
492       '3.43e+8'.  This leads to an ambiguity in an expression like '3e+2 yC'.
493       The  unit  'e'  is  a  small unit of charge, so this can be regarded as
494       equivalent to '(3e+2)  yC'  or  '(3  e)+(2  yC)'.   This  ambiguity  is
495       resolved  by  always interpreting '+' and '-' as part of an exponent if
496       possible.
497
498   Numbers as Units
499       For 'units', numbers are just another kind of unit.  They can appear as
500       many  times  as  you  like  and in any order in a unit expression.  For
501       example, to find the volume of a box that is 2 ft by 3 ft by 12  ft  in
502       steres, you could do the following:
503
504          You have: 2 ft 3 ft 12 ft
505          You want: stere
506                  * 2.038813
507                  / 0.49048148
508
509          You have: $ 5 / yard
510          You want: cents / inch
511                  * 13.888889
512                  / 0.072
513
514       And  the  second example shows how the dollar sign in the units conver‐
515       sion can precede the five.  Be careful:  'units'  will  interpret  '$5'
516       with no space as equivalent to 'dollar^5'.
517
518   Built-in Functions
519       Several  built-in  functions  are  provided: 'sin', 'cos', 'tan', 'ln',
520       'log', 'log2', 'exp', 'acos', 'atan' and 'asin'.  The 'sin', 'cos', and
521       'tan'  functions require either a dimensionless argument or an argument
522       with dimensions of angle.
523
524          You have: sin(30 degrees)
525          You want:
526                  Definition: 0.5
527
528          You have: sin(pi/2)
529          You want:
530                  Definition: 1
531
532          You have: sin(3 kg)
533                            ^
534          Unit not dimensionless
535
536       The other functions on the list require dimensionless  arguments.   The
537       inverse  trigonometric  functions  return  arguments with dimensions of
538       angle.
539
540       If you wish to  take  roots  of  units,  you  may  use  the  'sqrt'  or
541       'cuberoot'  functions.   These functions require that the argument have
542       the appropriate root.  You can obtain higher roots by using  fractional
543       exponents:
544
545          You have: sqrt(acre)
546          You want: feet
547                  * 208.71074
548                  / 0.0047913202
549
550          You have: (400 W/m^2 / stefanboltzmann)^(1/4)
551          You have:
552                  Definition: 289.80882 K
553
554          You have: cuberoot(hectare)
555                                    ^
556          Unit not a root
557
558   Previous Result
559       You  can  insert the result of the previous conversion using the under‐
560       score ('_').  It is useful when you want to convert the same  input  to
561       several different units, for example
562
563          You have: 2.3 tonrefrigeration
564          You want: btu/hr
565                  * 27600
566                  / 3.6231884e-005
567          You have: _
568          You want: kW
569                  * 8.0887615
570                  / 0.12362832
571
572       Suppose  you  want to do some deep frying that requires an oil depth of
573       2 inches.  You have 1/2 gallon of oil, and want to  know  the  largest-
574       diameter pan that will maintain the required depth.  The nonlinear unit
575       'circlearea' gives the radius of the circle (see Other Nonlinear Units,
576       for  a more detailed description) in SI units; you want the diameter in
577       inches:
578
579          You have: 1|2 gallon / 2 in
580          You want: circlearea
581                  0.10890173 m
582          You have: 2 _
583          You want: in
584                  * 8.5749393
585                  / 0.1166189
586
587       In most cases, surrounding white space is  optional,  so  the  previous
588       example could have used '2_'.  If '_' follows a non-numerical unit sym‐
589       bol, however, the space is required:
590
591          You have: m_
592                     ^
593          Parse error
594
595       When '_' is followed by a digit, the operation is multiplication rather
596       than exponentiation, so that '_2', is equivalent to '_ * 2' rather than
597       '_^2'.
598
599       You can use the '_' symbol any number of times; for example,
600
601          You have: m
602          You want:
603                  Definition: 1 m
604          You have: _ _
605          You want:
606                  Definition: 1 m^2
607
608       Using '_' before a conversion has  been  performed  (e.g.,  immediately
609       after invocation) generates an error:
610
611          You have: _
612                    ^
613          No previous result; '_' not set
614
615       Accordingly, '_' serves no purpose when 'units' is invoked non-interac‐
616       tively.
617
618       If 'units' is invoked with the '--verbose' option (see Invoking Units),
619       the value of '_' is not expanded:
620
621          You have: mile
622          You want: ft
623                  mile = 5280 ft
624                  mile = (1 / 0.00018939394) ft
625          You have: _
626          You want: m
627                  _ = 1609.344 m
628                  _ = (1 / 0.00062137119) m
629
630       You  can give '_' at the 'You want:' prompt, but it usually is not very
631       useful.
632
633   Complicated Unit Expressions
634       The 'units' program is especially  helpful  in  ensuring  accuracy  and
635       dimensional  consistency when converting lengthy unit expressions.  For
636       example, one form of the Darcy-Weisbach fluid-flow equation is
637
638            Delta P = (8 / pi)^2 (rho fLQ^2) / d^5,
639
640       where Delta P is the pressure drop, rho is the mass density, f  is  the
641       (dimensionless)  friction factor, L is the length of the pipe, Q is the
642       volumetric flow rate, and d is the pipe diameter.  It might be  desired
643       to have the equation in the form
644
645            Delta P = A1 rho fLQ^2 / d^5
646
647       that  accepted  the  user's normal units; for typical units used in the
648       US, the required conversion could be something like
649
650          You have: (8/pi^2)(lbm/ft^3)ft(ft^3/s)^2(1/in^5)
651          You want: psi
652                  * 43.533969
653                  / 0.022970568
654
655       The parentheses allow individual terms in the expression to be  entered
656       naturally,  as they might be read from the formula.  Alternatively, the
657       multiplication could be done with the '*' rather  than  a  space;  then
658       parentheses are needed only around 'ft^3/s' because of its exponent:
659
660          You have: 8/pi^2 * lbm/ft^3 * ft * (ft^3/s)^2 /in^5
661          You want: psi
662                  * 43.533969
663                  / 0.022970568
664
665       Without  parentheses, and using spaces for multiplication, the previous
666       conversion would need to be entered as
667
668          You have: 8 lb ft ft^3 ft^3 / pi^2 ft^3 s^2 in^5
669          You want: psi
670                  * 43.533969
671                  / 0.022970568
672
673   Backwards Compatibility:
674       '*' and '-' The  original  'units'  assigned  multiplication  a  higher
675       precedence  than division using the slash.  This differs from the usual
676       precedence rules, which give multiplication and division  equal  prece‐
677       dence, and can be confusing for people who think of units as a calcula‐
678       tor.
679
680       The star operator ('*')  included  in  this  'units'  program  has,  by
681       default,  the  same precedence as division, and hence follows the usual
682       precedence rules.  For backwards compatibility you can  invoke  'units'
683       with  the  '--oldstar'  option.   Then '*' has a higher precedence than
684       division, and the same precedence as multiplication using the space.
685
686       Historically, the hyphen ('-') has been used in technical  publications
687       to indicate products of units, and the original 'units' program treated
688       it as a multiplication  operator.   Because  'units'  provides  several
689       other  ways  to  obtain unit products, and because '-' is a subtraction
690       operator in general algebraic expressions, 'units'  treats  the  binary
691       '-'  as a subtraction operator by default.  For backwards compatibility
692       use the '--product' option, which causes 'units' to  treat  the  binary
693       '-' operator as a product operator.  When '-' is a multiplication oper‐
694       ator it has the same precedence as multiplication with a space,  giving
695       it a higher precedence than division.
696
697       When  '-'  is used as a unary operator it negates its operand.  Regard‐
698       less of the 'units' options, if '-' appears after '(' or after '+' then
699       it  will  act  as  a  negation  operator.  So you can always compute 20
700       degrees minus 12 minutes by entering '20 degrees  +  -12 arcmin'.   You
701       must use this construction when you define new units because you cannot
702       know what options will be in force when your definition is processed.
703

NONLINEAR UNIT CONVERSIONS

705       Nonlinear units are represented using functional notation.   They  make
706       possible nonlinear unit conversions such as temperature.
707
708   Temperature Conversions
709       Conversions  between temperatures are different from linear conversions
710       between temperature increments—see the  example  below.   The  absolute
711       temperature  conversions are handled by units starting with 'temp', and
712       you must use functional notation.   The  temperature-increment  conver‐
713       sions  are done using units starting with 'deg' and they do not require
714       functional notation.
715
716          You have: tempF(45)
717          You want: tempC
718                  7.2222222
719
720          You have: 45 degF
721          You want: degC
722                  * 25
723                  / 0.04
724
725       Think of 'tempF(x)' not as a function but as a notation that  indicates
726       that  x should have units of 'tempF' attached to it.  See Defining Non‐
727       linear Units.  The first conversion  shows  that  if  it's  45  degrees
728       Fahrenheit  outside,  it's  7.2 degrees Celsius.  The second conversion
729       indicates that a change of  45  degrees  Fahrenheit  corresponds  to  a
730       change  of  25  degrees  Celsius.  The conversion from 'tempF(x)' is to
731       absolute temperature, so that
732
733          You have: tempF(45)
734          You want: degR
735                  * 504.67
736                  / 0.0019814929
737
738       gives the same result as
739
740          You have: tempF(45)
741          You want: tempR
742                  * 504.67
743                  / 0.0019814929
744
745       But if you convert 'tempF(x)' to 'degC', the  output  is  probably  not
746       what you expect:
747
748          You have: tempF(45)
749          You want: degC
750                  * 280.37222
751                  / 0.0035666871
752
753       The  result  is the temperature in K, because 'degC' is defined as 'K',
754       the Kelvin. For consistent results, use the 'tempX' units when convert‐
755       ing to a temperature rather than converting a temperature increment.
756
757       The  'tempC()'  and 'tempF()' definitions are limited to positive abso‐
758       lute temperatures, and giving a value that would result in  a  negative
759       absolute temperature generates an error message:
760
761          You have: tempC(-275)
762                              ^
763          Argument of function outside domain
764                              ^
765
766   Other Nonlinear Units
767       Some  other  examples  of  nonlinear  units are numerous different ring
768       sizes and wire gauges, the grit sizes used for abrasives,  the  decibel
769       scale,  shoe  size, scales for the density of sugar (e.g., baume).  The
770       standard data file also supplies units for computing the area of a cir‐
771       cle  and  the volume of a sphere.  See the standard units data file for
772       more details.  Wire gauges with multiple  zeroes  are  signified  using
773       negative  numbers where two zeroes is '-1'.  Alternatively, you can use
774       the synonyms 'g00', 'g000', and so on that are defined in the  standard
775       units data file.
776
777          You have: wiregauge(11)
778          You want: inches
779                  * 0.090742002
780                  / 11.020255
781
782          You have: brwiregauge(g00)
783          You want: inches
784                  * 0.348
785                  / 2.8735632
786
787          You have: 1 mm
788          You want: wiregauge
789                  18.201919
790
791          You have: grit_P(600)
792          You want: grit_ansicoated
793                  342.76923
794
795       The  last  example shows the conversion from P graded sand paper, which
796       is the European standard and may be marked ``P600'' on the back, to the
797       USA standard.
798
799       You  can  compute  the  area  of  a  circle  using  the nonlinear unit,
800       'circlearea'.  You can also do this  using  the  circularinch  or  cir‐
801       cleinch.  The next example shows two ways to compute the area of a cir‐
802       cle with a five inch radius and one way to  compute  the  volume  of  a
803       sphere with a radius of one meter.
804
805          You have: circlearea(5 in)
806          You want: in2
807                  * 78.539816
808                  / 0.012732395
809
810          You have: 10^2 circleinch
811          You want: in2
812                  * 78.539816
813                  / 0.012732395
814
815          You have: spherevol(meter)
816          You want: ft3
817                  * 147.92573
818                  / 0.0067601492
819
820       The inverse of a nonlinear conversion is indicated by prefixing a tilde
821       ('~') to the nonlinear unit name:
822
823          You have: ~wiregauge(0.090742002 inches)
824          You want:
825                  Definition: 11
826
827       You can give a nonlinear unit definition without an argument or  paren‐
828       theses, and press Enter at the 'You want:' prompt to get the definition
829       of a nonlinear unit; if the definition is not valid for all  real  num‐
830       bers,  the range of validity is also given.  If the definition requires
831       specific units this information is also displayed:
832
833          You have: tempC
834                  Definition: tempC(x) = x K + stdtemp
835                              defined for x >= -273.15
836          You have: ~tempC
837                  Definition: ~tempC(tempC) = (tempC +(-stdtemp))/K
838                              defined for tempC >= 0 K
839          You have: circlearea
840                  Definition: circlearea(r) = pi r^2
841                              r has units m
842
843       To see the definition of the inverse use the  '~'  notation.   In  this
844       case  the  parameter  in  the functional definition will usually be the
845       name of the unit.  Note that the inverse  for  'tempC'  shows  that  it
846       requires units of 'K' in the specification of the allowed range of val‐
847       ues.  Nonlinear unit conversions are described in more detail in Defin‐
848       ing Nonlinear Units.
849

UNIT LISTS: CONVERSION TO SUMS OF UNITS

851       Outside  of  the SI, it is sometimes desirable to convert a single unit
852       to a sum of units—for example, feet to feet plus inches.   The  conver‐
853       sion from sums of units was described in Sums and Differences of Units,
854       and is a simple matter of adding the units with the '+' sign:
855
856          You have: 12 ft + 3 in + 3|8 in
857          You want: ft
858                  * 12.28125
859                  / 0.081424936
860
861       Although you can similarly write a sum of  units  to  convert  to,  the
862       result  will  not be the conversion to the units in the sum, but rather
863       the conversion to the particular sum that you have entered:
864
865          You have: 12.28125 ft
866          You want: ft + in + 1|8 in
867                  * 11.228571
868                  / 0.089058524
869
870       The unit expression given at the 'You want:' prompt  is  equivalent  to
871       asking  for conversion to multiples of '1 ft + 1 in + 1|8 in', which is
872       1.09375 ft, so the conversion in the previous example is equivalent to
873
874          You have: 12.28125 ft
875          You want: 1.09375 ft
876                  * 11.228571
877                  / 0.089058524
878
879       In converting to a sum of units like miles, feet and inches, you  typi‐
880       cally  want  the largest integral value for the first unit, followed by
881       the largest integral value for the next, and the remainder converted to
882       the  last unit.  You can do this conversion easily with 'units' using a
883       special syntax for lists of units.  You must list the desired units  in
884       order  from largest to smallest, separated by the semicolon (';') char‐
885       acter:
886
887          You have: 12.28125 ft
888          You want: ft;in;1|8 in
889                  12 ft + 3 in + 3|8 in
890
891       The conversion always gives integer coefficients on the  units  in  the
892       list, except possibly the last unit when the conversion is not exact:
893
894          You have: 12.28126 ft
895          You want: ft;in;1|8 in
896                  12 ft + 3 in + 3.00096 * 1|8 in
897
898       The order in which you list the units is important:
899
900          You have: 3 kg
901          You want: oz;lb
902                  105 oz + 0.051367866 lb
903
904          You have: 3 kg
905          You want: lb;oz
906                  6 lb + 9.8218858 oz
907
908       Listing ounces before pounds produces a technically correct result, but
909       not a very useful one.  You must list the units in descending order  of
910       size in order to get the most useful result.
911
912       Ending  a  unit  list  with  the  separator  ';' has the same effect as
913       repeating the last unit on the list, so 'ft;in;1|8 in;'  is  equivalent
914       to 'ft;in;1|8 in;1|8 in'.  With the example above, this gives
915
916          You have: 12.28126 ft
917          You want: ft;in;1|8 in;
918                  12 ft + 3 in + 3|8 in + 0.00096 * 1|8 in
919
920       in  effect  separating  the integer and fractional parts of the coeffi‐
921       cient for the last unit.  If you instead prefer to round the last coef‐
922       ficient to an integer you can do this with the '--round' ('-r') option.
923       With the previous example, the result is
924
925          You have: 12.28126 ft
926          You want: ft;in;1|8 in
927                  12 ft + 3 in + 3|8 in (rounded down to nearest 1|8 in)
928
929       When you use the '-r' option, repeating the last unit on the  list  has
930       no  effect  (e.g.,  'ft;in;1|8  in;1|8  in' is equivalent to 'ft;in;1|8
931       in'), and hence neither does ending a list with a ';'.  With  a  single
932       unit and the '-r' option, a terminal ';' does have an effect: it causes
933       'units' to treat the single unit as a list and produce a rounded  value
934       for  the  single  unit.   Without the extra ';', the '-r' option has no
935       effect on single unit conversions.  This example shows the output using
936       the '-r' option:
937
938          You have: 12.28126 ft
939          You want: in
940                  * 147.37512
941                  / 0.0067854058
942
943          You have: 12.28126 ft
944          You want: in;
945                  147 in (rounded down to nearest in)
946
947       Each  unit  that appears in the list must be conformable with the first
948       unit on the list, and of course the listed units must also be  conform‐
949       able with the unit that you enter at the 'You have:' prompt.
950
951          You have: meter
952          You want: ft;kg
953                       ^
954          conformability error
955                  ft = 0.3048 m
956                  kg = 1 kg
957
958          You have: meter
959          You want: lb;oz
960          conformability error
961                  1 m
962                  0.45359237 kg
963
964       In  the  first  case,  'units'  reports  the disagreement between units
965       appearing on the list.  In the second case, 'units'  reports  disagree‐
966       ment  between  the  unit  you entered and the desired conversion.  This
967       conformability error is based on the first unit on the unit list.
968
969       Other common candidates for conversion to sums of units are angles  and
970       time:
971
972          You have: 23.437754 deg
973          You want; deg;arcmin;arcsec
974              23 deg + 26 arcmin + 15.9144 arcsec
975
976          You have: 7.2319 hr
977          You want: hr;min;sec
978              7 hr + 13 min + 54.84 sec
979
980       In  North America, recipes for cooking typically measure ingredients by
981       volume, and use units that are not always convenient multiples of  each
982       other.   Suppose  that  you  have a recipe for 6 and you wish to make a
983       portion for 1.  If the recipe calls for 2 1/2 cups  of  an  ingredient,
984       you  might  wish to know the measurements in terms of measuring devices
985       you have available, you could use 'units' and enter
986
987          You have: (2+1|2) cup / 6
988          You want: cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
989                  1|3 cup + 1 tbsp + 1 tsp
990
991       By default, if a unit in a list begins with fraction of  the  form  1|x
992       and  its multiplier is an integer, the fraction is given as the product
993       of the multiplier and the numerator; for example,
994
995          You have: 12.28125 ft
996          You want: ft;in;1|8 in;
997                  12 ft + 3 in + 3|8 in
998
999       In many cases, such as the example above, this is what is  wanted,  but
1000       sometimes  it  is  not.  For example, a cooking recipe for 6 might call
1001       for 5 1/4 cup of an ingredient, but you want a portion for 2, and  your
1002       1-cup measure is not available; you might try
1003
1004          You have: (5+1|4) cup / 3
1005          You want: 1|2 cup;1|3 cup;1|4 cup
1006                  3|2 cup + 1|4 cup
1007
1008       This  result might be fine for a baker who has a 1 1/2-cup measure (and
1009       recognizes the equivalence), but it may not be  as  useful  to  someone
1010       with  more limited set of measures, who does want to do additional cal‐
1011       culations, and only wants to know ``How many 1/2-cup measures to I need
1012       to  add?''   After  all,  that's  what  was  actually  asked.  With the
1013       '--show-factor' option, the factor will not be combined  with  a  unity
1014       numerator, so that you get
1015
1016          You have: (5+1|4) cup / 3
1017          You want: 1|2 cup;1|3 cup;1|4 cup
1018                  3 * 1|2 cup + 1|4 cup
1019
1020       A user-specified fractional unit with a numerator other than 1 is never
1021       overridden, however—if a unit  list  specifies  '3|4  cup;1|2  cup',  a
1022       result  equivalent  to 1 1/2 cups will always be shown as '2 * 3|4 cup'
1023       whether or not the '--show-factor' option is given.
1024
1025       Some applications for unit lists may be less obvious.  Suppose that you
1026       have  a postal scale and wish to ensure that it's accurate at 1 oz, but
1027       have only metric calibration weights.  You might try
1028
1029          You have: 1 oz
1030          You want: 100 g;50 g; 20 g;10 g;5 g;2 g;1 g;
1031                  20 g + 5 g + 2 g + 1 g + 0.34952312 * 1 g
1032
1033       You might then place one each of the 20 g, 5 g, 2 g, and 1 g weights on
1034       the scale and hope that it indicates close to
1035
1036          You have: 20 g + 5 g + 2 g + 1 g
1037          You want: oz;
1038                  0.98767093 oz
1039
1040       Appending ';' to 'oz' forces a one-line display that includes the unit;
1041       here the integer part of the result is zero, so it is not displayed.
1042
1043       A unit list such as
1044
1045          cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
1046
1047       can be tedious to enter.  The 'units' program provides shorthand  names
1048       for some common combinations:
1049
1050          hms         hours, minutes, seconds
1051          dms         angle: degrees, minutes, seconds
1052          time        years, days, hours, minutes and seconds
1053          usvol       US cooking volume: cups and smaller
1054
1055       Using  these shorthands, or unit list aliases, you can do the following
1056       conversions:
1057
1058          You have: anomalisticyear
1059          You want: time
1060                  1 year + 25 min + 3.4653216 sec
1061          You have: 1|6 cup
1062          You want: usvol
1063                  2 tbsp + 2 tsp
1064
1065       You cannot combine a unit list alias with other units: it  must  appear
1066       alone at the 'You want:' prompt.
1067
1068       You  can  display the definition of a unit list alias by entering it at
1069       the 'You have:' prompt:
1070
1071          You have: dms
1072                  Definition: unit list, deg;arcmin;arcsec
1073
1074       When you specify compact output with '--compact', '--terse' or '-t' and
1075       perform conversion to a unit list, 'units' lists the conversion factors
1076       for each unit in the list, separated by semicolons.
1077
1078          You have: year
1079          You want: day;min;sec
1080          365;348;45.974678
1081
1082       Unlike the case of regular output, zeros are included  in  this  output
1083       list:
1084
1085          You have: liter
1086          You want: cup;1|2 cup;1|4 cup;tbsp
1087          4;0;0;3.6280454
1088

LOGGING CALCULATIONS

1090       The  '--log' option allows you to save the results of calculations in a
1091       file; this can be useful if you need a permanent record of  your  work.
1092       For example, the fluid-flow conversion in Complicated Unit Expressions,
1093       is lengthy, and if you were to use it in designing a piping system, you
1094       might  want  a  record  of it for the project file.  If the interactive
1095       session
1096
1097          # Conversion factor A1 for pressure drop
1098          # dP = A1 rho f L Q^2/d^5
1099          You have: (8/pi^2) (lbm/ft^3)ft(ft^3/s)^2(1/in^5) # Input units
1100          You want: psi
1101                  * 43.533969
1102                  / 0.022970568
1103
1104       were logged, the log file would contain
1105
1106          ### Log started Fri Oct 02 15:55:35 2015
1107
1108          # Conversion factor A1 for pressure drop
1109          # dP = A1 rho f L Q^2/d^5
1110          From: (8/pi^2) (lbm/ft^3)ft(ft^3/s)^2(1/in^5)   # Input units
1111          To:   psi
1112                  * 43.533969
1113                  / 0.022970568
1114
1115       The time is written to the log file when the file is opened.
1116
1117       The use of comments can help clarify the meaning  of  calculations  for
1118       the  log.   The log includes conformability errors between the units at
1119       the 'You have:' and 'You want:' prompts, but not other errors,  includ‐
1120       ing  lack  of  conformability  of items in sums or differences or among
1121       items in a unit list.  For example, a conversion between  zenith  angle
1122       and elevation angle could involve
1123
1124          You have: 90 deg - (5 deg + 22 min + 9 sec)
1125                                             ^
1126          Illegal sum or difference of non-conformable units
1127          You have: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
1128          You want: dms
1129                  84 deg + 37 arcmin + 51 arcsec
1130          You have: _
1131          You want: deg
1132                  * 84.630833
1133                  / 0.011816024
1134          You have:
1135
1136       The log file would contain
1137
1138          From: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
1139          To:   deg;arcmin;arcsec
1140                  84 deg + 37 arcmin + 51 arcsec
1141          From: _
1142          To:   deg
1143                  * 84.630833
1144                  / 0.011816024
1145
1146       The  initial  entry  error  (forgetting  that minutes have dimension of
1147       time, and that arcminutes must be used for dimensions  of  angle)  does
1148       not  appear  in  the  output.   When  converting  to a unit list alias,
1149       'units' expands the alias in the log file.
1150
1151       The 'From:' and 'To:' tags are written to the  log  file  even  if  the
1152       '--quiet'  option  is  given.   If  the log file exists when 'units' is
1153       invoked, the new results are appended to the log  file.   The  time  is
1154       written  to  the  log  file  each time the file is opened.  The '--log'
1155       option is ignored when 'units' is used non-interactively.
1156

INVOKING UNITS

1158       You invoke 'units' like this:
1159
1160          units [options] [from-unit [to-unit]]
1161
1162       If the from-unit and to-unit are omitted, the program will use interac‐
1163       tive  prompts  to determine which conversions to perform.  See Interac‐
1164       tive Use.  If both from-unit and to-unit are given, 'units' will  print
1165       the  result of that single conversion and then exit.  If only from-unit
1166       appears on the command line, 'units' will  display  the  definition  of
1167       that unit and exit.  Units specified on the command line may need to be
1168       quoted to protect them from shell interpretation and to group them into
1169       two arguments.  See Command Line Use.
1170
1171       The default behavior of 'units' can be changed by various options given
1172       on the command line.  In most cases, the options may be given in either
1173       short  form  (a single '-' followed by a single character) or long form
1174       ('--' followed  by  a  word  or  hyphen-separated  words).   Short-form
1175       options  are cryptic but require less typing; long-form options require
1176       more typing but are more explanatory and may be  more  mnemonic.   With
1177       long-form options you need only enter sufficient characters to uniquely
1178       identify the option to the program.  For example, '--out %f' works, but
1179       '--o %f'  fails  because  'units' has other long options beginning with
1180       'o'.  However, '--q' works because '--quiet' is the  only  long  option
1181       beginning with 'q'.
1182
1183       Some  options  require  arguments  to specify a value (e.g., '-d 12' or
1184       '--digits 12').  Short-form options that do not take arguments  may  be
1185       concatenated  (e.g.,  '-erS'  is  equivalent  to  '-e -r -S'); the last
1186       option in such a  list  may  be  one  that  takes  an  argument  (e.g.,
1187       '-ed 12').   With  short-form  options, the space between an option and
1188       its argument is optional  (e.g.,  '-d12'  is  equivalent  to  '-d 12').
1189       Long-form  options  may  not  be  concatenated, and the space between a
1190       long-form option and its argument is required.   Short-form  and  long-
1191       form  options  may  be  intermixed on the command line.  Options may be
1192       given in any order, but when  incompatible  options  (e.g.,  '--output-
1193       format' and '--exponential') are given in combination, behavior is con‐
1194       trolled by the last option  given.   For  example,  '-o%.12f -e'  gives
1195       exponential format with the default eight significant digits).
1196
1197       The following options are available:
1198
1199       -c, --check
1200              Check that all units and prefixes defined in the units data file
1201              reduce to primitive units.  Print a list of all units that  can‐
1202              not  be reduced.  Also display some other diagnostics about sus‐
1203              picious definitions in the units data  file.   Only  definitions
1204              active in the current locale are checked.  You should always run
1205              'units' with this option after modifying a units data file.
1206
1207       --check-verbose, --verbose-check
1208              Like the '--check' option, this option prints a  list  of  units
1209              that cannot be reduced.  But to help find unit  definitions that
1210              cause endless loops, it lists the units as they are checked.  If
1211              'units'  hangs, then the last unit to be printed has a bad defi‐
1212              nition.  Only definitions  active  in  the  current  locale  are
1213              checked.
1214
1215       -d ndigits, --digits ndigits
1216              Set  the number of significant digits in the output to the value
1217              specified (which must  be  greater  than  zero).   For  example,
1218              '-d 12' sets the number of significant digits to 12.  With expo‐
1219              nential output 'units' displays one digit to  the  left  of  the
1220              decimal  point  and  eleven  digits  to the right of the decimal
1221              point.  On most systems, the maximum number of internally  mean‐
1222              ingful  digits  is 15; if you specify a greater number than your
1223              system's maximum, 'units' will print a warning and set the  num‐
1224              ber  to the largest meaningful value.  To directly set the maxi‐
1225              mum value, give an  argument  of  'max'  (e.g.,  '-d max').   Be
1226              aware,  of  course, that ``significant'' here refers only to the
1227              display of numbers; if results depend on physical constants  not
1228              known to this precision, the physically meaningful precision may
1229              be less than that shown.  The '--digits' option  conflicts  with
1230              the '--output-format' option.
1231
1232       -e, --exponential
1233              Set  the  numeric output format to exponential (i.e., scientific
1234              notation), like that used in  the  Unix  'units'  program.   The
1235              default  precision  is eight significant digits (seven digits to
1236              the right of the decimal point); this can be  changed  with  the
1237              '--digits'  option.   The  '--exponential' option conflicts with
1238              the '--output-format' option.
1239
1240       -o format, --output-format format
1241              This option affords complete control  over  the  numeric  output
1242              format using the specified format. The format is a single float‐
1243              ing point numeric format for the 'printf()' function  in  the  C
1244              programming  language.   All  compilers support the format types
1245              'g' and 'G' to specify significant digits, 'e' and 'E' for  sci‐
1246              entific  notation, and 'f' for fixed-point decimal.  The ISO C99
1247              standard introduced the 'F' type for fixed-point decimal and the
1248              'a'  and  'A'  types for hexadecimal floating point; these types
1249              are allowed with compilers that support them.  The default  for‐
1250              mat   is  '%.8g';  for  greater  precision,  you  could  specify
1251              '-o %.15g'.  See Numeric Output Format and the documentation for
1252              'printf()' for more detailed descriptions of the format specifi‐
1253              cation.  The '--output-format' option affords the greatest  con‐
1254              trol of the output appearance, but requires at least rudimentary
1255              knowledge of the 'printf()' format syntax.  If you don't want to
1256              bother  with the 'printf()' syntax, you can specify greater pre‐
1257              cision more simply with the '--digits' option or select exponen‐
1258              tial  format with '--exponential'.  The '--output-format' option
1259              is incompatible with the '--exponential' and '--digits' options.
1260
1261       -f filename, --file filename
1262              Instruct 'units' to load the units file filename.  You can spec‐
1263              ify up to 25 units files on the command line.  When you use this
1264              option, 'units' will load only the files you list on the command
1265              line;  it will not load the standard file or your personal units
1266              file unless you explicitly list them.  If filename is the  empty
1267              string  ('-f ""'),  the default units file (or that specified by
1268              'UNITSFILE') will be loaded in addition to any others  specified
1269              with '-f'.
1270
1271       -L logfile, --log logfile
1272              Save  the  results of calculations in the file logfile; this can
1273              be useful if it is important to have a record  of  unit  conver‐
1274              sions  or  other calculations that are to be used extensively or
1275              in a critical activity such as a program or design project.   If
1276              logfile  exits,  the new results are appended to the file.  This
1277              option is ignored when 'units' is used  non-interactively.   See
1278              Logging  Calculations  for  a more detailed description and some
1279              examples.
1280
1281       -H filename, --history filename
1282              Instruct 'units' to save history to filename, so that  a  record
1283              of  your  commands  is  available for retrieval across different
1284              'units' invocations.  To prevent the history  from  being  saved
1285              set  filename to the empty string ('-H ""').  This option has no
1286              effect if readline is not available.
1287
1288       -h, --help
1289              Print out a summary of the options for 'units'.
1290
1291       -m, --minus
1292              Causes '-' to be interpreted as a subtraction operator.  This is
1293              the default behavior.
1294
1295       -p, --product
1296              Causes  '-'  to be interpreted as a multiplication operator when
1297              it has two operands.  It will act as a negation operator when it
1298              has  only  one  operand: '(-3)'.  By default '-' is treated as a
1299              subtraction operator.
1300
1301       --oldstar
1302              Causes '*' to have the old-style  precedence,  higher  than  the
1303              precedence of division so that '1/2*3' will equal '1/6'.
1304
1305       --newstar
1306              Forces '*' to have the new (default) precedence that follows the
1307              usual rules of algebra: the precedence of '*' is the same as the
1308              precedence of '/', so that '1/2*3' will equal '3/2'.
1309
1310       --compact
1311              Give  compact output featuring only the conversion factor.  This
1312              turns off the '--verbose' option.
1313
1314       -q, --quiet, --silent
1315              Suppress prompting of the user for units and the display of sta‐
1316              tistics about the number of units loaded.
1317
1318       -n, --nolists
1319              Disable conversion to unit lists.
1320
1321       -r, --round
1322              When  converting to a combination of units given by a unit list,
1323              round the value of the last unit in  the  list  to  the  nearest
1324              integer.
1325
1326       -S, --show-factor
1327              When  converting  to a combination of units specified in a list,
1328              always show a non-unity factor before a unit that begins with  a
1329              fraction with a unity denominator.  By default, if the unit in a
1330              list begins with fraction of the form 1|x and its multiplier  is
1331              an integer other than 1, the fraction is given as the product of
1332              the multiplier and the numerator (e.g., '3|8 in' rather than  '3
1333              *  1|8 in').   In  some  cases,  this is not what is wanted; for
1334              example, the results for  a  cooking  recipe  might  show  '3  *
1335              1|2 cup'  as  '3|2 cup'.   With  the  '--show-factor'  option, a
1336              result equivalent to 1.5 cups will  display  as  '3  *  1|2 cup'
1337              rather  than '3|2 cup'.  A user-specified fractional unit with a
1338              numerator other than 1 is never overridden,  however—if  a  unit
1339              list  specifies  '3|4 cup;1|2 cup', a result equivalent to 1 1/2
1340              cups will always be shown as '2 * 3|4 cup' whether  or  not  the
1341              '--show-factor' option is given.
1342
1343       -s, --strict
1344              Suppress  conversion  of  units  to their reciprocal units.  For
1345              example, 'units' will normally convert hertz to seconds  because
1346              these  units  are  reciprocals of each other.  The strict option
1347              requires that units be strictly conformable to perform a conver‐
1348              sion,  and will give an error if you attempt to convert hertz to
1349              seconds.
1350
1351       -1, --one-line
1352              Give only one line of output (the forward conversion).   Do  not
1353              print  the  reverse  conversion.   If a reciprocal conversion is
1354              performed then 'units' will still print the ``reciprocal conver‐
1355              sion'' line.
1356
1357       -t, --terse
1358              Give  terse  output  when  converting units.  This option can be
1359              used when calling 'units' from another program so that the  out‐
1360              put  is  easy  to parse.  This option has the combined effect of
1361              these options: '--strict'  '--quiet'  '--one-line'  '--compact'.
1362              When  combined  with  '--version'  it produces a display showing
1363              only the program name and version number.
1364
1365       -v, --verbose
1366              Give slightly more verbose output when converting  units.   When
1367              combined  with  the  '-c'  option  this gives the same effect as
1368              '--check-verbose'.  When combined with  '--version'  produces  a
1369              more detailed output, equivalent to the '--info' option.
1370
1371       -V, --version
1372              Print  the  program  version number, tell whether the 'readline'
1373              library has been included, tell whether UTF-8 support  has  been
1374              included;  give  the  locale,  the location of the default units
1375              data file, and the location of the  personal  units  data  file;
1376              indicate if the personal units data file does not exist.
1377
1378       When given in combination with the '--terse' option, the program prints
1379       only the version number and exits.
1380
1381       When given in combination with the '--verbose' option, the program, the
1382       '--version' option has the same effect as the '--info' option below.
1383
1384       -I, --info
1385              Print  the  information  given with the '--version' option, show
1386              the pathname of the  units  program,  show  the  status  of  the
1387              'UNITSFILE'  and  'MYUNITSFILE' environment variables, and addi‐
1388              tional information about how 'units' locates the related  files.
1389              On   systems  running  Microsoft  Windows,  the  status  of  the
1390              'UNITSLOCALE' environment variable  and  information  about  the
1391              related  locale  map  are also given.  This option is usually of
1392              interest only to developers and administrators, but it can some‐
1393              times be useful for troubleshooting.
1394
1395       Combining  the  '--version' and '--verbose' options has the same effect
1396       as giving '--info'.
1397
1398       -U, --unitsfile
1399              Print the location of the default units data file and  exit;  if
1400              the file cannot be found, print ``Units data file not found''.
1401
1402       -l locale, --locale locale
1403              Print  the  information  given with the '--version' option, show
1404              the Force a specified locale such as 'en_GB' to get British def‐
1405              initions  by default.  This overrides the locale determined from
1406              system settings or environment  variables.   See  Locale  for  a
1407              description of locale format.
1408

ADDING YOUR OWN DEFINITIONS

1410   Units Data Files
1411       The  units  and  prefixes  that  'units' can convert are defined in the
1412       units data file,  typically  '/usr/share/units/definitions.units'.   If
1413       you  can't  find this file, run 'units --version' to get information on
1414       the file locations for your installation.  Although you can  extend  or
1415       modify  this  data  file  if you have appropriate user privileges, it's
1416       usually better to put extensions in separate files so that the  defini‐
1417       tions will be preserved if you update 'units'.
1418
1419       You  can  include additional data files in the units database using the
1420       '!include' command in the standard units data file. For example
1421
1422          !include    /usr/local/share/units/local.units
1423
1424       might be appropriate for a site-wide supplemental data file.  The loca‐
1425       tion  of  the  '!include'  statement in the standard units data file is
1426       important; later definitions replace earlier ones, so  any  definitions
1427       in  an  included  file  will override definitions before the '!include'
1428       statement in the standard units data file.  With normal invocation,  no
1429       warning  is given about redefinitions; to ensure that you don't have an
1430       unintended redefinition, run 'units -c' after  making  changes  to  any
1431       units data file.
1432
1433       If  you  want to add your own units in addition to or in place of stan‐
1434       dard or site-wide supplemental units data files, you can  include  them
1435       in the '.units' file in your home directory.  If this file exists it is
1436       read after the standard units data file, so  that  any  definitions  in
1437       this  file  will  replace definitions of the same units in the standard
1438       data file or in files included from the standard data file.  This  file
1439       will  not be read if any units files are specified on the command line.
1440       (Under Windows the personal units file is named 'unitdef.units'.)  Run‐
1441       ning  'units -V'  will  display  the location and name of your personal
1442       units file.
1443
1444       The 'units' program first tries to determine your home  directory  from
1445       the 'HOME' environment variable.  On systems running Microsoft Windows,
1446       if 'HOME' does not exist, 'units' attempts to find your home  directory
1447       from  'HOMEDRIVE',  'HOMEPATH'  and  'USERPROFILE'.  You can specify an
1448       arbitrary file as your personal units data file with the  'MYUNITSFILE'
1449       environment  variable; if this variable exists, its value is used with‐
1450       out searching your home directory.  The default units  data  files  are
1451       described in more detail in Data Files.
1452
1453   Defining New Units and Prefixes
1454       A  unit is specified on a single line by giving its name and an equiva‐
1455       lence.  Comments start with a '#' character, which can appear  anywhere
1456       in  a line.  The backslash character ('\') acts as a continuation char‐
1457       acter if it appears as the last character on a line, making it possible
1458       to spread definitions out over several lines if desired.  A file can be
1459       included by giving the command '!include' followed by the file's  name.
1460       The  '!'   must  be  the first character on the line.  The file will be
1461       sought in the same directory as the parent file unless you give a  full
1462       path.  The name of the file to be included cannot contain spaces or the
1463       comment character '#'.
1464
1465       Unit names must not contain any of the operator  characters  '+',  '-',
1466       '*',  '/',  '|', '^', ';', '~', the comment character '#', or parenthe‐
1467       ses.  They cannot begin or end with an underscore ('_'), a comma  (',')
1468       or  a  decimal  point  ('.').   The figure dash (U+2012), typographical
1469       minus (`-'; U+2212), and en dash (`-'; U+2013)  are  converted  to  the
1470       operator  '-',  so  none  of these characters can appear in unit names.
1471       Names cannot begin with a digit, and if a name ends in  a  digit  other
1472       than  zero,  the  digit  must be preceded by a string beginning with an
1473       underscore, and afterwards consisting only of digits,  decimal  points,
1474       or  commas.   For  example, 'foo_2', 'foo_2,1', or 'foo_3.14' are valid
1475       names but 'foo2' or 'foo_a2' are invalid.   You  could  define  nitrous
1476       oxide as
1477
1478          N2O     nitrogen 2  + oxygen
1479
1480       but would need to define nitrogen dioxide as
1481
1482          NO_2    nitrogen + oxygen 2
1483
1484       Be careful to define new units in terms of old ones so that a reduction
1485       leads to the primitive units, which are marked  with  '!'   characters.
1486       Dimensionless  units are indicated by using the string '!dimensionless'
1487       for the unit definition.
1488
1489       When adding new units, be sure to use the '-c' option to check that the
1490       new  units  reduce properly.  If you create a loop in the units defini‐
1491       tions, then 'units' will hang when invoked with the '-c'  option.   You
1492       will  need  to  use the '--check-verbose' option, which prints out each
1493       unit as it is checked.  The program will still hang, but the last  unit
1494       printed will be the unit that caused the infinite loop.
1495
1496       If  you  define  any units that contain '+' characters, carefully check
1497       them because the '-c' option will not catch non-conformable  sums.   Be
1498       careful with the '-' operator as well.  When used as a binary operator,
1499       the '-' character can perform addition or multiplication  depending  on
1500       the  options used to invoke 'units'.  To ensure consistent behavior use
1501       '-' only as a unary negation operator when writing  units  definitions.
1502       To  multiply two units leave a space or use the '*' operator with care,
1503       recalling that it has two possible precedence values  and  may  require
1504       parentheses  to  ensure consistent behavior.  To compute the difference
1505       of 'foo' and 'bar' write 'foo+(-bar)' or even 'foo+-bar'.
1506
1507       Here is an example of a short data file that defines some basic units:
1508
1509          m       !               # The meter is a primitive unit
1510          sec     !               # The second is a primitive unit
1511          rad     !dimensionless  # A dimensionless primitive unit
1512          micro-  1e-6            # Define a prefix
1513          minute  60 sec          # A minute is 60 seconds
1514          hour    60 min          # An hour is 60 minutes
1515          inch    0.0254 m        # Inch defined in terms of meters
1516          ft      12 inches       # The foot defined in terms of inches
1517          mile    5280 ft         # And the mile
1518
1519       A unit that ends with a '-' character is a prefix.  If a prefix defini‐
1520       tion  contains any '/' characters, be sure they are protected by paren‐
1521       theses.  If you define 'half- 1/2' then 'halfmeter' would be equivalent
1522       to '1 / (2 meter)'.
1523
1524   Defining Nonlinear Units
1525       Some  unit conversions of interest are nonlinear; for example, tempera‐
1526       ture conversions between the Fahrenheit and Celsius  scales  cannot  be
1527       done by simply multiplying by conversion factors.
1528
1529       When  you  give a linear unit definition such as 'inch 2.54 cm' you are
1530       providing information that 'units' uses to  convert  values  in  inches
1531       into  primitive units of meters.  For nonlinear units, you give a func‐
1532       tional definition that provides the same information.
1533
1534       Nonlinear units are represented using a  functional  notation.   It  is
1535       best  to  regard  this  notation not as a function call but as a way of
1536       adding units to a number, much the same way that writing a linear  unit
1537       name  after  a number adds units to that number.  Internally, nonlinear
1538       units are defined by a pair of functions that convert to and from  lin‐
1539       ear  units in the database, so that an eventual conversion to primitive
1540       units is possible.
1541
1542       Here is an example nonlinear unit definition:
1543
1544          tempF(x) units=[1;K] domain=[-459.67,) range=[0,) \
1545                      (x+(-32)) degF + stdtemp ; (tempF+(-stdtemp))/degF + 32
1546
1547       A nonlinear unit definition comprises a unit name, a  formal  parameter
1548       name, two functions, and optional specifications for units, the domain,
1549       and the range (the domain of the inverse function).  The functions tell
1550       'units'  how  to  convert  to  and from the new unit.  To produce valid
1551       results, the arguments of these functions  need  to  have  the  correct
1552       dimensions  and  be  within  the  domains  for  which the functions are
1553       defined.
1554
1555       The definition begins with the unit name followed immediately (with  no
1556       spaces) by a '(' character.  In the parentheses is the name of the for‐
1557       mal parameter.  Next is an optional specification of the units required
1558       by  the  functions  in  the  definition.   In  the  example  above, the
1559       'units=[1;K]'  specification  indicates  that  the   'tempF'   function
1560       requires  an input argument conformable with '1' (i.e., the argument is
1561       dimensionless), and that the inverse function requires an  input  argu‐
1562       ment  conformable with 'K'.  For normal nonlinear units definition, the
1563       forward function will always take a dimensionless argument; in general,
1564       the  inverse  function will need units that match the quantity measured
1565       by your nonlinear unit.  Specifying the units enables 'units'  to  per‐
1566       form  error checking on function arguments, and also to assign units to
1567       domain and range specifications, which are described later.
1568
1569       Next the function  definitions  appear.   In  the  example  above,  the
1570       'tempF' function is defined by
1571
1572          tempF(x) = (x+(-32)) degF + stdtemp
1573
1574       This  gives  a  rule  for converting 'x' in the units 'tempF' to linear
1575       units of absolute temperature, which makes it possible to convert  from
1576       tempF to other units.
1577
1578       To  enable  conversions  to  Fahrenheit,  you  must give a rule for the
1579       inverse conversions.  The inverse will be 'x(tempF)' and its definition
1580       appears after a ';' character.  In our example, the inverse is
1581
1582          x(tempF) = (tempF+(-stdtemp))/degF + 32
1583
1584       This  inverse  definition takes an absolute temperature as its argument
1585       and converts it to the Fahrenheit  temperature.   The  inverse  can  be
1586       omitted  by  leaving  out the ';' character and the inverse definition,
1587       but then conversions to the unit will not be possible.  If the  inverse
1588       definition is omitted, the '--check' option will display a warning.  It
1589       is up to you to calculate and enter the  correct  inverse  function  to
1590       obtain  proper  conversions;  the '--check' option tests the inverse at
1591       one point and prints an error if it is not valid there, but this is not
1592       a guarantee that your inverse is correct.
1593
1594       With some definitions, the units may vary.  For example, the definition
1595
1596          square(x)       x^2
1597
1598       can  have  any  arbitrary  units, and can also take dimensionless argu‐
1599       ments.  In such a case, you should not specify units.  If a  definition
1600       takes  a  root of its arguments, the definition is valid only for units
1601       that yield such a root.  For example,
1602
1603          squirt(x)       sqrt(x)
1604
1605       is valid for a dimensionless argument, and for arguments with even pow‐
1606       ers of units.
1607
1608       Some definitions may not be valid for all real numbers.  In such cases,
1609       'units' can handle errors better if you specify an  appropriate  domain
1610       and range.  You specify the domain and range as shown below:
1611
1612          baume(d) units=[1;g/cm^3] domain=[0,130.5] range=[1,10] \
1613                   (145/(145-d)) g/cm^3 ; (baume+-g/cm^3) 145 / baume
1614
1615       In  this  example the domain is specified after 'domain=' with the end‐
1616       points given in brackets.   In  accord  with  mathematical  convention,
1617       square  brackets indicate a closed interval (one that includes its end‐
1618       points), and parentheses indicate an open interval (one that  does  not
1619       include  its  endpoints).   An interval can be open or closed on one or
1620       both ends; an interval that is unbounded on either end is indicated  by
1621       omitting the limit on that end.  For example, a quantity to which deci‐
1622       bel (dB) is applied may have any value greater than zero, so the  range
1623       is indicated by '(0,)':
1624
1625          decibel(x) units=[1;1] range=(0,) 10^(x/10); 10 log(decibel)
1626
1627       If  the  domain  or range is given, the second endpoint must be greater
1628       than the first.
1629
1630       The domain and range specifications can appear independently and in any
1631       order  along  with  the units specification.  The values for the domain
1632       and range endpoints are attached to the units given in the units speci‐
1633       fication, and if necessary, the parameter value is adjusted for compar‐
1634       ison with  the  endpoints.   For  example,  if  a  definition  includes
1635       'units=[1;ft]'  and  'range=[3,)',  the  range will be taken as 3 ft to
1636       infinity.  If the function is passed  a  parameter  of  '900 mm',  that
1637       value  will be adjusted to 2.9527559 ft, which is outside the specified
1638       range.  If you omit the units specification from the previous  example,
1639       'units'  can  not tell whether you intend the lower endpoint to be 3 ft
1640       or 3 microfurlongs, and can not adjust the parameter  value  of  900 mm
1641       for  comparison.   Without  units,  numerical values other than zero or
1642       plus or minus infinity for domain or range endpoints  are  meaningless,
1643       and accordingly they are not allowed.  If you give other values without
1644       units then the definition will be ignored and you  will  get  an  error
1645       message.
1646
1647       Although the units, domain, and range specifications are optional, it's
1648       best to give them when they are applicable; doing so allows 'units'  to
1649       perform  better  error  checking  and give more helpful error messages.
1650       Giving the domain and range also enables the '--check' option to find a
1651       point  in the domain to use for its point check of your inverse defini‐
1652       tion.
1653
1654       You can make synonyms for nonlinear units by providing both the forward
1655       and  inverse functions; inverse functions can be obtained using the '~'
1656       operator.  So to create a synonym for 'tempF' you could write
1657
1658          fahrenheit(x) units=[1;K] tempF(x); ~tempF(fahrenheit)
1659
1660       This is useful for creating a nonlinear unit  definition  that  differs
1661       slightly from an existing definition without having to repeat the orig‐
1662       inal functions.  For example,
1663
1664          dBW(x)     units=[1;W] range=[0,) dB(x) W ;  ~dB(dBW/W)
1665
1666       If you wish a synonym to refer to an existing  nonlinear  unit  without
1667       modification,  you  can  do  so  more simply by adding the synonym with
1668       appended parentheses as a new unit, with the existing  nonlinear  unit—
1669       without  parentheses—as  the  definition.   So  to create a synonym for
1670       'tempF' you could write
1671
1672          fahrenheit()  tempF
1673
1674       The definition must be a nonlinear unit; for example, the synonym
1675
1676          fahrenheit()  meter
1677
1678       will result in an error message when 'units' starts.
1679
1680       You may occasionally wish to define a function that operates on  units.
1681       This  can  be done using a nonlinear unit definition.  For example, the
1682       definition below provides conversion between radius and the area  of  a
1683       circle.   This  definition  requires  a length as input and produces an
1684       area as output, as indicated by the 'units=' specification.  Specifying
1685       the  range  as  the  nonnegative numbers can prevent cryptic error mes‐
1686       sages.
1687
1688          circlearea(r) units=[m;m^2] range=[0,)   pi r^2 ; sqrt(circlearea/pi)
1689
1690   Defining Piecewise Linear Units
1691       Sometimes you may be interested in a piecewise linear unit such as many
1692       wire  gauges.  Piecewise linear units can be defined by specifying con‐
1693       versions to linear units on a list  of  points.   Conversion  at  other
1694       points  will  be done by linear interpolation.  A partial definition of
1695       zinc gauge is
1696
1697          zincgauge[in] 1 0.002, 10 0.02, 15 0.04, 19 0.06, 23 0.1
1698
1699       In this example, 'zincgauge' is the name of the piecewise linear  unit.
1700       The  definition of such a unit is indicated by the embedded '[' charac‐
1701       ter.  After the bracket, you should indicate the units to  be  attached
1702       to the numbers in the table.  No spaces can appear before the ']' char‐
1703       acter, so a definition like 'foo[kg meters]' is invalid; instead  write
1704       'foo[kg*meters]'.   The  definition  of  the unit consists of a list of
1705       pairs optionally separated by commas.  This list defines a function for
1706       converting  from  the piecewise linear unit to linear units.  The first
1707       item in each pair is the function argument;  the  second  item  is  the
1708       value  of  the  function  at  that  argument (in the units specified in
1709       brackets).  In this example, we define 'zincgauge' at five points.  For
1710       example,  we  set 'zincgauge(1)' equal to '0.002 in'.  Definitions like
1711       this may be  more readable  if written using   continuation  characters
1712       as
1713
1714          zincgauge[in] \
1715               1 0.002  \
1716              10 0.02   \
1717              15 0.04   \
1718              19 0.06   \
1719              23 0.1
1720
1721       With  the  preceding  definition,  the following conversion can be per‐
1722       formed:
1723
1724          You have: zincgauge(10)
1725          You want: in
1726              * 0.02
1727              / 50
1728          You have: .01 inch
1729          You want: zincgauge
1730              5
1731
1732       If you define a piecewise linear unit that is not  strictly  monotonic,
1733       then the inverse will not be well defined.  If the inverse is requested
1734       for such a unit, 'units' will return the smallest inverse.
1735
1736       After adding nonlinear  units  definitions,  you  should  normally  run
1737       'units --check'  to  check  for  errors.  If the 'units' keyword is not
1738       given, the '--check' option checks a nonlinear unit definition using  a
1739       dimensionless  argument, and then checks using an arbitrary combination
1740       of units, as well as the square and cube of that combination; a warning
1741       is given if any of these tests fail.  For example,
1742
1743          Warning: function 'squirt(x)' defined as 'sqrt(x)'
1744                   failed for some test inputs:
1745                   squirt(7(kg K)^1): Unit not a root
1746                   squirt(7(kg K)^3): Unit not a root
1747
1748       Running  'units --check' will print a warning if a non-monotonic piece‐
1749       wise linear unit is encountered.  For example, the relationship between
1750       ANSI  coated  abrasive  designation and mean particle size is non-mono‐
1751       tonic in the vicinity of 800 grit:
1752
1753          ansicoated[micron] \
1754               . . .
1755              600 10.55 \
1756              800 11.5 \
1757              1000 9.5 \
1758
1759       Running 'units --check' would give the error message
1760
1761          Table 'ansicoated' lacks unique inverse around entry 800
1762
1763       Although the inverse is not well  defined  in  this  region,  it's  not
1764       really  an  error.   Viewing such error messages can be tedious, and if
1765       there are enough of them, they can distract from  true  errors.   Error
1766       checking for nonlinear unit definitions can be suppressed by giving the
1767       'noerror' keyword; for the examples above, this could be done as
1768
1769          squirt(x) noerror domain=[0,) range=[0,) sqrt(x); squirt^2
1770          ansicoated[micron] noerror \
1771               . . .
1772
1773       Use the 'noerror' keyword with  caution.   The  safest  approach  after
1774       adding  a  nonlinear unit definition is to run 'units --check' and con‐
1775       firm that there are no actual errors before adding the  'noerror'  key‐
1776       word.
1777
1778   Defining Unit List Aliases
1779       Unit  list  aliases  are  treated  differently  from  unit definitions,
1780       because they are a data entry shorthand rather than a  true  definition
1781       for  a  new unit.  A unit list alias definition begins with '!unitlist'
1782       and includes the alias and the definition;  for  example,  the  aliases
1783       included in the standard units data file are
1784
1785          !unitlist   hms     hr;min;sec
1786          !unitlist   time    year;day;hr;min;sec
1787          !unitlist   dms     deg;arcmin;arcsec
1788          !unitlist   ftin    ft;in;1|8 in
1789          !unitlist   usvol   cup;3|4 cup;2|3 cup;1|2 cup;1|3 cup;1|4 cup;\
1790                              tbsp;tsp;1|2 tsp;1|4 tsp;1|8 tsp
1791
1792       Unit  list  aliases  are  only  for  unit lists, so the definition must
1793       include a ';'.  Unit list aliases can never be combined with  units  or
1794       other  unit list aliases, so the definition of 'time' shown above could
1795       not have been shortened to 'year;day;hms'.
1796
1797       As usual, be sure to run  'units --check'  to  ensure  that  the  units
1798       listed in unit list aliases are conformable.
1799

NUMERIC OUTPUT FORMAT

1801       By  default, 'units' shows results to eight significant digits. You can
1802       change this with the '--exponential', '--digits', and '--output-format'
1803       options.   The first sets an exponential format (i.e., scientific nota‐
1804       tion) like that used in the original Unix 'units' program,  the  second
1805       allows you to specify a different number of significant digits, and the
1806       last allows you to control the output appearance using the  format  for
1807       the  'printf()'  function  in  the C programming language.  If you only
1808       want to change the number of significant digits or specify  exponential
1809       format  type,  use  the  '--digits'  and  '--exponential' options.  The
1810       '--output-format' option affords the greatest  control  of  the  output
1811       appearance,   but  requires  at  least  rudimentary  knowledge  of  the
1812       'printf()' format syntax. See Invoking Units for descriptions of  these
1813       options.
1814
1815   Format Specification
1816       The  format  specification recognized with the '--output-format' option
1817       is a subset of that for 'printf()'.  The format specification  has  the
1818       form  '%'[flags][width]['.'precision]type;  it must begin with '%', and
1819       must end with a floating-point type specifier: 'g' or  'G'  to  specify
1820       the  number  of significant digits, 'e' or 'E' for scientific notation,
1821       and 'f' for fixed-point decimal.  The ISO C99 standard  added  the  'F'
1822       type  for fixed-point decimal and the 'a' and 'A' types for hexadecimal
1823       floating point; these types are allowed  with  compilers  that  support
1824       them.   Type length modifiers (e.g., 'L' to indicate a long double) are
1825       inapplicable and are not allowed.
1826
1827       The default format for 'units' is '%.8g'; for  greater  precision,  you
1828       could specify '-o %.15g'.  The 'g' and 'G' format types use exponential
1829       format whenever the exponent would  be  less  than  -4,  so  the  value
1830       0.000013  displays  as  '1.3e-005'.   These  types also use exponential
1831       notation when the exponent is greater than or equal to  the  precision,
1832       so  with  the  default format, the value 5e7 displays as '50000000' and
1833       the value 5e8 displays as '5e+008'.  If you prefer fixed-point display,
1834       you  might  specify '-o %.8f'; however, small numbers will display very
1835       few significant digits, and values less than 0.5e-8 will  show  nothing
1836       but zeros.
1837
1838       The  format  specification may include one or more optional flags: '+',
1839       ' ' (space), '#', '-', or '0' (the  digit  zero).   The  digit-grouping
1840       flag ''' is allowed with compilers that support it.  Flags are followed
1841       by an optional value for the minimum field width, and an optional  pre‐
1842       cision specification that begins with a period (e.g., '.6').  The field
1843       width includes the digits, decimal point, the exponent, thousands sepa‐
1844       rators (with the digit-grouping flag), and the sign if any of these are
1845       shown.
1846
1847   Flags
1848       The '+' flag causes the output to have a sign ('+' or '-').  The  space
1849       flag ' ' is similar to the '+' flag, except that when the value is pos‐
1850       itive, it is prefixed with a space rather than a plus sign;  this  flag
1851       is ignored if the '+' flag is also given.  The '+' or ' ' flag could be
1852       useful if conversions might include positive and negative results,  and
1853       you  wanted  to  align the decimal points in exponential notation.  The
1854       '#' flag causes the output value to contain  a  decimal  point  in  all
1855       cases;  by  default,  the output contains a decimal point only if there
1856       are digits (which can be trailing zeros) to the  right  of  the  point.
1857       With  the  'g' or 'G' types, the '#' flag also prevents the suppression
1858       of trailing zeros.  The digit-grouping flag ''' shows a thousands sepa‐
1859       rator  in  digits to the left of the decimal point.  This can be useful
1860       when displaying large numbers in fixed-point decimal; for example, with
1861       the format '%f',
1862
1863          You have: mile
1864          You want: microfurlong
1865                  * 8000000.000000
1866                  / 0.000000
1867
1868       the  magnitude of the first result may not be immediately obvious with‐
1869       out counting the digits to the left of the decimal point.  If the thou‐
1870       sands  separator  is  the comma (','), the output with the format '%'f'
1871       might be
1872
1873          You have: mile
1874          You want: microfurlong
1875                  * 8,000,000.000000
1876                  / 0.000000
1877
1878       making the magnitude readily apparent.   Unfortunately,  few  compilers
1879       support the digit-grouping flag.
1880
1881       With  the  '-' flag, the output value is left aligned within the speci‐
1882       fied field width.  If a field width greater than  needed  to  show  the
1883       output  value is specified, the '0' (zero) flag causes the output value
1884       to be left padded  with  zeros  until  the  specified  field  width  is
1885       reached; for example, with the format '%011.6f',
1886
1887          You have: troypound
1888          You want: grain
1889                  * 5760.000000
1890                  / 0000.000174
1891
1892       The '0' flag has no effect if the '-' (left align) flag is given.
1893
1894   Field Width
1895       By default, the output value is left aligned and shown with the minimum
1896       width necessary for the specified (or default) precision.  If  a  field
1897       width greater than this is specified, the value shown is right aligned,
1898       and padded on the left with enough  spaces  to  provide  the  specified
1899       field  width.  A width specification is typically used with fixed-point
1900       decimal to have columns of numbers align at  the  decimal  point;  this
1901       arguably  is  less  useful with 'units' than with long columnar output,
1902       but it may nonetheless assist in quickly assessing the relative  magni‐
1903       tudes of results.  For example, with the format '%12.6f',
1904
1905          You have: km
1906          You want: in
1907                  * 39370.078740
1908                  /     0.000025
1909          You have: km
1910          You want: rod
1911                  *   198.838782
1912                  /     0.005029
1913          You have: km
1914          You want: furlong
1915                  *     4.970970
1916                  /     0.201168
1917
1918   Precision
1919       The  meaning  of ``precision'' depends on the format type.  With 'g' or
1920       'G', it specifies the number of significant digits (like the '--digits'
1921       option); with 'e', 'E', 'f', or 'F', it specifies the maximum number of
1922       digits to be shown after the decimal point.
1923
1924       With the 'g' and 'G' format types, trailing zeros  are  suppressed,  so
1925       the  results  may sometimes have fewer digits than the specified preci‐
1926       sion (as indicated above, the '#' flag causes trailing zeros to be dis‐
1927       played).
1928
1929       The  default precision is 6, so '%g' is equivalent to '%.6g', and would
1930       show the output to six significant digits.   Similarly,  '%e'  or  '%f'
1931       would show the output with six digits after the decimal point.
1932
1933       The C 'printf()' function allows a precision of arbitrary size, whether
1934       or not all of the digits are meaningful.  With most compilers, the max‐
1935       imum  internal precision with 'units' is 15 decimal digits (or 13 hexa‐
1936       decimal digits).  With the '--digits' option, you are  limited  to  the
1937       maximum  internal precision; with the '--output-format' option, you may
1938       specify a precision greater than this, but it may  not  be  meaningful.
1939       In some cases, specifying excess precision can result in rounding arti‐
1940       facts.  For example, a pound is exactly 7000 grains, but with the  for‐
1941       mat '%.18g', the output might be
1942
1943          You have: pound
1944          You want: grain
1945                  * 6999.9999999999991
1946                  / 0.00014285714285714287
1947
1948       With the format '%.25g' you might get the following:
1949
1950          You have: 1/3
1951          You want:
1952                  Definition: 0.333333333333333314829616256247
1953
1954       In  this case the displayed value includes a series of digits that rep‐
1955       resent the underlying binary floating-point approximation  to  1/3  but
1956       are not meaningful for the desired computation.  In general, the result
1957       with excess precision is system dependent.  The precision affects  only
1958       the  display  of numbers; if a result relies on physical constants that
1959       are not known to the specified  precision,  the  number  of  physically
1960       meaningful digits may be less than the number of digits shown.
1961
1962       See  the documentation for 'printf()' for more detailed descriptions of
1963       the format specification.
1964
1965       The '--output-format' option is incompatible with  the  '--exponential'
1966       or  '--digits'  options;  if  the  former  is given in combination with
1967       either of the latter, the format  is  controlled  by  the  last  option
1968       given.
1969

LOCALIZATION

1971       Some units have different values in different locations.  The localiza‐
1972       tion feature accommodates this by allowing a units data file to specify
1973       definitions that depend on the user's locale.
1974
1975   Locale
1976       A  locale is a subset of a user's environment that indicates the user's
1977       language and country, and some attendant preferences, such as the  for‐
1978       matting of dates.  The 'units' program attempts to determine the locale
1979       from the POSIX setlocale function; if  this  cannot  be  done,  'units'
1980       examines  the  environment  variables  'LC_CTYPE' and 'LANG'.  On POSIX
1981       systems, a locale is of the form language'_'country, where language  is
1982       the  two-character code from ISO 639-1 and country is the two-character
1983       code from ISO 3166-1; language is lower case and country is upper case.
1984       For example, the POSIX locale for the United Kingdom is 'en_GB'.
1985
1986       On systems running Microsoft Windows, the value returned by setlocale()
1987       is different from that on POSIX systems; 'units' attempts  to  map  the
1988       Windows  value  to  a  POSIX  value  by  means  of  a table in the file
1989       'locale_map.txt' in the same directory as the other  data  files.   The
1990       file  includes  entries  for many combinations of language and country,
1991       and   can   be   extended   to   include   other   combinations.    The
1992       'locale_map.txt'  file  comprises two tab-separated columns; each entry
1993       is of the form
1994
1995          Windows-locale   POSIX-locale
1996
1997       where POSIX-locale is as described above, and Windows-locale  typically
1998       spells  out  both the language and country.  For example, the entry for
1999       the United States is
2000
2001          English_United States   en_US
2002
2003       You can force 'units' to run in a desired  locale  by  using  the  '-l'
2004       option.
2005
2006       In order to create unit definitions for a particular locale you begin a
2007       block of definitions in a unit datafile with '!locale'  followed  by  a
2008       locale  name.   The  '!'  must be the first character on the line.  The
2009       'units' program reads the following definitions  only  if  the  current
2010       locale   matches.    You   end   the  block  of  localized  units  with
2011       '!endlocale'.  Here is an example, which defines the British gallon.
2012
2013          !locale en_GB
2014          gallon       4.54609 liter
2015          !endlocale
2016
2017   Additional Localization
2018       Sometimes the locale isn't sufficient to  determine  unit  preferences.
2019       There  could  be regional preferences, or a company could have specific
2020       preferences.  Though probably uncommon, such  differences  could  arise
2021       with  the choice of English customary units outside of English-speaking
2022       countries.  To address this, 'units' allows specifying definitions that
2023       depend on environment variable settings.  The environment variables can
2024       be controled based on the current locale, or the user can set  them  to
2025       force a particular group of definitions.
2026
2027       A  conditional  block  of  definitions in a units data file begins with
2028       either '!var' or '!varnot' following by an  environment  variable  name
2029       and  then  a  space  separated  list  of values.  The leading '!'  must
2030       appear in the first column of a units data file,  and  the  conditional
2031       block is terminated by '!endvar'.  Definitions in blocks beginning with
2032       '!var' are executed only if the environment variable is  exactly  equal
2033       to  one  of  the  listed  values.  Definitions in blocks beginning with
2034       '!varnot' are executed only if the environment variable does not  equal
2035       any of the list values.
2036
2037       The  inch  has  long been a customary measure of length in many places.
2038       The word comes from the latin uncia meaning ``one twelfth,''  referring
2039       to  its  relationship with the foot.  By the 20th century, the inch was
2040       officially defined in English-speaking countries relative to the  yard,
2041       but  until  1959, the yard differed slightly among those countries.  In
2042       France the customary inch, which was displaced in 1799  by  the  meter,
2043       had a different length based on a french foot.  These customary defini‐
2044       tions could be accommodated as follows:
2045
2046          !var INCH_UNIT usa
2047          yard          3600|3937 m
2048          !endvar
2049          !var INCH_UNIT canada
2050          yard          0.9144 meter
2051          !endvar
2052          !var INCH_UNIT uk
2053          yard          0.91439841 meter
2054          !endvar
2055          !var INCH_UNIT canada uk usa
2056          foot          1|3 yard
2057          inch          1|12 foot
2058          !endvar
2059          !var INCH_UNIT france
2060          foot          144|443.296 m
2061          inch          1|12 foot
2062          line          1|12 inch
2063          !endvar
2064          !varnot INCH_UNIT usa uk france canada
2065          !message Unknown value for INCH_UNIT
2066          !endvar
2067
2068       When 'units' reads the above definitions it will check the  environment
2069       variable  'INCH_UNIT' and load only the definitions for the appropriate
2070       section.  If 'INCH_UNIT' is unset or is not set to one of the four val‐
2071       ues  listed  then  'units'  will run the last block.  In this case that
2072       block uses the '!message' command to display a warning message.  Alter‐
2073       natively that block could set default values.
2074
2075       In  order to create default values that are overridden by user settings
2076       the data file can use the '!set' command,  which  sets  an  environment
2077       variable  only  if  it is not already set;  these settings are only for
2078       the current 'units' invocation and do not persist.  So if  the  example
2079       above  were  preceded  by  '!set INCH_UNIT france' then this would make
2080       'france' the default value for 'INCH_UNIT'.  If the user  had  set  the
2081       variable in the environment before invoking 'units', then 'units' would
2082       use the user's value.
2083
2084       To link these settings to the user's locale you combine the '!set' com‐
2085       mand  with  the  '!locale' command.  If you wanted to combine the above
2086       example with suitable locales you could do by preceding the above defi‐
2087       nition with the following:
2088
2089          !locale en_US
2090          !set INCH_UNIT usa
2091          !endlocale
2092          !locale en_GB
2093          !set INCH_UNIT uk
2094          !endlocale
2095          !locale en_CA
2096          !set INCH_UNIT canada
2097          !endlocale
2098          !locale fr_FR
2099          !set INCH_UNIT france
2100          !endlocale
2101          !set INCH_UNIT france
2102
2103       These  definitions  set the overall default for 'INCH_UNIT' to 'france'
2104       and set default values for four  locales  appropriately.   The  overall
2105       default setting comes last so that it only applies when 'INCH_UNIT' was
2106       not set by one of the other commands or by the user.
2107
2108       If the variable given after  '!var'  or  '!varnot'  is  undefined  then
2109       'units'  prints  an error message and ignores the definitions that fol‐
2110       low.  Use '!set' to create defaults  to  prevent  this  situation  from
2111       arising.   The  '-c' option only checks the definitions that are active
2112       for the current environment and locale, so when adding new  definitions
2113       take  care  to  check that all cases give rise to a well defined set of
2114       definitions.
2115

ENVIRONMENT VARIABLES

2117       The 'units' program uses the following environment variables:
2118
2119       HOME   Specifies the location of your home directory;  it  is  used  by
2120              'units' to find a personal units data file '.units'.  On systems
2121              running Microsoft Windows, the file is 'unitdef.units',  and  if
2122              'HOME'  does  not  exist,  'units'  tries to determine your home
2123              directory from the 'HOMEDRIVE' and 'HOMEPATH' environment  vari‐
2124              ables;  if  these  variables  do  not exist, units finally tries
2125              'USERPROFILE'—typically 'C:\Users\username' (Windows  Vista  and
2126              Windows 7) or 'C:\Documents and Settings\username' (Windows XP).
2127
2128       LC_CTYPE, LANG
2129              Checked to determine the locale if 'units' cannot obtain it from
2130              the operating system.  Sections of the standard units data  file
2131              are specific to certain locales.
2132
2133       MYUNITSFILE
2134              Specifies  your  personal  units  data  file.   If this variable
2135              exists, 'units' uses its value rather than searching  your  home
2136              directory  for  '.units'.   The  personal units file will not be
2137              loaded if any data files are given using the '-f' option.
2138
2139       PAGER  Specifies the pager to use for help and for displaying the  con‐
2140              formable  units.   The  help function browses the units database
2141              and calls the pager using the '+n'n syntax for specifying a line
2142              number.   The  default  pager  is 'more'; 'PAGER' can be used to
2143              specify alternatives such as 'less', 'pg', 'emacs', or 'vi'.
2144
2145       UNITS_ENGLISH
2146              Set to either 'US' or 'GB' to choose United  States  or  British
2147              volume definitions, overriding the default from your locale.
2148
2149       UNITSFILE
2150              Specifies  the  units data file to use (instead of the default).
2151              You can only specify a single units data file using  this  envi‐
2152              ronment  variable.  If units data files are given using the '-f'
2153              option, the file specified by 'UNITSFILE' will be not be  loaded
2154              unless   the   '-f'  option  is  given  with  the  empty  string
2155              ('units -f ""').
2156
2157       UNITSLOCALEMAP
2158              Windows only; this variable has no effect on Unix-like  systems.
2159              Specifies  the  units  locale  map  file  to use (instead of the
2160              default).  This variable seldom needs to be set, but you can use
2161              it to ensure that the locale map file will be found if you spec‐
2162              ify a location for the units data file  using  either  the  '-f'
2163              option  or  the 'UNITSFILE' environment variable, and that loca‐
2164              tion does not also contain the locale map file.
2165

DATA FILES

2167       The 'units' program uses two default  data  files:  'definitions.units'
2168       and  'currency.units'.   The  program can also use an optional personal
2169       units data file '.units' ('unitdef.units' under Windows) located in the
2170       user's  home  directory.   The personal units data file is described in
2171       more detail in Units Data Files.
2172
2173       On  Unix-like  systems,  the  data  files  are  typically  located   in
2174       '/usr/share/units' if 'units' is provided with the operating system, or
2175       in '/usr/local/share/units' if 'units' is compiled from the source dis‐
2176       tribution.   Note that the currency file 'currency.units' is a symbolic
2177       link to another location.
2178
2179       On systems running Microsoft Windows, the files  may  be  in  the  same
2180       locations  if Unix-like commands are available, a Unix-like file struc‐
2181       ture is present (e.g., 'C:/usr/local'), and 'units'  is  compiled  from
2182       the  source  distribution.   If Unix-like commands are not available, a
2183       more common location is 'C:\Program Files (x86)\GNU\units' (for  64-bit
2184       Windows  installations)  or  'C:\Program Files\GNU\units'  (for  32-bit
2185       installations).
2186
2187       If   'units'   is    obtained    from    the    GNU    Win32    Project
2188       (http://gnuwin32.sourceforge.net/),   the   files   are   commonly   in
2189       'C:\Program Files\GnuWin32\share\units'.
2190
2191       If the default units data file is not  an  absolute  pathname,  'units'
2192       will  look for the file in the directory that contains the 'units' pro‐
2193       gram; if the file is not found there, 'units' will look in a  directory
2194       '../share/units' relative to the directory with the 'units' program.
2195
2196       You   can   determine   the   location   of   the   files   by  running
2197       'units --version'.  Running 'units --info'  will  give  you  additional
2198       information about the files, how 'units' will attempt to find them, and
2199       the status of the related environment variables.
2200

UNICODE SUPPORT

2202       The standard units data file is in Unicode, using UTF-8 encoding.  Most
2203       definitions use only ASCII characters (i.e., code points U+0000 through
2204       U+007F); definitions using non-ASCII characters appear in blocks begin‐
2205       ning with '!utf8' and ending with '!endutf8'.
2206
2207       When  'units'  starts,  it checks the locale to determine the character
2208       set.  If 'units' is compiled with Unicode support and definitions; oth‐
2209       erwise  these definitions are ignored.  When Unicode support is active,
2210       'units' will check every line of  all  of  the  units  data  files  for
2211       invalid  or  non-printing  UTF-8  sequences;  if  such sequences occur,
2212       'units' ignores the entire line.  In  addition  to  checking  validity,
2213       'units'  determines the display width of non-ASCII characters to ensure
2214       proper positioning of the pointer in some error messages and  to  align
2215       columns for the 'search' and '?'  commands.
2216
2217       At  present,  'units' does not support Unicode under Microsoft Windows.
2218       The UTF-16 and UTF-32 encodings are not supported on any systems.
2219
2220       If definitions that contain non-ASCII characters are added to  a  units
2221       data  file,  those  definitions  should  be enclosed within '!utf8' ...
2222       '!endutf8' to ensure that they are only loaded when Unicode support  is
2223       available.   As  usual,  the '!'  must appear as the first character on
2224       the line.  As discussed in Units Data Files, it's usually best  to  put
2225       such  definitions  in  supplemental  data files linked by an '!include'
2226       command or in a personal units data file.
2227
2228       When Unicode support is not active, 'units' makes no assumptions  about
2229       character encoding, except that characters in the range 00-7F hexadeci‐
2230       mal correspond to ASCII  encoding.   Non-ASCII  characters  are  simply
2231       sequences  of  bytes,  and have no special meanings; for definitions in
2232       supplementary units data files, you can  use  any  encoding  consistent
2233       with  this assumption.  For example, if you wish to use non-ASCII char‐
2234       acters in definitions when running 'units' under Windows, you can use a
2235       character  set  such  as Windows ``ANSI'' (code page 1252 in the US and
2236       Western Europe).  You can even use UTF-8, though some messages  may  be
2237       improperly   aligned,   and  'units'  will  not  detect  invalid  UTF-8
2238       sequences.  If you use UTF-8  encoding  when  Unicode  support  is  not
2239       active, you should place any definitions with non-ASCII characters out‐
2240       side '!utf8' ...  '!endutf8' blocks—otherwise, they will be ignored.
2241
2242       Typeset material other than code  examples  usually  uses  the  Unicode
2243       minus  (U+2212)  rather  than  the ASCII hyphen-minus operator (U+002D)
2244       used in 'units'; the figure dash (U+2012) and en dash (U+2013) are also
2245       occasionally  used.  To allow such material to be copied and pasted for
2246       interactive use or in units data files, 'units' converts these  charac‐
2247       ters  to  U+002D  before  further processing.  Because of this, none of
2248       these characters can appear in unit names.
2249

READLINE SUPPORT

2251       If the 'readline' package has been compiled in, then  when  'units'  is
2252       used  interactively,  numerous command line editing features are avail‐
2253       able.  To check if your version of 'units' includes 'readline',  invoke
2254       the program with the '--version' option.
2255
2256       For  complete  information  about 'readline', consult the documentation
2257       for the 'readline' package.  Without any  configuration,  'units'  will
2258       allow  editing  in  the style of emacs.  Of particular use with 'units'
2259       are the completion commands.
2260
2261       If you type a few characters and then hit ESC  followed  by  '?'   then
2262       'units'  will display a list of all the units that start with the char‐
2263       acters typed.  For example, if you type 'metr' and then request comple‐
2264       tion, you will see something like this:
2265
2266          You have: metr
2267          metre             metriccup         metrichorsepower  metrictenth
2268          metretes          metricfifth       metricounce       metricton
2269          metriccarat       metricgrain       metricquart       metricyarncount
2270          You have: metr
2271
2272       If  there  is  a unique way to complete a unitname, you can hit the TAB
2273       key and 'units' will provide the rest of the  unit  name.   If  'units'
2274       beeps,  it  means that there is no unique completion.  Pressing the TAB
2275       key a second time will print the list of all completions.
2276
2277       The readline library also keeps a history of the values you enter.  You
2278       can  move  through this history using the up and down arrows.  The his‐
2279       tory is saved to the file '.units_history' in your  home  directory  so
2280       that  it will persist across multiple 'units' invocations.  If you wish
2281       to keep work for a certain project separate you can change the  history
2282       filename using the '--history' option.  You could, for example, make an
2283       alias for 'units' to 'units --history .units_history' so  that  'units'
2284       would  save  separate  history in the current directory.  The length of
2285       each history file is limited to 5000 lines.  Note also that if you  run
2286       several concurrent copies of 'units' each one will save its new history
2287       to the history file upon exit.
2288

UPDATING CURRENCY EXCHANGE RATES

2290       The units program includes currency exchange rates and prices for  some
2291       precious  metals  in the database.  Of course, these values change over
2292       time, sometimes very rapidly, and 'units' cannot provide real time val‐
2293       ues.   To update the exchange rates run the 'units_cur', which rewrites
2294       the    file    containing     the     currency     rates,     typically
2295       '/var/lib/units/currency.units'                                      or
2296       'usr/local/com/units/currency.units'.  This program requires  'python',
2297       and  must  be run with suitable permissions to write the file.  To keep
2298       the rates updated automatically, run it using a cron job on a Unix-like
2299       system,  or  a  similar scheduling program on a different system.  Cur‐
2300       rency exchange rates are taken  from  Yahoo  (http://finance.yahoo.com)
2301       and  precious  metals  pricing  from  Packetizer  (www.packetizer.com).
2302       These sites update once per day, so there is no benefit in running  the
2303       update  script  more  often than daily.  You can run 'units_cur' with a
2304       filename specified on the command line and it will write  the  data  to
2305       that file.  If you give '-' for the file it will write to standard out‐
2306       put.
2307

DATABASE COMMAND SYNTAX

2309       unit definition
2310              Define a regular unit.
2311
2312       prefix- definition
2313              Define a prefix.
2314
2315       funcname(var)   noerror    units=[in-units,out-units]    domain=[x1,x2]
2316       range=[y1,y2] definition(var) ; inverse(funcname)
2317              Define  a  nonlinear  unit  or unit function.  The four optional
2318              keywords 'noerror', 'units=', 'range=' and 'domain=' can  appear
2319              in any order.  The definition of the inverse is optional.
2320
2321       tabname[out-units] noerror pair-list
2322              Define  a piecewise linear unit.  The pair list gives the points
2323              on the table listed in ascending order.  The  'noerror'  keyword
2324              is optional.
2325
2326       !endlocale
2327              End a block of definitions beginning with '!locale'
2328
2329       !endutf8
2330              End a block of definitions begun with '!utf8'
2331
2332       !endvar
2333              End a block of definitions begun with '!var' or '!varnot'
2334
2335       !include file
2336              Include the specified file.
2337
2338       !locale value
2339              Load  the  following  definitions  only  of the locale is set to
2340              value.
2341
2342       !message text
2343              Display text when the database is read unless the  quiet  option
2344              ('-q') is enabled.
2345
2346       !set variable value
2347              Sets  the environment variable, variable, to the specified value
2348              only if it is not already set.
2349
2350       !unitlist alias definition
2351              Define a unit list alias.
2352
2353       !utf8  Load the following definitions only if 'units' is  running  with
2354              UTF-8 enabled.
2355
2356       !var envar value-list
2357              Load  the block of definitions that follows only if the environ‐
2358              ment variable envar is set to one of the values  listed  in  the
2359              space-separated value list.  If envar is not set, 'units' prints
2360              an error message and ignores the block of definitions.
2361
2362       !varnot envar value-list
2363              Load the block of definitions that follows only if the  environ‐
2364              ment  variable  envar  is set to value that is not listed in the
2365              space-separated value list.  If envar is not set, 'units' prints
2366              an error message and ignores the block of definitions.
2367

GNU FREE DOCUMENTATION LICENSE

FILES

2370       /usr/share/units/definitions.units — the standard units data file
2371

AUTHOR

2373                                16 October 2017                       UNITS(1)
Impressum