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

NAME

6       units - unit conversion program
7

OVERVIEW OF `UNITS'

9       The  `units' program converts quantities expressed in various scales to
10       their equivalents in other scales.  The `units' program can handle mul‐
11       tiplicative  scale  changes  as  well  as nonlinear conversions such as
12       Fahrenheit to Celsius.  Temperature conversions require a special  syn‐
13       tax.  See the examples below.
14
15       The units are defined in an external data file.  You can use the exten‐
16       sive data file that comes with this program, or you  can  provide  your
17       own data file to suit your needs.
18
19       You  can  use the program interactively with prompts, or you can use it
20       from the command line.
21

INTERACTING WITH `UNITS'

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

USING `UNITS' NON-INTERACTIVELY

154       The `units' program can  perform  units  conversions  non-interactively
155       from the command line.  To do this, type the command, type the original
156       units expression, and type the new units you want.  You  will  probably
157       need  to protect the units expressions from interpretation by the shell
158       using single quote characters.
159
160       If you type
161
162           units '2 liters' 'quarts'
163
164       then `units' will print
165
166               * 2.1133764
167               / 0.47317647
168
169       and then exit.  The output tells you that 2 liters is about 2.1 quarts,
170       or alternatively that a quart is about 0.47 times 2 liters.
171
172       If  the  conversion is successful, then `units' will return success (0)
173       to the calling environment.  If `units' is given non-conformable  units
174       to  convert,  it  will  print a message giving the reduced form of each
175       unit and it will return failure (nonzero) to the calling environment.
176
177       When `units' is invoked with only one argument, it will print  out  the
178       definition  of  the specified unit.  It will return failure if the unit
179       is not defined and success if the unit is defined.
180

UNIT EXPRESSIONS

182       In order to enter more complicated units or fractions, you will need to
183       use  operations such as powers, products and division.  Powers of units
184       can be specified using the `^' character  as  shown  in  the  following
185       example, or by simple concatenation: `cm3' is equivalent to `cm^3'.  If
186       the exponent is more than one digit, the `^' is required.  An  exponent
187       like `2^3^2' is evaluated right to left.  The `^' operator has the sec‐
188       ond highest precedence.  The `**' operator is provided as  an  alterna‐
189       tive exponent operator.
190
191           You have: cm^3
192           You want: gallons
193                   * 0.00026417205
194                   / 3785.4118
195
196           You have: arabicfoot * arabictradepound * force
197           You want: ft lbf
198                   * 0.7296
199                   / 1.370614
200
201       Multiplication  of units can be specified by using spaces, or an aster‐
202       isk (`*').  If `units' is invoked with the `--product' option then  the
203       hyphen (`-') also acts as a multiplication operator.  Division of units
204       is indicated by the slash (`/') or by `per'.
205
206           You have: furlongs per fortnight
207           You want: m/s
208                   * 0.00016630986
209                   / 6012.8727
210
211       Historically, multiplication in units was assigned a higher  precedence
212       than  division.   This  disagrees with the usual precedence rules which
213       give multiplication and division equal precedence, and it  has  been  a
214       source of confusion for people who think of units as a calculator.
215
216       By default, multiplication using the star (`*') now has the same prece‐
217       dence as division and hence follows the  usual  precedence  rules.   If
218       units  is  invoked  with  the  the `--oldstar' option then then the old
219       behavior is activated and `*' will have  the  same  precedence  as  the
220       other multiplication operators described next.
221
222       Multiplication  using  a  space or using the hyphen has a higher prece‐
223       dence than division and is  evaluated  left  to  right.   So  @samp{m/s
224       s/day}  is equivalent to `m / s s day' and has dimensions of length per
225       time cubed.  Similarly, `1/2 meter' refers  to  a  unit  of  reciprocal
226       length  equivalent  to  .5/meter,  which is probably not what you would
227       intend if you entered that expression.
228
229       You can indicate division of numbers with the vertical dash  (`|'),  so
230       if  you  wanted  half  a  meter you could write @samp{1|2 meter}.  This
231       operator has the highest precedence so the square root  of  two  thirds
232       could be written `2|3^1|2'.
233
234           You have: 1|2 inch
235           You want: cm
236                   * 1.27
237                   / 0.78740157
238
239       Parentheses can be used for grouping as desired.
240
241           You have: (1/2) kg / (kg/meter)
242           You want: league
243                   * 0.00010356166
244                   / 9656.0833
245
246       Prefixes  are defined separately from base units.  In order to get cen‐
247       timeters, the units database defines `centi-'  and  `c-'  as  prefixes.
248       Prefixes  can  appear  alone  with no unit following them.  An exponent
249       applies only to the immediately preceding unit and its prefix  so  that
250       `cm^3' or `centimeter^3' refer to cubic centimeters but `centi*meter^3'
251       refers to hundredths of cubic meters.  Only one prefix is permitted per
252       unit, so `micromicrofarad' will fail, but `micro*microfarad' will work,
253       as will `micro microfarad'..
254
255       For `units', numbers are just another kind of unit.  They can appear as
256       many  times  as  you  like  and in any order in a unit expression.  For
257       example, to find the volume of a box which is 2 ft by 3 ft by 12 ft  in
258       steres, you could do the following:
259
260           You have: 2 ft 3 ft 12 ft
261           You want: stere
262                   * 2.038813
263                   / 0.49048148
264
265           You have: $ 5 / yard
266           You want: cents / inch
267                   * 13.888889
268                   / 0.072
269
270       And  the  second example shows how the dollar sign in the units conver‐
271       sion can precede the five.  Be careful:  `units'  will  interpret  `$5'
272       with no space as equivalent to dollars^5.
273
274       Outside  of  the SI system, it is often desirable to add values of dif‐
275       ferent units together.  You may also wish to use `units' as a  calcula‐
276       tor  that  keeps track of units.  Sums of conformable units are written
277       with the `+' character.
278
279           You have: 2 hours + 23 minutes + 32 seconds
280           You want: seconds
281                   * 8612
282                   / 0.00011611705
283
284           You have: 12 ft + 3 in
285           You want: cm
286                   * 373.38
287                   / 0.0026782366
288
289           You have: 2 btu + 450 ft lbf
290           You want: btu
291                   * 2.5782804
292                   / 0.38785542
293
294       The expressions which are  added  together  must  reduce  to  identical
295       expressions in primitive units, or an error message will be displayed:
296
297           You have: 12 printerspoint + 4 heredium
298                                                 ^
299           Illegal sum of non-conformable units
300
301       Historically `-' has been used for products of units, which complicates
302       its iterpretation in `units'.  Because `units' provides  several  other
303       ways to obtain unit products, and because `-' is a subtraction operator
304       in general algebraic expressions, `units' treats the binary  `-'  as  a
305       subtraction  operator  by  default.  This behavior can be altered using
306       the `--product' option which causes `units' to  treat  the  binary  `-'
307       operator as a product operator.  Note that when `-' is a multiplication
308       operator it has the same precedence as `*', but when `-' is a  subtrac‐
309       tion operator it has the lower precedence as the addition operator.
310
311       When  `-'  is used as a unary operator it negates its operand.  Regard‐
312       less of the `units' options, if `-' appears after `(' or after `+' then
313       it  will  act  as  a  negation  operator.  So you can always compute 20
314       degrees minus 12 minutes by entering `20 degrees +  -12  arcmin'.   You
315       must use this construction when you define new units because you cannot
316       know what options will be in force when your definition is processed.
317
318       The `+' character sometimes appears in exponents like `3.43e+8'.   This
319       leads to an ambiguity in an expression like `3e+2 yC'.  The unit `e' is
320       a small unit of charge, so  this  can  be  regarded  as  equivalent  to
321       `(3e+2)  yC'  or  `(3 e)+(2 yC)'.  This ambiguity is resolved by always
322       interpreting `+' as part of an exponent if possible.
323
324       Several built in functions are provided:  `sin',  `cos',  `tan',  `ln',
325       `log', `log2', `exp', `acos', `atan' and `asin'.  The `sin', `cos', and
326       `tan' functions require either a dimensionless argument or an  argument
327       with dimensions of angle.
328
329           You have: sin(30 degrees)
330           You want:
331                   Definition: 0.5
332
333           You have: sin(pi/2)
334           You want:
335                   Definition: 1
336
337           You have: sin(3 kg)
338                             ^
339           Unit not dimensionless
340
341       The  other  functions on the list require dimensionless arguments.  The
342       inverse trigonometric functions return  arguments  with  dimensions  of
343       angle.
344
345       If  you  wish  to take roots of units, you may use the `sqrt' or `cube‐
346       root' functions.  These functions require that the  argument  have  the
347       appropriate  root.   Higher  roots can  be obtained by using fractional
348       exponents:
349
350           You have: sqrt(acre)
351           You want: feet
352                   * 208.71074
353                   / 0.0047913202
354
355           You have: (400 W/m^2 / stefanboltzmann)^(1/4)
356           You have:
357                   Definition: 289.80882 K
358
359           You have: cuberoot(hectare)
360                                     ^
361           Unit not a root
362
363       Nonlinear units are represented using functional notation.   They  make
364       possible  nonlinear unit conversions such temperature.  This is differ‐
365       ent from the linear units that convert temperature  differences.   Note
366       the difference below.  The absolute temperature conversions are handled
367       by units starting with `temp', and you must  use  functional  notation.
368       The  temperature  differences  are done using units starting with `deg'
369       and they do not require functional notation.
370
371           You have: tempF(45)
372           You want: tempC
373                   7.2222222
374
375           You have: 45 degF
376           You want: degC
377                   * 25
378                   / 0.04
379
380       Think of `tempF(x)' not as a function but as a notation which indicates
381       that  `x'  should  have units of `tempF' attached to it.  See Nonlinear
382       units.  The first conversion shows that if it's 45  degrees  Fahrenheit
383       outside  it's  7.2  degrees  Celsius.  The second conversions indicates
384       that a change of 45 degrees Fahrenheit corresponds to a  change  of  25
385       degrees Celsius.
386
387       Some  other  examples of nonlinears units are ring size and wire gauge.
388       There are numerous different gauges and  ring  sizes.   See  the  units
389       database  for more details.  Note that wire gauges with multiple zeroes
390       are signified using negative numbers where two zeroes is -1.   Alterna‐
391       tively,  you  can  use  the  synonyms `g00', `g000', and so on that are
392       defined in the units database.
393
394           You have: wiregauge(11)
395           You want: inches
396                   * 0.090742002
397                   / 11.020255
398
399           You have: brwiregauge(g00)
400           You want: inches
401                   * 0.348
402                   / 2.8735632
403
404           You have: 1 mm
405           You want: wiregauge
406                   18.201919
407

INVOKING `UNITS'

409       You invoke `units' like this:
410
411           units [OPTIONS] [FROM-UNIT [TO-UNIT]]
412
413       If the FROM-UNIT and TO-UNIT are omitted, then  the  program  will  use
414       interactive  prompts  to  determine  which conversions to perform.  See
415       Interactive use.  If both FROM-UNIT and TO-UNIT are given, `units' will
416       print  the  result  of  that  single conversion and then exit.  If only
417       FROM-UNIT appears on the command line, `units' will display the defini‐
418       tion  of  that unit and exit.  Units specified on the command line will
419       need to be quoted to protect them  from  shell  interpretation  and  to
420       group them into two arguments.  See Command line use.
421
422       The  following  options allow you to read in an alternative units file,
423       check your units file, or change the output format:
424
425       -c, --check
426              Check that all units and prefixes defined in the units data file
427              reduce  to primitive units.  Print a list of all units that can‐
428              not be reduced.  Also display some other diagnostics about  sus‐
429              picious definitions in the units data file.  Note that only def‐
430              initions active in the current locale are checked.
431
432       --check-verbose
433              Like the `-check' option, this option prints  a  list  of  units
434              that cannot be reduced.  But to help find unit  definitions that
435              cause endless loops, it lists the units as they are checked.  If
436              `units'  hangs, then the last unit to be printed has a bad defi‐
437              nition.  Note that only definitions active in the current locale
438              are checked.
439
440       -o format, --output-format format
441              Use the specified format for numeric output.  Format is the same
442              as that for the printf function in the  ANSI  C  standard.   For
443              example, if you want more precision you might use `-o %.15g'.
444
445       -f filename, --file filename
446              Instruct  `units'  to load the units file `filename'.  If `file‐
447              name' is the empty string (`-f "') then the default  units  file
448              will  be loaded.  This enables you to load the default file plus
449              a personal units file.  Up to 25 units files may be specified on
450              the  command  line.  This option overrides the `UNITSFILE' envi‐
451              ronment variable.
452
453       -h, --help
454              Print out a summary of the options for `units'.
455
456       -m, --minus
457              Causes `-' to be interpreted as a subtraction operator.  This is
458              usually the default behavior.
459
460       -p, --product
461              Causes  `-'  to be interpreted as a multiplication operator when
462              it has two operands.  It will as a negation operator when it has
463              only  one  operand: `(-3)'.  Note that by default `-' is treated
464              as a subtraction operator.
465
466       , --oldstar Causes `*' to have the old style  precedence,  higher  than
467       the precedence of division so that `1/2*3' will equal `6'.
468
469       ,  --newstar Forces `*' to have the new (default) precedence which fol‐
470       lows the usual rules of algebra: the precedence of `*' is the  same  as
471       the precedence of `/', so that `1/2*3' will equal `3/2'.
472
473       ,  --compact  Give compact output featuring only the conversion factor.
474       This turns off the `--verbose' option.
475
476       -q, --quiet, --silent
477              Suppress prompting of the user for units and the display of sta‐
478              tistics about the number of units loaded.
479
480       -s, --strict
481              Suppress  conversion  of  units  to their reciprocal units.  For
482              example, `units' will normally convert hertz to seconds  because
483              these  units  are  reciprocals of each other.  The strict option
484              requires that units be strictly conformable to perform a conver‐
485              sion,  and will give an error if you attempt to convert hertz to
486              seconds.
487
488       -1, --one-line
489              Give only one line of output (the forward conversion).   Do  not
490              print the reverse conversion.  Note that if a reciprocal conver‐
491              sion is performed  then  `units'  will  print  still  print  the
492              "reciprocal conversion" line.
493
494       -t, --terse
495              Give  terse  output  when  converting units.  This option can be
496              used when calling `units' from another program so that the  out‐
497              put  is  easy  to parse.  This option has the combined effect of
498              these options:  `--strict' `--quiet' `--one-line' `--compact'.
499
500       -v, --verbose
501              Give slightly more verbose output when converting  units.   When
502              combined  with  the  `-c'  option  this gives the same effect as
503              `--check-verbose'.
504
505       -V, --version
506              Print program version number, tell whether the readline  library
507              has  been  included,  and give the location of the default units
508              data file.
509

UNIT DEFINITIONS

511       The conversion information is read from a  units  data  file  which  is
512       called  `units.dat'  and  is probably located in the `/usr/local/share'
513       directory.  If you invoke `units' with the `-V' option, it  will  print
514       the  location  of this file.  The default file includes definitions for
515       all  familiar  units,  abbreviations  and  metric  prefixes.   It  also
516       includes many obscure or archaic units.
517
518       Many constants of nature are defined, including these:
519
520              pi         ratio of circumference to diameter
521              c          speed of light
522              e          charge on an electron
523              force      acceleration of gravity
524              mole       Avogadro's number
525              water      pressure per unit height of water
526              Hg         pressure per unit height of mercury
527              au         astronomical unit
528
529              k          Boltzman's constant
530              mu0        permeability of vacuum
531              epsilon0   permitivity of vacuum
532              G          gravitational constant
533              mach       speed of sound
534       The  database includes atomic masses for all of the elements and numer‐
535       ous other constants.  Also included are the densities of various ingre‐
536       dients used in baking so that `2 cups flour_sifted' can be converted to
537       `grams'.  This is not an exhaustive list.  Consult the units data  file
538       to see the complete list, or to see the definitions that are used.
539
540       The  unit  `pound'  is  a  unit of mass.  To get force, multiply by the
541       force conversion unit `force' or use the shorthand `lbf'.   (Note  that
542       `g'  is  already taken as the standard abbreviation for the gram.)  The
543       unit `ounce' is also a unit of mass.  The fluid ounce  is  `fluidounce'
544       or  `floz'.   British capacity units that differ from their US counter‐
545       parts, such as the British Imperial gallon,  are  prefixed  with  `br'.
546       Currency  is  prefixed with its country name: `belgiumfranc', `britain‐
547       pound'.
548
549       The US Survey foot, yard, and mile can be obtained by  using  the  `US'
550       prefix.   These  units  differ  slightly  from the international length
551       units.  They were in general use until 1959, and  are  still  used  for
552       geographic  surveys.  The acre is officially defined in terms of the US
553       Survey foot.  If you want an acre defined  according  to  the  interna‐
554       tional  foot,  use  `intacre'.   The  difference between these units is
555       about 4 parts per million.  The British also used a slightly  different
556       length  measure  before  1959.   These  can be obtained with the prefix
557       `UK'.
558
559       When searching for a unit, if the  specified  string  does  not  appear
560       exactly  as  a unit name, then the `units' program will try to remove a
561       trailing `s' or a trailing `es'.  If that fails, `units' will check for
562       a prefix.  All of the standard metric prefixes are defined.
563
564       To  find  out  what units and prefixes are available, read the standard
565       units data file.
566

DEFINING NEW UNITS

568       All of the units and prefixes that `units' can convert are  defined  in
569       the units data file.  If you want to add your own units, you can supply
570       your own file.  You can also add your  own  units  definitions  in  the
571       `.units.dat'  file  in  your home directory.  If this file exists it is
572       read before the units data file.  It will not  be  read  if  any  units
573       files are specified on the command line.
574
575       A  unit is specified on a single line by giving its name and an equiva‐
576       lence.  Comments start with a `#' character, which can appear  anywhere
577       in a line.  The backslash character (`´) acts as a continuation charac‐
578       ter if it appears as the last character on a line, making  it  possible
579       to spread definitions out over several lines if desired.  A file can be
580       included by giving the command `!include' followed by the file's  name.
581       The file will be sought in the same directory as the parent file unless
582       a full path is given.
583
584       Unit names must not contain any of the operator  characters  `+',  `-',
585       `*',  `/', `|', `^' or the parentheses.  They cannot begin with a digit
586       or a decimal point (`.'), nor can they end with  a  digit  (except  for
587       zero).   Be  careful to define new units in terms of old ones so that a
588       reduction leads to the primitive units, which are marked with `!' char‐
589       acters.  Dimensionless units are indicated by using the string `!dimen‐
590       sionless' for the unit definition.
591
592       When adding new units, be sure to use the `-c' option to check that the
593       new  units  reduce properly.  If you create a loop in the units defini‐
594       tions, then `units' will hang when invoked with the `-c' options.   You
595       will  need  to  use  the `--check-verbose' option which prints out each
596       unit as it checks them.  The program will still hang, but the last unit
597       printed will be the unit which caused the infinite loop.
598
599       If  you  define any units which contain `+' characters, carefully check
600       them because the `-c' option will not catch non-conformable  sums.   Be
601       careful with the `-' operator as well.  When used as a binary operator,
602       the `-' character can perform addition or multiplication  depending  on
603       the  options used to invoke `units'.  To ensure consistent behavior use
604       `-' only as a unary negation operator when writing  units  definitions.
605       To  multiply two units leave a space or use the `*' operator with care,
606       recalling that it has two possible precedence values  and  may  require
607       parentheses  to  ensure consistent behavior.  To compute the difference
608       of `foo' and `bar' write `foo+(-bar)' or even `foo+-bar'.
609
610       Here is an example of a short units file that defines some basic units:
611
612              m        !                # The meter is a primitive unit
613              sec      !                # The second is a primitive unit
614              rad      !dimensionless   # The second is a primitive unit
615              micro-   1e-6             # Define a prefix
616              minute   60 sec           # A minute is 60 seconds
617              hour     60 min           # An hour is 60 minutes
618              inch     0.0254 m         # Inch defined in terms of meters
619              ft       12 inches        # The foot defined in terms of inches
620              mile     5280 ft          # And the mile
621
622                     A unit which ends with a `-' character is a prefix.  If a
623                     prefix  definition  contains  any `/' characters, be sure
624                     they are protected by parentheses.  If you define  `half-
625                     1/2'  then  `halfmeter'  would  be  equivalent  to `1 / 2
626                     meter'.
627

DEFINING NONLINEAR UNITS

629       Some units conversions of interest are nonlinear; for example, tempera‐
630       ture  conversions  between  the Fahrenheit and Celsius scales cannot be
631       done by simply multiplying by conversions factors.
632
633       When you give a linear unit definition such as `inch 2.54 cm'  you  are
634       providing  information  that  `units'  uses to convert values in inches
635       into primitive units of meters.  For nonlinear units, you give a  func‐
636       tional definition that provides the same information.
637
638       Nonlinear  units  are  represented  using a functional notation.  It is
639       best to regard this notation not as a function call but  as  a  way  of
640       adding  units to a number, much the same way that writing a linear unit
641       name after a number adds units to that number.   Internally,  nonlinear
642       units are defined by a pair of functions which convert to and from lin‐
643       ear units in the data file, so that an eventual conversion to primitive
644       units is possible.
645
646       Here is an example nonlinear unit definition:
647
648       tempF(x) [1;K] (x+(-32)) degF + stdtemp ; (tempF+(-stdtemp))/degF + 32
649
650       A  nonlinear  unit  definition comprises a unit name, a dummy parameter
651       name, two functions, and two corresponding units.  The  functions  tell
652       `units'  how  to convert to and from the new unit.  In order to produce
653       valid results, the arguments of these functions need to have  the  cor‐
654       rect  dimensions.   To  facilitate  error checking, you may specify the
655       dimensions.
656
657       The definition begins with the unit name followed immediately (with  no
658       spaces)  by a `(' character.  In parentheses is the name of the parame‐
659       ter.  Next is an optional specification of the units  required  by  the
660       functions  in this definition.  In the example above, the `tempF' func‐
661       tion requires an input argument conformable with `1'.  For normal  non‐
662       linear units definitions the forward function will always take a dimen‐
663       sionless argument.  The inverse function  requires  an  input  argument
664       conformable  with `K'.  In general the inverse function will need units
665       that match the quantity measured by your nonlinear unit.  The sole pur‐
666       pose  of  the expression in brackets to enable `units' to perform error
667       checking on function arguments.
668
669       Next the function  definitions  appear.   In  the  example  above,  the
670       `tempF' function is defined by
671
672           tempF(x) = (x+(-32)) degF + stdtemp
673
674       This  gives  a  rule  for converting `x' in the units `tempF' to linear
675       units of absolute temperature, which makes it possible to convert  from
676       tempF to other units.
677
678       In  order  to  make conversions to Fahrenheit possible, you must give a
679       rule for the inverse conversions. The inverse will  be  `x(tempF)'  and
680       its  definition  appears  after  a  `;' character.  In our example, the
681       inverse is
682
683           x(tempF) = (tempF+(-stdtemp))/degF + 32
684
685       This inverse definition takes an absolute temperature as  its  argument
686       and  converts  it  to  the  Fahrenheit temperature.  The inverse can be
687       omitted by leaving out the `;' character, but then conversions  to  the
688       unit  will be impossible.  If the inverse is omitted then the `--check'
689       option will display a warning.  It is up to you to calculate and  enter
690       the  correct  inverse  function  to  obtain  proper  conversions.   The
691       `--check' option tests the inverse at one point and print an  error  if
692       it is not valid there, but this is not a guarantee that your inverse is
693       correct.
694
695       If you wish to make synonyms for nonlinear units,  you  still  need  to
696       define  both  the forward and inverse functions.  Inverse functions can
697       be obtained using the `~' operator.  So to create a synonym for `tempF'
698       you could write
699
700           fahrenheit(x) [1;K] tempF(x); ~tempF(fahrenheit)
701
702       You  may occasionally wish to define a function that operates on units.
703       This can be done using a nonlinear unit definition.  For  example,  the
704       definition  below  provides conversion between radius and the area of a
705       circle.  Note that this definition requires a length as input and  pro‐
706       duces an area as output, as indicated by the specification in brackets.
707
708           circlearea(r) [m;m^2] pi r^2 ; sqrt(circlearea/pi)
709
710       Sometimes you may be interested in a piecewise linear unit such as many
711       wire gauges.  Piecewise linear units can be defined by specifying  con‐
712       versions  to  linear  units  on  a list of points.  Conversion at other
713       points will be done by linear interpolation.  A partial  definition  of
714       zinc gauge is
715
716           zincgauge[in] 1 0.002, 10 0.02, 15 0.04, 19 0.06, 23 0.1
717
718       In  this example, `zincgauge' is the name of the piecewise linear unit.
719       The definition of such a unit is indicated by the embedded `['  charac‐
720       ter.   After  the bracket, you should indicate the units to be attached
721       to the numbers in the table.  No spaces can appear before the `]' char‐
722       acter,  so a definition like `foo[kg meters]' is illegal; instead write
723       `foo[kg*meters]'.  The definition of the unit consists  of  a  list  of
724       pairs optionally separated by commas.  This list defines a function for
725       converting from the piecewise linear unit to linear units.   The  first
726       item  in  each  pair  is  the function argument; the second item is the
727       value of the function at that  argument  (in  the  units  specified  in
728       brackets).  In this example, we define `zincgauge' at five points.  For
729       example, we set `zincgauge(1)' equal to `0.002 in'.   Definitions  like
730       this  may  be  more readable  if written using  continuation characters
731       as
732              zincgauge[in]         \
733                      1        0.002 \
734                      10        0.02 \
735                      15        0.04 \
736                      19        0.06 \
737                      23        0.1
738
739       With the preceeding definition, the following conversion  can  be  per‐
740       formed:
741
742           You have: zincgauge(10)
743           You want: in
744               * 0.02
745               / 50
746           You have: .01 inch
747           You want: zincgauge
748               5
749
750       If  you  define a piecewise linear unit that is not strictly monotonic,
751       then the inverse will not be well defined.  If the inverse is requested
752       for  such  a  unit,  `units'  will  return  the  smallest inverse.  The
753       `--check' option will print a warning if a non-monotonic piecewise lin‐
754       ear unit is encountered.
755

LOCALIZATION

757       Some units have different values in different locations.  The localiza‐
758       tion feature accomodates this by allowing the units database to specify
759       region  dependent  definitions.   A locale region in the units database
760       begins with `!locale' followed by the name of the locale.  The  leading
761       `!'  must appear in the first column of the units database.  The locale
762       region is terminated by `!endlocale'.  The following example shows  how
763       to define a couple units in a locale.
764
765       !locale en_GB
766       ton                     brton
767       gallon                  brgallon
768       !endlocale
769
770       The  current  locale is specified by the `LOCALE' environment variable.
771       Note that the `-c' option only checks the definitions which are  active
772       for the current locale.
773

ENVIRONMENT VARIABLES

775       The `units' programs uses the following environment variables.
776
777       LOCALE Specifies  the locale.  The default is `en_US'.  Sections of the
778              units database are specific to certain locales.
779
780       PAGER  Specifies the pager to use for help and for displaying the  con‐
781              formable  units.   The  help function browses the units database
782              and calls the pager using the `+nn' syntax for specifying a line
783              number.   The  default  pager is `more', but `less', `emacs', or
784              `vi' are possible alternatives.
785
786       UNITSFILE
787              Specifies the  units  database  file  to  use  (instead  of  the
788              default). This will be overridden by the `-f' option.  Note that
789              you can only specify a single units database using this environ‐
790              ment variable.
791

READLINE SUPPORT

793       If  the  `readline'  package has been compiled in, then when `units' is
794       used interactively, numerous command line editing features  are  avail‐
795       able.   To  check  if  your  version  of `units' includes the readline,
796       invoke the program with the `--version' option.
797
798       For complete information about readline, consult the documentation  for
799       the  readline  package.   Without any configuration, `units' will allow
800       editing in the style of emacs.  Of particular use with `units' are  the
801       completion commands.
802
803       If you type a few characters and then hit `ESC' followed by the `?' key
804       then `units' will display a list of all the units which start with  the
805       characters  typed.   For  example,  if you type `metr' and then request
806       completion, you will see something like this:
807
808       You have: metr
809       metre             metriccup         metrichorsepower  metrictenth
810       metretes          metricfifth       metricounce       metricton
811       metriccarat       metricgrain       metricquart       metricyarncount
812       You have: metr
813
814       If there is a unique way to complete a unitname, you can  hit  the  tab
815       key  and  `units'  will  provide the rest of the unit name.  If `units'
816       beeps, it means that there is no unique completion.  Pressing  the  tab
817       key a second time will print the list of all completions.
818

FILES

820       /usr/share/units.dat - the standard units data file
821

AUTHOR

823       Adrian Mariano (adrian@cam.cornell.edu)
824
825
826
827                                  25 Sep 2007                         UNITS(1)
Impressum