1UNITS(1) General Commands Manual UNITS(1)
2
6 units — unit conversion and calculation program
7
9 [options] [from-unit [to-unit]]
10
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 But Fahrenheit to Celsius is linear, you insist. Not so. A transfor‐
21 mation T is linear if T(x + y) = T(x) + T(y) and this fails for
22 T(x) = ax + b. This transformation is affine, but not linear—see
23 https://en.wikipedia.org/wiki/Linear_map.
24 Basic operation is simple: you enter the units that you want to convert
26 from and the units that you want to convert to. You can use the pro‐
27 gram interactively with prompts, or you can use it from the command
28 line.
29 Beyond simple unit conversions, units can be used as a general-purpose
31 scientific calculator that keeps track of units in its calculations.
32 You can form arbitrary complex mathematical expressions of dimensions
33 including sums, products, quotients, powers, and even roots of dimen‐
34 sions. Thus you can ensure accuracy and dimensional consistency when
35 working with long expressions that involve many different units that
36 may combine in complex ways; for an illustration, see Complicated Unit
37 Expressions.
38 The units are defined in an external data file. You can use the exten‐
40 sive data file that comes with this program, or you can provide your
41 own data file to suit your needs. You can also use your own data file
42 to supplement the standard data file.
43 You can change the default behavior of units with various options given
45 on the command line. See Invoking Units for a description of the avail‐
46 able options.
47
49 To invoke units for interactive use, type units at your shell prompt.
50 The program will print something like this:
51 Currency exchange rates from www.timegenie.com on 2014-03-05
53 2860 units, 109 prefixes, 85 nonlinear units
54 You have:
56 At the ‘You have:’ prompt, type the quantity and units that you are
58 converting from. For example, if you want to convert ten meters to
59 feet, type 10 meters. Next, units will print ‘You want:’. You should
60 type the units you want to convert to. To convert to feet, you would
61 type feet. If the readline library was compiled in, then tab will com‐
62 plete unit names. See Readline Support for more information about
63 readline. To quit the program type quit or exit at either prompt.
64 The result will be displayed in two ways. The first line of output,
66 which is marked with a ‘*’ to indicate multiplication, gives the result
67 of the conversion you have asked for. The second line of output, which
68 is marked with a ‘/’ to indicate division, gives the inverse of the
69 conversion factor. If you convert 10 meters to feet, units will print
70 * 32.808399
72 / 0.03048
73 which tells you that 10 meters equals about 32.8 feet. The second num‐
75 ber gives the conversion in the opposite direction. In this case, it
76 tells you that 1 foot is equal to about 0.03 dekameters since the
77 dekameter is 10 meters. It also tells you that 1/32.8 is about 0.03.
78 The units program prints the inverse because sometimes it is a more
80 convenient number. In the example above, for example, the inverse
81 value is an exact conversion: a foot is exactly 0.03048 dekameters.
82 But the number given the other direction is inexact.
83 If you convert grains to pounds, you will see the following:
85 You have: grains
87 You want: pounds
88 * 0.00014285714
89 / 7000
90 From the second line of the output you can immediately see that a
92 grain is equal to a seven thousandth of a pound. This is not so obvi‐
93 ous from the first line of the output. If you find the output format
94 confusing, try using the ‘--verbose’ option:
95 You have: grain
97 You want: aeginamina
98 grain = 0.00010416667 aeginamina
99 grain = (1 / 9600) aeginamina
100 If you request a conversion between units that measure reciprocal di‐
102 mensions, then units will display the conversion results with an extra
103 note indicating that reciprocal conversion has been done:
104 You have: 6 ohms
106 You want: siemens
107 reciprocal conversion
108 * 0.16666667
109 / 6
110 Reciprocal conversion can be suppressed by using the ‘--strict’ option.
112 As usual, use the ‘--verbose’ option to get more comprehensible output:
113 You have: tex
115 You want: typp
116 reciprocal conversion
117 1 / tex = 496.05465 typp
118 1 / tex = (1 / 0.0020159069) typp
119 You have: 20 mph
121 You want: sec/mile
122 reciprocal conversion
123 1 / 20 mph = 180 sec/mile
124 1 / 20 mph = (1 / 0.0055555556) sec/mile
125 If you enter incompatible unit types, the units program will print a
127 message indicating that the units are not conformable and it will dis‐
128 play the reduced form for each unit:
129 You have: ergs/hour
131 You want: fathoms kg^2 / day
132 conformability error
133 2.7777778e-11 kg m^2 / sec^3
134 2.1166667e-05 kg^2 m / sec
135 If you only want to find the reduced form or definition of a unit, sim‐
137 ply press Enter at the ‘You want:’ prompt. Here is an example:
138 You have: jansky
140 You want:
141 Definition: fluxunit = 1e-26 W/m^2 Hz = 1e-26 kg / s^2
142 The output from units indicates that the jansky is defined to be equal
144 to a fluxunit which in turn is defined to be a certain combination of
145 watts, meters, and hertz. The fully reduced (and in this case somewhat
146 more cryptic) form appears on the far right.
147 Some named units are treated as dimensionless in some situations.
149 These units include the radian and steradian. These units will be
150 treated as equal to 1 in units conversions. Power is equal to torque
151 times angular velocity. This conversion can only be performed if the
152 radian is dimensionless.
153 You have: (14 ft lbf) (12 radians/sec)
155 You want: watts
156 * 227.77742
157 / 0.0043902509
158 It is also possible to compute roots and other non-integer powers of
160 dimensionless units; this allows computations such as the altitude of
161 geosynchronous orbit:
162 You have: cuberoot(G earthmass / (circle/siderealday)^2) - earthradius
164 You want: miles
165 * 22243.267
166 / 4.4957425e-05
167 Named dimensionless units are not treated as dimensionless in other
169 contexts. They cannot be used as exponents so for example,
170 ‘meter^radian’ is forbidden.
171 If you want a list of options you can type ? at the ‘You want:’ prompt.
173 The program will display a list of named units that are conformable
174 with the unit that you entered at the ‘You have:’ prompt above. Con‐
175 formable unit combinations will not appear on this list.
176 Typing help at either prompt displays a short help message. You can
178 also type help followed by a unit name. This will invoke a pager on
179 the units data base at the point where that unit is defined. You can
180 read the definition and comments that may give more details or histori‐
181 cal information about the unit. (You can generally quit out of the
182 page by pressing ‘q’.)
183 Typing search text will display a list of all of the units whose names
185 contain text as a substring along with their definitions. This may
186 help in the case where you aren't sure of the right unit name.
187
189 The units program can perform units conversions non-interactively from
190 the command line. To do this, type the command, type the original unit
191 expression, and type the new units you want. If a units expression
192 contains non-alphanumeric characters, you may need to protect it from
193 interpretation by the shell using single or double quote characters.
194 If you type
196 units "2 liters" quarts
198 then units will print
200 * 2.1133764
202 / 0.47317647
203 and then exit. The output tells you that 2 liters is about 2.1 quarts,
205 or alternatively that a quart is about 0.47 times 2 liters.
206 units does not require a space between a numerical value and the unit,
208 so the previous example can be given as
209 units 2liters quarts
211 to avoid having to quote the first argument.
213 If the conversion is successful, units will return success (zero) to
215 the calling environment. If you enter non-conformable units, then
216 units will print a message giving the reduced form of each unit and it
217 will return failure (nonzero) to the calling environment.
218 If the ‘--conformable’ option is given, only one unit expression is al‐
220 lowed, and units will print all units conformable with that expression;
221 it is equivalent to giving ? at the ‘You want:’ prompt. For example,
222 units --conformable gauss
224 B_FIELD tesla
225 Gs gauss
226 T tesla
227 gauss abvolt sec / cm^2
228 stT stattesla
229 statT stattesla
230 stattesla statWb/cm^2
231 tesla Wb/m^2
232 If you give more than one unit expression with the ‘--conformable’ op‐
234 tion, the program will exit with an error message and return failure.
235 This option has no effect in interactive mode.
236 If the ‘--terse’ (‘-t’) option is given with the ‘--conformable’ op‐
238 tion, conformable units are shown without definitions; with the previ‐
239 ous example, this would give
240 units --terse --conformable gauss
242 B_FIELD
243 Gs
244 T
245 gauss
246 stT
247 statT
248 stattesla
249 tesla
250 When the ‘--conformable’ option is not given and you invoke units with
252 only one argument, units will print the definition of the specified
253 unit. It will return failure if the unit is not defined and success if
254 the unit is defined.
255
257 The conversion information is read from a units data file that is
258 called ‘definitions.units’ and is usually located in the
259 ‘/usr/share/units’ directory. If you invoke units with the ‘-V’ op‐
260 tion, it will print the location of this file. The default file in‐
261 cludes definitions for all familiar units, abbreviations and metric
262 prefixes. It also includes many obscure or archaic units. Many common
263 spelled-out numbers (e.g., ‘seventeen’) are recognized.
264 Many constants of nature are defined, including these:
266 pi ratio of circumference to diameter
268 c speed of light
269 e charge on an electron
270 force acceleration of gravity
271 mole Avogadro's number
272 water pressure per unit height of water
273 Hg pressure per unit height of mercury
274 au astronomical unit
275 k Boltzman's constant
276 mu0 permeability of vacuum
277 epsilon0 permittivity of vacuum
278 G Gravitational constant
279 mach speed of sound
280 The standard data file includes atomic masses for all of the elements
282 and numerous other constants. Also included are the densities of vari‐
283 ous ingredients used in baking so that ‘2 cups flour_sifted’ can be
284 converted to ‘grams’. This is not an exhaustive list. Consult the
285 units data file to see the complete list, or to see the definitions
286 that are used.
287 The ‘pound’ is a unit of mass. To get force, multiply by the force
289 conversion unit ‘force’ or use the shorthand ‘lbf’. (Note that ‘g’ is
290 already taken as the standard abbreviation for the gram.) The unit
291 ‘ounce’ is also a unit of mass. The fluid ounce is ‘fluidounce’ or
292 ‘floz’. When British capacity units differ from their US counterparts,
293 such as the British Imperial gallon, the unit is defined both ways with
294 ‘br’ and ‘us’ prefixes. Your locale settings will determine the value
295 of the unprefixed unit. Currency is prefixed with its country name:
296 ‘belgiumfranc’, ‘britainpound’.
297 When searching for a unit, if the specified string does not appear ex‐
299 actly as a unit name, then the units program will try to remove a
300 trailing ‘s’, ‘es’. Next units will replace a trailing ‘ies’ with ‘y’.
301 If that fails, units will check for a prefix. The database includes
302 all of the standard metric prefixes. Only one prefix is permitted per
303 unit, so ‘micromicrofarad’ will fail. However, prefixes can appear
304 alone with no unit following them, so ‘micro*microfarad’ will work, as
305 will ‘micro microfarad’.
306 To find out which units and prefixes are available, read the standard
308 units data file, which is extensively annotated.
309 English Customary Units
311 English customary units differ in various ways in different regions.
312 In Britain a complex system of volume measurements featured different
313 gallons for different materials such as a wine gallon and ale gallon
314 that different by twenty percent. This complexity was swept away in
315 1824 by a reform that created an entirely new gallon, the British Impe‐
316 rial gallon defined as the volume occupied by ten pounds of water.
317 Meanwhile in the USA the gallon is derived from the 1707 Winchester
318 wine gallon, which is 231 cubic inches. These gallons differ by about
319 twenty percent. By default if units runs in the ‘en_GB’ locale you
320 will get the British volume measures. If it runs in the ‘en_US’ locale
321 you will get the US volume measures. In other locales the default val‐
322 ues are the US definitions. If you wish to force different defini‐
323 tions, then set the environment variable UNITS_ENGLISH to either ‘US’
324 or ‘GB’ to set the desired definitions independent of the locale.
325 Before 1959, the value of a yard (and other units of measure defined in
327 terms of it) differed slightly among English-speaking countries. In
328 1959, Australia, Canada, New Zealand, the United Kingdom, the United
329 States, and South Africa adopted the Canadian value of 1 yard =
330 0.9144 m (exactly), which was approximately halfway between the values
331 used by the UK and the US; it had the additional advantage of making
332 1 inch = 2.54 cm (exactly). This new standard was termed the Interna‐
333 tional Yard. Australia, Canada, and the UK then defined all customary
334 lengths in terms of the International Yard (Australia did not define
335 the furlong or rod); because many US land surveys were in terms of the
336 pre-1959 units, the US continued to define customary surveyors' units
337 (furlong, chain, rod, and link) in terms of the previous value for the
338 foot, which was termed the US survey foot. The US defined a US survey
339 mile as 5280 US survey feet, and defined a statute mile as a US survey
340 mile. The US values for these units differ from the international val‐
341 ues by about 2 ppm.
342 The units program uses the international values for these units; the US
344 values can be obtained by using either the ‘US’ or the ‘survey’ prefix.
345 In either case, the simple familiar relationships among the units are
346 maintained, e.g., 1 ‘furlong’ = 660 ‘ft’, and 1 ‘USfurlong’ = 660
347 ‘USft’, though the metric equivalents differ slightly between the two
348 cases. The ‘US’ prefix or the ‘survey’ prefix can also be used to ob‐
349 tain the US survey mile and the value of the US yard prior to 1959,
350 e.g., ‘USmile’ or ‘surveymile’ (but not ‘USsurveymile’). To get the US
351 value of the statute mile, use either ‘USstatutemile’ or ‘USmile’.
352 Except for distances that extend over hundreds of miles (such as in the
354 US State Plane Coordinate System), the differences in the miles are
355 usually insignificant:
356 You have: 100 surveymile - 100 mile
358 You want: inch
359 * 12.672025
360 / 0.078913984
361 The pre-1959 UK values for these units can be obtained with the prefix
363 ‘UK’.
364 In the US, the acre is officially defined in terms of the US survey
366 foot, but units uses a definition based on the international foot. If
367 you want the official US acre use ‘USacre’ and similarly use
368 ‘USacrefoot’ for the official US version of that unit. The difference
369 between these units is about 4 parts per million.
370
372 Operators
373 You can enter more complicated units by combining units with operations
374 such as multiplication, division, powers, addition, subtraction, and
375 parentheses for grouping. You can use the customary symbols for these
376 operators when units is invoked with its default options. Addition‐
377 ally, units supports some extensions, including high priority multipli‐
378 cation using a space, and a high priority numerical division operator
379 (‘|’) that can simplify some expressions.
380 You multiply units using a space or an asterisk (‘*’). The next exam‐
382 ple shows both forms:
383 You have: arabicfoot * arabictradepound * force
385 You want: ft lbf
386 * 0.7296
387 / 1.370614
388 You can divide units using the slash (‘/’) or with ‘per’:
390 You have: furlongs per fortnight
392 You want: m/s
393 * 0.00016630986
394 / 6012.8727
395 You can use parentheses for grouping:
397 You have: (1/2) kg / (kg/meter)
399 You want: league
400 * 0.00010356166
401 / 9656.0833
402 White space surrounding operators is optional, so the previous example
404 could have used ‘(1/2)kg/(kg/meter)’. As a consequence, however, hy‐
405 phenated spelled-out numbers (e.g., ‘forty-two’) cannot be used;
406 ‘forty-two’ is interpreted as ‘40 - 2’.
407 Multiplication using a space has a higher precedence than division us‐
409 ing a slash and is evaluated left to right; in effect, the first ‘/’
410 character marks the beginning of the denominator of a unit expression.
411 This makes it simple to enter a quotient with several terms in the de‐
412 nominator: ‘J / mol K’. The ‘*’ and ‘/’ operators have the same prece‐
413 dence, and are evaluated left to right; if you multiply with ‘*’, you
414 must group the terms in the denominator with parentheses:
415 ‘J / (mol * K)’.
416 The higher precedence of the space operator may not always be advanta‐
418 geous. For example, ‘m/s s/day’ is equivalent to ‘m / s s day’ and has
419 dimensions of length per time cubed. Similarly, ‘1/2 meter’ refers to
420 a unit of reciprocal length equivalent to 0.5/meter, perhaps not what
421 you would intend if you entered that expression. The get a half meter
422 you would need to use parentheses: ‘(1/2) meter’. The ‘*’ operator is
423 convenient for multiplying a sequence of quotients. For example,
424 ‘m/s * s/day’ is equivalent to ‘m/day’. Similarly, you could write
425 ‘1/2 * meter’ to get half a meter.
426 The units program supports another option for numerical fractions: you
428 can indicate division of numbers with the vertical bar (‘|’), so if you
429 wanted half a meter you could write ‘1|2 meter’. You cannot use the
430 vertical bar to indicate division of non-numerical units (e.g., ‘m|s’
431 results in an error message).
432 Powers of units can be specified using the ‘^’ character, as shown in
434 the following example, or by simple concatenation of a unit and its ex‐
435 ponent: ‘cm3’ is equivalent to ‘cm^3’; if the exponent is more than one
436 digit, the ‘^’ is required. You can also use ‘**’ as an exponent oper‐
437 ator.
438 You have: cm^3
440 You want: gallons
441 * 0.00026417205
442 / 3785.4118
443 Concatenation only works with a single unit name: if you write
445 ‘(m/s)2’, units will treat it as multiplication by 2. When a unit in‐
446 cludes a prefix, exponent operators apply to the combination, so
447 ‘centimeter3’ gives cubic centimeters. If you separate the prefix from
448 the unit with any multiplication operator (e.g., ‘centi meter^3’), the
449 prefix is treated as a separate unit, so the exponent applies only to
450 the unit without the prefix. The second example is equivalent to
451 ‘centi * (meter^3)’, and gives a hundredth of a cubic meter, not a cu‐
452 bic centimeter. The units program is limited internally to products of
453 99 units; accordingly, expressions like ‘meter^100’ or ‘joule^34’ (rep‐
454 resented internally as ‘kg^34 m^68 / s^68’) will fail.
455 The ‘|’ operator has the highest precedence, so you can write the
457 square root of two thirds as ‘2|3^1|2’. The ‘^’ operator has the sec‐
458 ond highest precedence, and is evaluated right to left, as usual:
459 You have: 5 * 2^3^2
461 You want:
462 Definition: 2560
463 With a dimensionless base unit, any dimensionless exponent is meaning‐
465 ful (e.g., ‘pi^exp(2.371)’). Even though angle is sometimes treated as
466 dimensionless, exponents cannot have dimensions of angle:
467 You have: 2^radian
469 ^
470 Exponent not dimensionless
471 If the base unit is not dimensionless, the exponent must be a rational
473 number p/q, and the dimension of the unit must be a power of q, so
474 ‘gallon^2|3’ works but ‘acre^2|3’ fails. An exponent using the slash
475 (‘/’) operator (e.g., ‘gallon^(2/3)’) is also acceptable; the parenthe‐
476 ses are needed because the precedence of ‘^’ is higher than that of
477 ‘/’. Since units cannot represent dimensions with exponents greater
478 than 99, a fully reduced exponent must have q < 100. When raising a
479 non-dimensionless unit to a power, units attempts to convert a decimal
480 exponent to a rational number with q < 100. If this is not possible
481 units displays an error message:
482 You have: ft^1.234
484 Base unit not dimensionless; rational exponent required
485 A decimal exponent must match its rational representation to machine
487 precision, so ‘acre^1.5’ works but ‘gallon^0.666’ does not.
488 Sums and Differences of Units
490 You may sometimes want to add values of different units that are out‐
491 side the SI. You may also wish to use units as a calculator that keeps
492 track of units. Sums of conformable units are written with the ‘+’
493 character, and differences with the ‘-’ character.
494 You have: 2 hours + 23 minutes + 32 seconds
496 You want: seconds
497 * 8612
498 / 0.00011611705
499 You have: 12 ft + 3 in
501 You want: cm
502 * 373.38
503 / 0.0026782366
504 You have: 2 btu + 450 ft lbf
506 You want: btu
507 * 2.5782804
508 / 0.38785542
509 The expressions that are added or subtracted must reduce to identical
511 expressions in primitive units, or an error message will be displayed:
512 You have: 12 printerspoint - 4 heredium
514 ^
515 Illegal sum of non-conformable units
516 If you add two values of vastly different scale you may exceed the
518 available precision of floating point (about 15 digits). The effect is
519 that the addition of the smaller value makes no change to the larger
520 value; in other words, the smaller value is treated as if it were zero.
521 You have: lightyear + cm
523 No warning is given, however. As usual, the precedence for ‘+’ and ‘-’
525 is lower than that of the other operators. A fractional quantity such
526 as 2 1/2 cups can be given as ‘(2+1|2) cups’; the parentheses are nec‐
527 essary because multiplication has higher precedence than addition. If
528 you omit the parentheses, units attempts to add ‘2’ and ‘1|2 cups’, and
529 you get an error message:
530 You have: 2+1|2 cups
532 ^
533 Illegal sum or difference of non-conformable units
534 The expression could also be correctly written as ‘(2+1/2) cups’. If
536 you write ‘2 1|2 cups’ the space is interpreted as multiplication so
537 the result is the same as ‘1 cup’.
538 The ‘+’ and ‘-’ characters sometimes appears in exponents like
540 ‘3.43e+8’. This leads to an ambiguity in an expression like ‘3e+2 yC’.
541 The unit ‘e’ is a small unit of charge, so this can be regarded as
542 equivalent to ‘(3e+2) yC’ or ‘(3 e)+(2 yC)’. This ambiguity is re‐
543 solved by always interpreting ‘+’ and ‘-’ as part of an exponent if
544 possible.
545 Numbers as Units
547 For units, numbers are just another kind of unit. They can appear as
548 many times as you like and in any order in a unit expression. For ex‐
549 ample, to find the volume of a box that is 2 ft by 3 ft by 12 ft in
550 steres, you could do the following:
551 You have: 2 ft 3 ft 12 ft
553 You want: stere
554 * 2.038813
555 / 0.49048148
556 You have: $ 5 / yard
558 You want: cents / inch
559 * 13.888889
560 / 0.072
561 And the second example shows how the dollar sign in the units conver‐
563 sion can precede the five. Be careful: units will interpret ‘$5’ with
564 no space as equivalent to ‘dollar^5’.
565 Built-in Functions
567 Several built-in functions are provided: ‘sin’, ‘cos’, ‘tan’, ‘asin’,
568 ‘acos’, ‘atan’, ‘sinh’, ‘cosh’, ‘tanh’, ‘asinh’, ‘acosh’, ‘atanh’,
569 ‘exp’, ‘ln’, ‘log’, ‘abs’, ‘round’, ‘floor’, ‘ceil’, ‘factorial’,
570 ‘Gamma’, ‘lnGamma’, ‘erf’, and ‘erfc’; the function ‘lnGamma’ is the
571 natural logarithm of the ‘Gamma’ function.
572 The ‘sin’, ‘cos’, and ‘tan’ functions require either a dimensionless
574 argument or an argument with dimensions of angle.
575 You have: sin(30 degrees)
577 You want:
578 Definition: 0.5
579 You have: sin(pi/2)
581 You want:
582 Definition: 1
583 You have: sin(3 kg)
585 ^
586 Unit not dimensionless
587 The other functions on the list require dimensionless arguments. The
589 inverse trigonometric functions return arguments with dimensions of an‐
590 gle.
591 The ‘ln’ and ‘log’ functions give natural log and log base 10 respec‐
593 tively. To obtain logs for any integer base, enter the desired base
594 immediately after ‘log’. For example, to get log base 2 you would
595 write ‘log2’ and to get log base 47 you could write ‘log47’.
596 You have: log2(32)
598 You want:
599 Definition: 5
600 You have: log3(32)
601 You want:
602 Definition: 3.1546488
603 You have: log4(32)
604 You want:
605 Definition: 2.5
606 You have: log32(32)
607 You want:
608 Definition: 1
609 You have: log(32)
610 You want:
611 Definition: 1.50515
612 You have: log10(32)
613 You want:
614 Definition: 1.50515
615 If you wish to take roots of units, you may use the ‘sqrt’ or
617 ‘cuberoot’ functions. These functions require that the argument have
618 the appropriate root. You can obtain higher roots by using fractional
619 exponents:
620 You have: sqrt(acre)
622 You want: feet
623 * 208.71074
624 / 0.0047913202
625 You have: (400 W/m^2 / stefanboltzmann)^(1/4)
627 You have:
628 Definition: 289.80882 K
629 You have: cuberoot(hectare)
631 ^
632 Unit not a root
633 Previous Result
635 You can insert the result of the previous conversion using the under‐
636 score (‘_’). It is useful when you want to convert the same input to
637 several different units, for example
638 You have: 2.3 tonrefrigeration
640 You want: btu/hr
641 * 27600
642 / 3.6231884e-005
643 You have: _
644 You want: kW
645 * 8.0887615
646 / 0.12362832
647 Suppose you want to do some deep frying that requires an oil depth of
649 2 inches. You have 1/2 gallon of oil, and want to know the largest-di‐
650 ameter pan that will maintain the required depth. The nonlinear unit
651 ‘circlearea’ gives the radius of the circle (see Other Nonlinear Units,
652 for a more detailed description) in SI units; you want the diameter in
653 inches:
654 You have: 1|2 gallon / 2 in
656 You want: circlearea
657 0.10890173 m
658 You have: 2 _
659 You want: in
660 * 8.5749393
661 / 0.1166189
662 In most cases, surrounding white space is optional, so the previous ex‐
664 ample could have used ‘2_’. If ‘_’ follows a non-numerical unit sym‐
665 bol, however, the space is required:
666 You have: m_
668 ^
669 Parse error
670 When ‘_’ is followed by a digit, the operation is multiplication rather
672 than exponentiation, so that ‘_2’, is equivalent to ‘_ * 2’ rather than
673 ‘_^2’.
674 You can use the ‘_’ symbol any number of times; for example,
676 You have: m
678 You want:
679 Definition: 1 m
680 You have: _ _
681 You want:
682 Definition: 1 m^2
683 Using ‘_’ before a conversion has been performed (e.g., immediately af‐
685 ter invocation) generates an error:
686 You have: _
688 ^
689 No previous result; '_' not set
690 Accordingly, ‘_’ serves no purpose when units is invoked non-interac‐
692 tively.
693 If units is invoked with the ‘--verbose’ option (see Invoking Units),
695 the value of ‘_’ is not expanded:
696 You have: mile
698 You want: ft
699 mile = 5280 ft
700 mile = (1 / 0.00018939394) ft
701 You have: _
702 You want: m
703 _ = 1609.344 m
704 _ = (1 / 0.00062137119) m
705 You can give ‘_’ at the ‘You want:’ prompt, but it usually is not very
707 useful.
708 Complicated Unit Expressions
710 The units program is especially helpful in ensuring accuracy and dimen‐
711 sional consistency when converting lengthy unit expressions. For exam‐
712 ple, one form of the Darcy-Weisbach fluid-flow equation is
713 Delta P = (8 / pi)^2 (rho fLQ^2) / d^5,
715 where Delta P is the pressure drop, rho is the mass density, f is the
717 (dimensionless) friction factor, L is the length of the pipe, Q is the
718 volumetric flow rate, and d is the pipe diameter. It might be desired
719 to have the equation in the form
720 Delta P = A1 rho fLQ^2 / d^5
722 that accepted the user’s normal units; for typical units used in the
724 US, the required conversion could be something like
725 You have: (8/pi^2)(lbm/ft^3)ft(ft^3/s)^2(1/in^5)
727 You want: psi
728 * 43.533969
729 / 0.022970568
730 The parentheses allow individual terms in the expression to be entered
732 naturally, as they might be read from the formula. Alternatively, the
733 multiplication could be done with the ‘*’ rather than a space; then
734 parentheses are needed only around ‘ft^3/s’ because of its exponent:
735 You have: 8/pi^2 * lbm/ft^3 * ft * (ft^3/s)^2 /in^5
737 You want: psi
738 * 43.533969
739 / 0.022970568
740 Without parentheses, and using spaces for multiplication, the previous
742 conversion would need to be entered as
743 You have: 8 lb ft ft^3 ft^3 / pi^2 ft^3 s^2 in^5
745 You want: psi
746 * 43.533969
747 / 0.022970568
748 Backwards Compatibility: ‘*’ and ‘-’
750 The original units assigned multiplication a higher precedence than di‐
751 vision using the slash. This differs from the usual precedence rules,
752 which give multiplication and division equal precedence, and can be
753 confusing for people who think of units as a calculator.
754 The star operator (‘*’) included in this units program has, by default,
756 the same precedence as division, and hence follows the usual precedence
757 rules. For backwards compatibility you can invoke units with the
758 ‘--oldstar’ option. Then ‘*’ has a higher precedence than division,
759 and the same precedence as multiplication using the space.
760 Historically, the hyphen (‘-’) has been used in technical publications
762 to indicate products of units, and the original units program treated
763 it as a multiplication operator. Because units provides several other
764 ways to obtain unit products, and because ‘-’ is a subtraction operator
765 in general algebraic expressions, units treats the binary ‘-’ as a sub‐
766 traction operator by default. For backwards compatibility use the
767 ‘--product’ option, which causes units to treat the binary ‘-’ operator
768 as a product operator. When ‘-’ is a multiplication operator it has
769 the same precedence as multiplication with a space, giving it a higher
770 precedence than division.
771 When ‘-’ is used as a unary operator it negates its operand. Regard‐
773 less of the units options, if ‘-’ appears after ‘(’ or after ‘+’, then
774 it will act as a negation operator. So you can always compute 20 de‐
775 grees minus 12 minutes by entering ‘20 degrees + -12 arcmin’. You must
776 use this construction when you define new units because you cannot know
777 what options will be in force when your definition is processed.
778
780 Nonlinear units are represented using functional notation. They make
781 possible nonlinear unit conversions such as temperature.
782 Temperature Conversions
784 Conversions between temperatures are different from linear conversions
785 between temperature increments—see the example below. The absolute
786 temperature conversions are handled by units starting with ‘temp’, and
787 you must use functional notation. The temperature-increment conver‐
788 sions are done using units starting with ‘deg’ and they do not require
789 functional notation.
790 You have: tempF(45)
792 You want: tempC
793 7.2222222
794 You have: 45 degF
796 You want: degC
797 * 25
798 / 0.04
799 Think of ‘tempF(x)’ not as a function but as a notation that indicates
801 that x should have units of ‘tempF’ attached to it. See Defining Non‐
802 linear Units. The first conversion shows that if it’s 45 degrees
803 Fahrenheit outside, it’s 7.2 degrees Celsius. The second conversion
804 indicates that a change of 45 degrees Fahrenheit corresponds to a
805 change of 25 degrees Celsius. The conversion from ‘tempF(x)’ is to ab‐
806 solute temperature, so that
807 You have: tempF(45)
809 You want: degR
810 * 504.67
811 / 0.0019814929
812 gives the same result as
814 You have: tempF(45)
816 You want: tempR
817 * 504.67
818 / 0.0019814929
819 But if you convert ‘tempF(x)’ to ‘degC’, the output is probably not
821 what you expect:
822 You have: tempF(45)
824 You want: degC
825 * 280.37222
826 / 0.0035666871
827 The result is the temperature in K, because ‘degC’ is defined as ‘K’,
829 the Kelvin. For consistent results, use the ‘tempX’ units when convert‐
830 ing to a temperature rather than converting a temperature increment.
831 The ‘tempC()’ and ‘tempF()’ definitions are limited to positive abso‐
833 lute temperatures, and giving a value that would result in a negative
834 absolute temperature generates an error message:
835 You have: tempC(-275)
837 ^
838 Argument of function outside domain
839 Other Nonlinear Units
841 Some other examples of nonlinear units are numerous different ring
842 sizes and wire gauges, the grit sizes used for abrasives, the decibel
843 scale, shoe size, scales for the density of sugar (e.g., baume). The
844 standard data file also supplies units for computing the area of a cir‐
845 cle and the volume of a sphere. See the standard units data file for
846 more details. Wire gauges with multiple zeroes are signified using
847 negative numbers where two zeroes is ‘-1’. Alternatively, you can use
848 the synonyms ‘g00’, ‘g000’, and so on that are defined in the standard
849 units data file.
850 You have: wiregauge(11)
852 You want: inches
853 * 0.090742002
854 / 11.020255
855 You have: brwiregauge(g00)
857 You want: inches
858 * 0.348
859 / 2.8735632
860 You have: 1 mm
862 You want: wiregauge
863 18.201919
864 You have: grit_P(600)
866 You want: grit_ansicoated
867 342.76923
868 The last example shows the conversion from P graded sand paper, which
870 is the European standard and may be marked “P600” on the back, to the
871 USA standard.
872 You can compute the area of a circle using the nonlinear unit,
874 ‘circlearea’. You can also do this using the circularinch or cir‐
875 cleinch. The next example shows two ways to compute the area of a cir‐
876 cle with a five inch radius and one way to compute the volume of a
877 sphere with a radius of one meter.
878 You have: circlearea(5 in)
880 You want: in2
881 * 78.539816
882 / 0.012732395
883 You have: 10^2 circleinch
885 You want: in2
886 * 78.539816
887 / 0.012732395
888 You have: spherevol(meter)
890 You want: ft3
891 * 147.92573
892 / 0.0067601492
893 The inverse of a nonlinear conversion is indicated by prefixing a tilde
895 (‘~’) to the nonlinear unit name:
896 You have: ~wiregauge(0.090742002 inches)
898 You want:
899 Definition: 11
900 You can give a nonlinear unit definition without an argument or paren‐
902 theses, and press Enter at the ‘You want:’ prompt to get the definition
903 of a nonlinear unit; if the definition is not valid for all real num‐
904 bers, the range of validity is also given. If the definition requires
905 specific units this information is also displayed:
906 You have: tempC
908 Definition: tempC(x) = x K + stdtemp
909 defined for x >= -273.15
910 You have: ~tempC
911 Definition: ~tempC(tempC) = (tempC +(-stdtemp))/K
912 defined for tempC >= 0 K
913 You have: circlearea
914 Definition: circlearea(r) = pi r^2
915 r has units m
916 To see the definition of the inverse use the ‘~’ notation. In this
918 case the parameter in the functional definition will usually be the
919 name of the unit. Note that the inverse for ‘tempC’ shows that it re‐
920 quires units of ‘K’ in the specification of the allowed range of val‐
921 ues. Nonlinear unit conversions are described in more detail in Defin‐
922 ing Nonlinear Units.
923
925 Outside of the SI, it is sometimes desirable to convert a single unit
926 to a sum of units—for example, feet to feet plus inches. The conver‐
927 sion from sums of units was described in Sums and Differences of Units,
928 and is a simple matter of adding the units with the ‘+’ sign:
929 You have: 12 ft + 3 in + 3|8 in
931 You want: ft
932 * 12.28125
933 / 0.081424936
934 Although you can similarly write a sum of units to convert to, the re‐
936 sult will not be the conversion to the units in the sum, but rather the
937 conversion to the particular sum that you have entered:
938 You have: 12.28125 ft
940 You want: ft + in + 1|8 in
941 * 11.228571
942 / 0.089058524
943 The unit expression given at the ‘You want:’ prompt is equivalent to
945 asking for conversion to multiples of ‘1 ft + 1 in + 1|8 in’, which is
946 1.09375 ft, so the conversion in the previous example is equivalent to
947 You have: 12.28125 ft
949 You want: 1.09375 ft
950 * 11.228571
951 / 0.089058524
952 In converting to a sum of units like miles, feet and inches, you typi‐
954 cally want the largest integral value for the first unit, followed by
955 the largest integral value for the next, and the remainder converted to
956 the last unit. You can do this conversion easily with units using a
957 special syntax for lists of units. You must list the desired units in
958 order from largest to smallest, separated by the semicolon (‘;’) char‐
959 acter:
960 You have: 12.28125 ft
962 You want: ft;in;1|8 in
963 12 ft + 3 in + 3|8 in
964 The conversion always gives integer coefficients on the units in the
966 list, except possibly the last unit when the conversion is not exact:
967 You have: 12.28126 ft
969 You want: ft;in;1|8 in
970 12 ft + 3 in + 3.00096 * 1|8 in
971 The order in which you list the units is important:
973 You have: 3 kg
975 You want: oz;lb
976 105 oz + 0.051367866 lb
977 You have: 3 kg
979 You want: lb;oz
980 6 lb + 9.8218858 oz
981 Listing ounces before pounds produces a technically correct result, but
983 not a very useful one. You must list the units in descending order of
984 size in order to get the most useful result.
985 Ending a unit list with the separator ‘;’ has the same effect as re‐
987 peating the last unit on the list, so ‘ft;in;1|8 in;’ is equivalent to
988 ‘ft;in;1|8 in;1|8 in’. With the example above, this gives
989 You have: 12.28126 ft
991 You want: ft;in;1|8 in;
992 12 ft + 3 in + 3|8 in + 0.00096 * 1|8 in
993 in effect separating the integer and fractional parts of the coeffi‐
995 cient for the last unit. If you instead prefer to round the last coef‐
996 ficient to an integer you can do this with the ‘--round’ (‘-r’) option.
997 With the previous example, the result is
998 You have: 12.28126 ft
1000 You want: ft;in;1|8 in
1001 12 ft + 3 in + 3|8 in (rounded down to nearest 1|8 in)
1002 When you use the ‘-r’ option, repeating the last unit on the list has
1004 no effect (e.g., ‘ft;in;1|8 in;1|8 in’ is equivalent to ‘ft;in;1|8
1005 in’), and hence neither does ending a list with a ‘;’. With a single
1006 unit and the ‘-r’ option, a terminal ‘;’ does have an effect: it causes
1007 units to treat the single unit as a list and produce a rounded value
1008 for the single unit. Without the extra ‘;’, the ‘-r’ option has no ef‐
1009 fect on single unit conversions. This example shows the output using
1010 the ‘-r’ option:
1011 You have: 12.28126 ft
1013 You want: in
1014 * 147.37512
1015 / 0.0067854058
1016 You have: 12.28126 ft
1018 You want: in;
1019 147 in (rounded down to nearest in)
1020 Each unit that appears in the list must be conformable with the first
1022 unit on the list, and of course the listed units must also be conform‐
1023 able with the unit that you enter at the ‘You have:’ prompt.
1024 You have: meter
1026 You want: ft;kg
1027 ^
1028 conformability error
1029 ft = 0.3048 m
1030 kg = 1 kg
1031 You have: meter
1033 You want: lb;oz
1034 conformability error
1035 1 m
1036 0.45359237 kg
1037 In the first case, units reports the disagreement between units appear‐
1039 ing on the list. In the second case, units reports disagreement be‐
1040 tween the unit you entered and the desired conversion. This conforma‐
1041 bility error is based on the first unit on the unit list.
1042 Other common candidates for conversion to sums of units are angles and
1044 time:
1045 You have: 23.437754 deg
1047 You want; deg;arcmin;arcsec
1048 23 deg + 26 arcmin + 15.9144 arcsec
1049 You have: 7.2319 hr
1051 You want: hr;min;sec
1052 7 hr + 13 min + 54.84 sec
1053 Some applications for unit lists may be less obvious. Suppose that you
1055 have a postal scale and wish to ensure that it’s accurate at 1 oz, but
1056 have only metric calibration weights. You might try
1057 You have: 1 oz
1059 You want: 100 g;50 g; 20 g;10 g;5 g;2 g;1 g;
1060 20 g + 5 g + 2 g + 1 g + 0.34952312 * 1 g
1061 You might then place one each of the 20 g, 5 g, 2 g, and 1 g weights on
1063 the scale and hope that it indicates close to
1064 You have: 20 g + 5 g + 2 g + 1 g
1066 You want: oz;
1067 0.98767093 oz
1068 Appending ‘;’ to ‘oz’ forces a one-line display that includes the unit;
1070 here the integer part of the result is zero, so it is not displayed.
1071 If a non-empty list item differs vastly in scale from the quantity from
1073 which the list is to be converted, you may exceed the available preci‐
1074 sion of floating point (about 15 digits), in which case you will get a
1075 warning, e.g.,
1076 You have: lightyear
1078 You want: mile;100 inch;10 inch;mm;micron
1079 5.8786254e+12 mile + 390 * 100 inch (at 15-digit precision limit)
1080 Cooking Measure
1082 In North America, recipes for cooking typically measure ingredients by
1083 volume, and use units that are not always convenient multiples of each
1084 other. Suppose that you have a recipe for 6 and you wish to make a
1085 portion for 1. If the recipe calls for 2 1/2 cups of an ingredient,
1086 you might wish to know the measurements in terms of measuring devices
1087 you have available, you could use units and enter
1088 You have: (2+1|2) cup / 6
1090 You want: cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
1091 1|3 cup + 1 tbsp + 1 tsp
1092 By default, if a unit in a list begins with fraction of the form 1|x
1094 and its multiplier is an integer, the fraction is given as the product
1095 of the multiplier and the numerator; for example,
1096 You have: 12.28125 ft
1098 You want: ft;in;1|8 in;
1099 12 ft + 3 in + 3|8 in
1100 In many cases, such as the example above, this is what is wanted, but
1102 sometimes it is not. For example, a cooking recipe for 6 might call
1103 for 5 1/4 cup of an ingredient, but you want a portion for 2, and your
1104 1-cup measure is not available; you might try
1105 You have: (5+1|4) cup / 3
1107 You want: 1|2 cup;1|3 cup;1|4 cup
1108 3|2 cup + 1|4 cup
1109 This result might be fine for a baker who has a 1 1/2-cup measure (and
1111 recognizes the equivalence), but it may not be as useful to someone
1112 with more limited set of measures, who does want to do additional cal‐
1113 culations, and only wants to know “How many 1/2-cup measures to I need
1114 to add?” After all, that’s what was actually asked. With the
1115 ‘--show-factor’ option, the factor will not be combined with a unity
1116 numerator, so that you get
1117 You have: (5+1|4) cup / 3
1119 You want: 1|2 cup;1|3 cup;1|4 cup
1120 3 * 1|2 cup + 1|4 cup
1121 A user-specified fractional unit with a numerator other than 1 is never
1123 overridden, however—if a unit list specifies ‘3|4 cup;1|2 cup’, a re‐
1124 sult equivalent to 1 1/2 cups will always be shown as ‘2 * 3|4 cup’
1125 whether or not the ‘--show-factor’ option is given.
1126 Unit List Aliases
1128 A unit list such as
1129 cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
1131 can be tedious to enter. The units program provides shorthand names
1133 for some common combinations:
1134 hms hours, minutes, seconds
1136 dms angle: degrees, minutes, seconds
1137 time years, days, hours, minutes and seconds
1138 usvol US cooking volume: cups and smaller
1139 ftin feet, inches and 1/8 inches
1140 inchfine inches subdivided to 1/64 inch
1141 Using these shorthands, or unit list aliases, you can do the following
1143 conversions:
1144 You have: anomalisticyear
1146 You want: time
1147 1 year + 25 min + 3.4653216 sec
1148 You have: 1|6 cup
1149 You want: usvol
1150 2 tbsp + 2 tsp
1151 You can define your own unit list aliases; see Defining Unit List
1153 Aliases.
1154 You cannot combine a unit list alias with other units: it must appear
1156 alone at the ‘You want:’ prompt.
1157 You can display the definition of a unit list alias by entering it at
1159 the ‘You have:’ prompt:
1160 You have: dms
1162 Definition: unit list, deg;arcmin;arcsec
1163 When you specify compact output with ‘--compact’, ‘--terse’ or ‘-t’ and
1165 perform conversion to a unit list, units lists the conversion factors
1166 for each unit in the list, separated by semicolons.
1167 You have: year
1169 You want: day;min;sec
1170 365;348;45.974678
1171 Unlike the case of regular output, zeros are included in this output
1173 list:
1174 You have: liter
1176 You want: cup;1|2 cup;1|4 cup;tbsp
1177 4;0;0;3.6280454
1178
1180 CGS Units
1181 The SI—an extension of the MKS (meter–kilogram–second) system—has
1182 largely supplanted the older CGS (centimeter–gram–second) system, but
1183 CGS units are still used in a few specialized fields, especially in
1184 physics where they lead to a more elegant formulation of Maxwell’s
1185 equations. Conversions between SI and CGS involving mechanical units
1186 are straightforward, involving powers of 10 (e.g., 1 m = 100 cm). Con‐
1187 versions involving electromagnetic units are more complicated, and
1188 units supports four different systems of CGS units: electrostatic units
1189 (ESU), electromagnetic units (EMU), the Gaussian system and the Heavi‐
1190 side–Lorentz system. The differences between these systems arise from
1191 different choices made for proportionality constants in electromagnetic
1192 equations. Coulomb’s law gives electrostatic force between two charges
1193 separated by a distance delim $$ r:
1194 F = k_C q_1 q_2 / r^2.
1196 Ampere’s law gives the electromagnetic force per unit length between
1198 two current-carrying conductors separated by a distance r:
1199 F/l = 2 k_A I_1 I_2 / r.
1201 The two constants, k_C and k_A, are related by the square of the speed
1203 of light: k_A = k_C / c^2.
1204 In the SI, the constants have dimensions, and an additional base unit,
1206 the ampere, measures electric current. The CGS systems do not define
1207 new base units, but express charge and current as derived units in
1208 terms of mass, length, and time. In the ESU system, the constant for
1209 Coulomb’s law is chosen to be unity and dimensionless, which defines
1210 the unit of charge. In the EMU system, the constant for Ampere’s law
1211 is chosen to be unity and dimensionless, which defines a unit of cur‐
1212 rent. The Gaussian system usually uses the ESU units for charge and
1213 current; it chooses another constant so that the units for the electric
1214 and magnetic fields are the same. The Heaviside–Lorentz system is “ra‐
1215 tionalized” so that factors of 4{pi} do not appear in Maxwell’s equa‐
1216 tions. The SI system is similarly rationalized, but the other CGS sys‐
1217 tems are not. In the Heaviside–Lorentz (HLU) system the factor of
1218 4{pi} appears in Coulomb’s law instead; this system differs from the
1219 Gaussian system by factors of the square root of 4{pi}
1220 The dimensions of electrical quantities in the various CGS systems are
1222 different from the SI dimensions for the same units; strictly, conver‐
1223 sions between these systems and SI are not possible. But units in dif‐
1224 ferent systems relate to the same physical quantities, so there is a
1225 correspondence between these units. The units program defines the
1226 units so that you can convert between corresponding units in the vari‐
1227 ous systems.
1228 The CGS definitions involve cm^(1/2) and g^(1/2), which is problematic
1230 because units does not normally support fractional roots of base units.
1231 The ‘--units’ (‘-u’) option allows selection of a CGS unit system and
1232 works around this restriction by introducing base units for the square
1233 roots of length and mass: ‘sqrt_cm’ and ‘sqrt_g’. The centimeter then
1234 becomes ‘sqrt_cm^2’ and the gram, ‘sqrt_g^2’. This allows working from
1235 equations using the units in the CGS system, and enforcing dimensional
1236 conformity within that system. Recognized CGS arguments to the
1237 ‘--units’ option are ‘gauss[ian]’, ‘esu’, ‘emu’, ‘lhu’; the argument is
1238 case insensitive. You can also give ‘si’ which just enforces the de‐
1239 fault SI mode and displays ‘(SI)’ at the ‘You have:’ prompt to empha‐
1240 size the units mode. Some other types of units are also supported as
1241 described below. Giving an unrecognized system generates a warning,
1242 and units uses SI units.
1243 The changes resulting from the ‘--units’ option are actually controlled
1245 by the UNITS_SYSTEM environment variable. If you frequently work with
1246 one of the supported CGS units systems, you may set this environment
1247 variable rather than giving the ‘--units’ option at each invocation.
1248 As usual, an option given on the command line overrides the setting of
1249 the environment variable. For example, if you would normally work with
1250 Gaussian units but might occasionally work with SI, you could set
1251 UNITS_SYSTEM to ‘gaussian’ and specify SI with the ‘--units’ option.
1252 Unlike the argument to the ‘--units’ option, the value of UNITS_SYSTEM
1253 is case sensitive, so setting a value of ‘EMU’ will have no effect
1254 other than to give an error message and set SI units.
1255 The CGS definitions appear as conditional settings in the standard
1257 units data file, which you can consult for more information on how
1258 these units are defined, or on how to define an alternate units system.
1259 The ESU system derives the electromagnetic units from its unit of
1261 charge, the statcoulomb, which is defined from Coulomb’s law. The
1262 statcoulomb equals dyne^(1/2) cm, or cm^(3/2) g^(1/2) s^(−1). The unit
1263 of current, the statampere, is statcoulomb sec, analogous to the rela‐
1264 tionship in SI. Other electrical units are then derived in a manner
1265 similar to that for SI units; the units use the SI names prefixed by
1266 ‘stat-’, e.g., ‘statvolt’ or ‘statV’. The prefix ‘st-’ is also recog‐
1267 nized (e.g., ‘stV’).
1268 The EMU system derives the electromagnetic units from its unit of cur‐
1270 rent, the abampere, which is defined in terms of Ampere’s law. The
1271 abampere is equal to dyne^(1/2), or cm^(1/2) g^(1/2) s^(−1). delim off
1272 The unit of charge, the abcoulomb, is abampere sec, again analogous to
1273 the SI relationship. Other electrical units are then derived in a man‐
1274 ner similar to that for SI units; the units use the SI names prefixed
1275 by ‘ab-’, e.g., ‘abvolt’ or ‘abV’. The magnetic field units include
1276 the gauss, the oersted and the maxwell.
1277 The Gaussian units system, which was also known as the Symmetric Sys‐
1279 tem, uses the same charge and current units as the ESU system (e.g.,
1280 ‘statC’, ‘statA’); it differs by defining the magnetic field so that it
1281 has the same units as the electric field. The resulting magnetic field
1282 units are the same ones used in the EMU system: the gauss, the oersted
1283 and the maxwell.
1284 The Heaviside–Lorentz system appears to lack named units. We define
1286 five basic units, ‘hlu_charge’, ‘hlu_current’, ‘hlu_volt’, ‘hlu_efield’
1287 and ‘hlu_bfield’ for conversions with this system. It is important to
1288 remember that with all of the CGS systems, the units may look the same
1289 but mean something different. The HLU system and Gaussian systems both
1290 measure magnetic field using the same CGS dimensions, but the amount of
1291 magnetic field with the same units is different in the two systems.
1292 The CGS systems define units that measure the same thing but may have
1294 conflicting dimensions. Furthermore, the dimensions of the electromag‐
1295 netic CGS units are never compatible with SI. But if you measure
1296 charge in two different systems you have measured the same physical
1297 thing, so there is a correspondence between the units in the different
1298 systems, and units supports conversions between corresponding units.
1299 When running with SI, units defines all of the CGS units in terms of
1300 SI. When you select a CGS system, units defines the SI units and the
1301 other CGS system units in terms of the system you have selected.
1302 (Gaussian) You have: statA
1304 You want: abA
1305 * 3.335641e-11
1306 / 2.9979246e+10
1307 (Gaussian) You have: abA
1308 You want: sqrt(dyne)
1309 conformability error
1310 2.9979246e+10 sqrt_cm^3 sqrt_g / s^2
1311 1 sqrt_cm sqrt_g / s
1312 In the above example, units converts between the current units statA
1314 and abA even though the abA, from the EMU system, has incompatible di‐
1315 mensions. This works because in Gaussian mode, the abA is defined in
1316 terms of the statA, so it does not have the correct definition for EMU;
1317 consequently, you cannot convert the abA to its EMU definition.
1318 One challenge of conversion is that because the CGS system has fewer
1320 base units, quantities that have different dimensions in SI may have
1321 the same dimension in a CGS system. And yet, they may not have the
1322 same conversion factor. For example, the unit for the E field and B
1323 fields are the same in the Gaussian system, but the conversion factors
1324 to SI are quite different. This means that correct conversion is only
1325 possible if you keep track of what quantity is being measured. You
1326 cannot convert statV/cm to SI without indicating which type of field
1327 the unit measures. To aid in dimensional analysis, units defines vari‐
1328 ous dimension units such as LENGTH, TIME, and CHARGE to be the appro‐
1329 priate dimension in SI. The electromagnetic dimensions such as B_FIELD
1330 or E_FIELD may be useful aids both for conversion and dimensional
1331 analysis in CGS. You can convert them to or from CGS in order to per‐
1332 form SI conversions that in some cases will not work directly due to
1333 dimensional incompatibilities. This example shows how the Gaussian
1334 system uses the same units for all of the fields, but they all have
1335 different conversion factors with SI.
1336 (Gaussian) You have: statV/cm
1338 You want: E_FIELD
1339 * 29979.246
1340 / 3.335641e-05
1341 (Gaussian) You have: statV/cm
1342 You want: B_FIELD
1343 * 0.0001
1344 / 10000
1345 (Gaussian) You have: statV/cm
1346 You want: H_FIELD
1347 * 79.577472
1348 / 0.012566371
1349 (Gaussian) You have: statV/cm
1350 You want: D_FIELD
1351 * 2.6544187e-07
1352 / 3767303.1
1353 The next example shows that the oersted cannot be converted directly to
1355 the SI unit of magnetic field, A/m, because the dimensions conflict.
1356 We cannot redefine the ampere to make this work because then it would
1357 not convert with the statampere. But you can still do this conversion
1358 as shown below.
1359 (Gaussian) You have: oersted
1361 You want: A/m
1362 conformability error
1363 1 sqrt_g / s sqrt_cm
1364 29979246 sqrt_cm sqrt_g / s^2
1365 (Gaussian) You have: oersted
1366 You want: H_FIELD
1367 * 79.577472
1368 / 0.012566371
1369 Natural Units
1371 Like the CGS units, “natural” units are an alternative to the SI system
1372 used primarily physicists in different fields, with different systems
1373 tailored to different fields of study. These systems are “natural” be‐
1374 cause the base measurements are defined using physical constants in‐
1375 stead of arbitrary values such as the meter or second. In different
1376 branches of physics, different physical constants are more fundamental,
1377 which has given rise to a variety of incompatible natural unit systems.
1378 The supported systems are the “natural” units (which seem to have no
1380 better name) used in high energy physics and cosmology, the Planck
1381 units, often used my scientists working with gravity, and the Hartree
1382 atomic units are favored by those working in physical chemistry and
1383 condensed matter physics.
1384 You can select the various natural units using the ‘--units’ option in
1386 the same way that you select the CGS units. The “natural” units come
1387 in two types, a rationalized system derived from the Heaviside–Lorentz
1388 units and an unrationalized system derived from the Gaussian system.
1389 You can select these using ‘natural’ and ‘natural-gauss’ respectively.
1390 For conversions in SI mode, several unit names starting with ‘natural’
1391 are available. This “natural” system is defined by setting {hbar}, c
1392 and the Boltzman constant to 1. Only a single base unit remains: the
1393 electron volt.
1394 The Planck units exist in a variety of forms, and units supports two.
1396 Both supported forms are rationalized, in that factors of 4{pi} do not
1397 appear in Maxwell’s equations. However, Planck units can also differ
1398 based on how the gravitational constant is treated. This system is
1399 similar to the natural units in that c, {hbar}, and Boltzman’s constant
1400 are set to 1, but in this system, Newton’s gravitational constant, G is
1401 also fixed. In the “reduced” Planck system, delim $$ 8{pi}G = 1
1402 whereas in the unreduced system G = 1. The reduced system eliminates
1403 factors of 8{pi} delim off from the Einstein field equations for gravi‐
1404 tation, so this is similar to the process of forming rationalized units
1405 to simplify Maxwell’s equations. To obtain the unreduced system use
1406 the name ‘planck’ and for the reduced Planck units, ‘planck-red’.
1407 Units such as ‘planckenergy’ and ‘planckenergy_red’ enable you to con‐
1408 vert the unreduced and reduced Planck energy unit in SI mode between
1409 the various systems. In Planck units, all measurements are dimension‐
1410 less.
1411 The final natural unit system is the Hartree atomic units. Like the
1413 Planck units, all measurements in the Hartree units are dimensionless,
1414 but this system is defined by defined from completely different physi‐
1415 cal constants: the electron mass, Planck’s constant, the electron
1416 charge, and the Coulomb constant are the defining physical quantities,
1417 which are all set to unity. To invoke this system with the ‘--units’
1418 option use the name ‘hartree’.
1419 Prompt Prefix
1421 If a unit system is specified with the ‘--units’ option, the selected
1422 system’s name is prepended to the ‘You have:’ prompt as a reminder,
1423 e.g.,
1424 (Gaussian) You have: stC
1426 You want:
1427 Definition: statcoulomb = sqrt(dyne) cm = 1 sqrt_cm^3 sqrt_g / s
1428 You can suppressed the prefix by including a line
1430 !prompt
1432 with no argument in a site or personal units data file. The prompt can
1434 be conditionally suppressed by including such a line within ‘!var’ ...
1435 ‘!endvar’ constructs, e.g.,
1436 !var UNITS_SYSTEM gaussian gauss
1438 !prompt
1439 !endvar
1440 This might be appropriate if you normally use Gaussian units and find
1442 the prefix distracting but want to be reminded when you have selected a
1443 different CGS system.
1444
1446 The ‘--log’ option allows you to save the results of calculations in a
1447 file; this can be useful if you need a permanent record of your work.
1448 For example, the fluid-flow conversion in Complicated Unit Expressions,
1449 is lengthy, and if you were to use it in designing a piping system, you
1450 might want a record of it for the project file. If the interactive
1451 session
1452 # Conversion factor A1 for pressure drop
1454 # dP = A1 rho f L Q^2/d^5
1455 You have: (8/pi^2) (lbm/ft^3)ft(ft^3/s)^2(1/in^5) # Input units
1456 You want: psi
1457 * 43.533969
1458 / 0.022970568
1459 were logged, the log file would contain
1461 ### Log started Fri Oct 02 15:55:35 2015
1463 # Conversion factor A1 for pressure drop
1465 # dP = A1 rho f L Q^2/d^5
1466 From: (8/pi^2) (lbm/ft^3)ft(ft^3/s)^2(1/in^5) # Input units
1467 To: psi
1468 * 43.533969
1469 / 0.022970568
1470 The time is written to the log file when the file is opened.
1472 The use of comments can help clarify the meaning of calculations for
1474 the log. The log includes conformability errors between the units at
1475 the ‘You have:’ and ‘You want:’ prompts, but not other errors, includ‐
1476 ing lack of conformability of items in sums or differences or among
1477 items in a unit list. For example, a conversion between zenith angle
1478 and elevation angle could involve
1479 You have: 90 deg - (5 deg + 22 min + 9 sec)
1481 ^
1482 Illegal sum or difference of non-conformable units
1483 You have: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
1484 You want: dms
1485 84 deg + 37 arcmin + 51 arcsec
1486 You have: _
1487 You want: deg
1488 * 84.630833
1489 / 0.011816024
1490 You have:
1491 The log file would contain
1493 From: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
1495 To: deg;arcmin;arcsec
1496 84 deg + 37 arcmin + 51 arcsec
1497 From: _
1498 To: deg
1499 * 84.630833
1500 / 0.011816024
1501 The initial entry error (forgetting that minutes have dimension of
1503 time, and that arcminutes must be used for dimensions of angle) does
1504 not appear in the output. When converting to a unit list alias, units
1505 expands the alias in the log file.
1506 The ‘From:’ and ‘To:’ tags are written to the log file even if the
1508 ‘--quiet’ option is given. If the log file exists when units is in‐
1509 voked, the new results are appended to the log file. The time is writ‐
1510 ten to the log file each time the file is opened. The ‘--log’ option
1511 is ignored when units is used non-interactively.
1512
1514 You invoke units like this:
1515 units [options] [from-unit [to-unit]]
1517 If the from-unit and to-unit are omitted, the program will use interac‐
1519 tive prompts to determine which conversions to perform. See Interac‐
1520 tive Use. If both from-unit and to-unit are given, units will print
1521 the result of that single conversion and then exit. If only from-unit
1522 appears on the command line, units will display the definition of that
1523 unit and exit. Units specified on the command line may need to be
1524 quoted to protect them from shell interpretation and to group them into
1525 two arguments. Note also that the ‘--quiet’ option is enabled by de‐
1526 fault if you specify from-unit on the command line. See Command Line
1527 Use.
1528 The default behavior of units can be changed by various options given
1530 on the command line. In most cases, the options may be given in either
1531 short form (a single ‘-’ followed by a single character) or long form
1532 (‘--’ followed by a word or hyphen-separated words). Short-form op‐
1533 tions are cryptic but require less typing; long-form options require
1534 more typing but are more explanatory and may be more mnemonic. With
1535 long-form options you need only enter sufficient characters to uniquely
1536 identify the option to the program. For example, ‘--out %f’ works, but
1537 ‘--o %f’ fails because units has other long options beginning with ‘o’.
1538 However, ‘--q’ works because ‘--quiet’ is the only long option begin‐
1539 ning with ‘q’.
1540 Some options require arguments to specify a value (e.g., ‘-d 12’ or
1542 ‘--digits 12’). Short-form options that do not take arguments may be
1543 concatenated (e.g., ‘-erS’ is equivalent to ‘-e -r -S’); the last op‐
1544 tion in such a list may be one that takes an argument (e.g., ‘-ed 12’).
1545 With short-form options, the space between an option and its argument
1546 is optional (e.g., ‘-d12’ is equivalent to ‘-d 12’). Long-form options
1547 may not be concatenated, and the space between a long-form option and
1548 its argument is required. Short-form and long-form options may be in‐
1549 termixed on the command line. Options may be given in any order, but
1550 when incompatible options (e.g., ‘--output-format’ and ‘--exponential’)
1551 are given in combination, behavior is controlled by the last option
1552 given. For example, ‘-o%.12f -e’ gives exponential format with the de‐
1553 fault eight significant digits).
1554 The following options are available:
1556 -c, --check
1558 Check that all units and prefixes defined in the units data file
1559 reduce to primitive units. Print a list of all units that can‐
1560 not be reduced. Also display some other diagnostics about sus‐
1561 picious definitions in the units data file. Only definitions
1562 active in the current locale are checked. You should always run
1563 units with this option after modifying a units data file.
1564 --check-verbose, --verbose-check
1566 Like the ‘--check’ option, this option prints a list of units
1567 that cannot be reduced. But to help find unit definitions that
1568 cause endless loops, it lists the units as they are checked. If
1569 units hangs, then the last unit to be printed has a bad defini‐
1570 tion. Only definitions active in the current locale are
1571 checked.
1572 -d ndigits, --digits ndigits
1574 Set the number of significant digits in the output to the value
1575 specified (which must be greater than zero). For example,
1576 ‘-d 12’ sets the number of significant digits to 12. With expo‐
1577 nential output units displays one digit to the left of the deci‐
1578 mal point and eleven digits to the right of the decimal point.
1579 On most systems, the maximum number of internally meaningful
1580 digits is 15; if you specify a greater number than your system’s
1581 maximum, units will print a warning and set the number to the
1582 largest meaningful value. To directly set the maximum value,
1583 give an argument of max (e.g., ‘-d max’). Be aware, of course,
1584 that “significant” here refers only to the display of numbers;
1585 if results depend on physical constants not known to this preci‐
1586 sion, the physically meaningful precision may be less than that
1587 shown. The ‘--digits’ option conflicts with the
1588 ‘--output-format’ option.
1589 -e, --exponential
1591 Set the numeric output format to exponential (i.e., scientific
1592 notation), like that used in the Unix units program. The de‐
1593 fault precision is eight significant digits (seven digits to the
1594 right of the decimal point); this can be changed with the
1595 ‘--digits’ option. The ‘--exponential’ option conflicts with
1596 the ‘--output-format’ option.
1597 -o format, --output-format format
1599 This option affords complete control over the numeric output
1600 format using the specified format. The format is a single float‐
1601 ing point numeric format for the printf() function in the C pro‐
1602 gramming language. All compilers support the format types ‘g’
1603 and ‘G’ to specify significant digits, ‘e’ and ‘E’ for scien‐
1604 tific notation, and ‘f’ for fixed-point decimal. The ISO C99
1605 standard introduced the ‘F’ type for fixed-point decimal and the
1606 ‘a’ and ‘A’ types for hexadecimal floating point; these types
1607 are allowed with compilers that support them. The default for‐
1608 mat is ‘%.8g’; for greater precision, you could specify
1609 ‘-o %.15g’. See Numeric Output Format and the documentation for
1610 printf() for more detailed descriptions of the format specifica‐
1611 tion. The ‘--output-format’ option affords the greatest control
1612 of the output appearance, but requires at least rudimentary
1613 knowledge of the printf() format syntax. If you don’t want to
1614 bother with the printf() syntax, you can specify greater preci‐
1615 sion more simply with the ‘--digits’ option or select exponen‐
1616 tial format with ‘--exponential’. The ‘--output-format’ option
1617 is incompatible with the ‘--exponential’ and ‘--digits’ options.
1618 -f filename, --file filename
1620 Instruct units to load the units file filename. You can specify
1621 up to 25 units files on the command line. When you use this op‐
1622 tion, units will load only the files you list on the command
1623 line; it will not load the standard file or your personal units
1624 file unless you explicitly list them. If filename is the empty
1625 string (‘-f ""’), the default units file (or that specified by
1626 UNITSFILE) will be loaded in addition to any others specified
1627 with ‘-f’.
1628 -L logfile, --log logfile
1630 Save the results of calculations in the file logfile; this can
1631 be useful if it is important to have a record of unit conver‐
1632 sions or other calculations that are to be used extensively or
1633 in a critical activity such as a program or design project. If
1634 logfile exits, the new results are appended to the file. This
1635 option is ignored when units is used non-interactively. See
1636 Logging Calculations for a more detailed description and some
1637 examples.
1638 -H filename, --history filename
1640 Instruct units to save history to filename, so that a record of
1641 your commands is available for retrieval across different units
1642 invocations. To prevent the history from being saved set file‐
1643 name to the empty string (‘-H ""’). This option has no effect
1644 if readline is not available.
1645 -h, --help
1647 Print out a summary of the options for units.
1648 -m, --minus
1650 Causes ‘-’ to be interpreted as a subtraction operator. This is
1651 the default behavior.
1652 -p, --product
1654 Causes ‘-’ to be interpreted as a multiplication operator when
1655 it has two operands. It will act as a negation operator when it
1656 has only one operand: ‘(-3)’. By default ‘-’ is treated as a
1657 subtraction operator.
1658 --oldstar
1660 Causes ‘*’ to have the old-style precedence, higher than the
1661 precedence of division so that ‘1/2*3’ will equal ‘1/6’.
1662 --newstar
1664 Forces ‘*’ to have the new (default) precedence that follows the
1665 usual rules of algebra: the precedence of ‘*’ is the same as the
1666 precedence of ‘/’, so that ‘1/2*3’ will equal ‘3/2’.
1667 -r, --round
1669 When converting to a combination of units given by a unit list,
1670 round the value of the last unit in the list to the nearest in‐
1671 teger.
1672 -S, --show-factor
1674 When converting to a combination of units specified in a list,
1675 always show a non-unity factor before a unit that begins with a
1676 fraction with a unity denominator. By default, if the unit in a
1677 list begins with fraction of the form 1|x and its multiplier is
1678 an integer other than 1, the fraction is given as the product of
1679 the multiplier and the numerator (e.g., ‘3|8 in’ rather than ‘3
1680 * 1|8 in’). In some cases, this is not what is wanted; for ex‐
1681 ample, the results for a cooking recipe might show ‘3 * 1|2 cup’
1682 as ‘3|2 cup’. With the ‘--show-factor’ option, a result equiva‐
1683 lent to 1.5 cups will display as ‘3 * 1|2 cup’ rather than
1684 ‘3|2 cup’. A user-specified fractional unit with a numerator
1685 other than 1 is never overridden, however—if a unit list speci‐
1686 fies ‘3|4 cup;1|2 cup’, a result equivalent to 1 1/2 cups will
1687 always be shown as ‘2 * 3|4 cup’ whether or not the
1688 ‘--show-factor’ option is given.
1689 --conformable
1691 In non-interactive mode, show all units conformable with the
1692 original unit expression. Only one unit expression is allowed;
1693 if you give more than one, units will exit with an error message
1694 and return failure.
1695 -v, --verbose
1697 Give slightly more verbose output when converting units. When
1698 combined with the ‘-c’ option this gives the same effect as
1699 ‘--check-verbose’. When combined with ‘--version’ produces a
1700 more detailed output, equivalent to the ‘--info’ option.
1701 -V, --version
1703 Print the program version number, tell whether the readline li‐
1704 brary has been included, tell whether UTF-8 support has been in‐
1705 cluded; give the locale, the location of the default units data
1706 file, and the location of the personal units data file; indicate
1707 if the personal units data file does not exist.
1708 When given in combination with the ‘--terse’ option, the program
1710 prints only the version number and exits.
1711 When given in combination with the ‘--verbose’ option, the pro‐
1713 gram, the ‘--version’ option has the same effect as the ‘--info’
1714 option below.
1715 -I, --info
1717 Print the information given with the ‘--version’ option, show
1718 the pathname of the units program, show the status of the
1719 UNITSFILE and MYUNITSFILE environment variables, and additional
1720 information about how units locates the related files. On sys‐
1721 tems running Microsoft Windows, the status of the UNITSLOCALE
1722 environment variable and information about the related locale
1723 map are also given. This option is usually of interest only to
1724 developers and administrators, but it can sometimes be useful
1725 for troubleshooting.
1726 Combining the ‘--version’ and ‘--verbose’ options has the same
1728 effect as giving ‘--info’.
1729 -U, --unitsfile
1731 Print the location of the default units data file and exit; if
1732 the file cannot be found, print “Units data file not found”.
1733 -u units-system, --units units-system
1735 Specify a CGS units system or natural units system. The sup‐
1736 ported units systems are: gauss[ian], esu, emu, hlu, natural,
1737 natural-gauss, hartree, planck, planck-red, and si. See Alterna‐
1738 tive Unit Systems for further information about these unit sys‐
1739 tems.
1740 -l locale, --locale locale
1742 Force a specified locale such as ‘en_GB’ to get British defini‐
1743 tions by default. This overrides the locale determined from
1744 system settings or environment variables. See Locale for a de‐
1745 scription of locale format.
1746 -n, --nolists
1748 Disable conversion to unit lists.
1749 -s, --strict
1751 Suppress conversion of units to their reciprocal units. For ex‐
1752 ample, units will normally convert hertz to seconds because
1753 these units are reciprocals of each other. The strict option
1754 requires that units be strictly conformable to perform a conver‐
1755 sion, and will give an error if you attempt to convert hertz to
1756 seconds.
1757 -1, --one-line
1759 Give only one line of output (the forward conversion); do not
1760 print the reverse conversion. If a reciprocal conversion is
1761 performed, then units will still print the “reciprocal conver‐
1762 sion” line.
1763 -t, --terse
1765 Print only a single conversion factor. This option can be used
1766 when calling units from another program so that the output is
1767 easy to parse. This option has the combined effect of these op‐
1768 tions: ‘--strict’ ‘--quiet’ ‘--one-line’ ‘--compact’. When
1769 combined with ‘--version’ it produces a display showing only the
1770 program name and version number.
1771 --compact
1773 Give compact output featuring only the conversion factor; the
1774 multiplication and division signs are not shown, and there is no
1775 leading whitespace. If you convert to a unit list, then the
1776 output is a semicolon separated list of factors. This turns off
1777 the ‘--verbose’ option.
1778 -q, --quiet, --silent
1780 Suppress the display of statistics about the number of units
1781 loaded, any messages printed by the units database, and the
1782 prompting of the user for units. This option does not affect
1783 how units displays the results. This option is turned on by de‐
1784 fault if you invoke units with a unit expression on the command
1785 line.
1786
1788 Despite its numerous options, units cannot cover every conceivable
1789 unit-conversion task. For example, suppose we have found some mysteri‐
1790 ous scale, but cannot figure out the units in which it is reporting.
1791 We reach into our pocket, place a 3.75-gram coin on the scale, and ob‐
1792 serve the scale reading ‘0.120’. How do we quickly determine the
1793 units? Or we might wonder if a unit has any “synonyms,” i.e., other
1794 units with the same value.
1795 The capabilities of units are easily extended with simple scripting.
1797 Both questions above involve conformable units; on a system with Unix-
1798 like utilities, conversions to conformable units could be shown accom‐
1799 plished with the following script:
1800 #!/bin/sh
1802 progname=`basename $0 .sh`
1804 umsg="Usage: $progname [<number>] unit"
1805 if [ $# -lt 1 ]
1807 then
1808 echo "$progname: missing quantity to convert"
1809 echo "$umsg"
1810 exit 1
1811 fi
1812 for unit in `units --conformable "$*" | cut -f 1 -d ' '`
1814 do
1815 echo "$*" # have -- quantity to convert
1816 echo $unit # want -- conformable unit
1817 done | units --terse --verbose
1818 When units is invoked with no non-option arguments, it reads have/want
1820 pairs, on alternating lines, from its standard input, so the task can
1821 be accomplished with only two invocations of units. This avoids the
1822 computational overhead of needlessly reprocessing the units database
1823 for each conformable unit, as well as the inherent system overhead of
1824 process invocation.
1825 By itself, the script is not very useful. But it could be used in com‐
1827 bination with other commands to address specific tasks. For example,
1828 running the script through a simple output filter could help solve the
1829 scale problem above. If the script is named conformable, running
1830 $ conformable 3.75g | grep 0.120
1832 gives
1834 3.75g = 0.1205653 apounce
1835 3.75g = 0.1205653 fineounce
1836 3.75g = 0.1205653 ozt
1837 3.75g = 0.1205653 tradewukiyeh
1838 3.75g = 0.1205653 troyounce
1839 So we might conclude that the scale is calibrated in troy ounces.
1841 We might run
1843 $ units --verbose are
1844 Definition: 100 m^2 = 100 m^2
1845 and wonder if ‘are’ has any synonyms, value. To find out, we could run
1847 $ conformable are | grep "= 1 "
1849 are = 1 a
1850 are = 1 are
1851
1853 The output can be tweaked in various ways using command line options.
1854 With no options, the output looks like this
1855 $ units
1857 Currency exchange rates from FloatRates (USD base) on 2019-02-20
1858 3070 units, 109 prefixes, 109 nonlinear units
1859 You have: 23ft
1861 You want: m
1862 * 7.0104
1863 / 0.14264521
1864 You have: m
1865 You want: ft;in
1866 3 ft + 3.3700787 in
1867 This is arguably a bit cryptic; the ‘--verbose’ option makes clear what
1869 the output means:
1870 $ units --verbose
1872 Currency exchange rates from FloatRates (USD base) on 2019-02-20
1873 3070 units, 109 prefixes, 109 nonlinear units
1874 You have: 23 ft
1876 You want: m
1877 23 ft = 7.0104 m
1878 23 ft = (1 / 0.14264521) m
1879 You have: meter
1880 You want: ft;in
1881 meter = 3 ft + 3.3700787 in
1882 The ‘--quiet’ option suppresses the clutter displayed when units
1884 starts, as well as the prompts to the user. This option is enabled by
1885 default when you give units on the command line.
1886 $ units --quiet
1888 23 ft
1889 m
1890 * 7.0104
1891 / 0.14264521
1892 $ units 23ft m
1894 * 7.0104
1895 / 0.14264521
1896 The remaining style options allow you to display only numerical values
1898 without the tab or the multiplication and division signs, or to display
1899 just a single line showing the forward conversion:
1900 $ units --compact 23ft m
1902 7.0104
1903 0.14264521
1904 $ units --compact m 'ft;in'
1906 3;3.3700787
1907 $ units --one-line 23ft m
1909 * 7.0104
1910 $ units --one-line 23ft 1/m
1912 reciprocal conversion
1913 * 0.14264521
1914 $ units --one-line 23ft kg
1916 conformability error
1917 7.0104 m
1918 1 kg
1919 Note that when converting to a unit list, the ‘--compact’ option dis‐
1921 plays a semicolon separated list of results. Also be aware that the
1922 ‘one-line’ option doesn't live up to its name if you execute a recipro‐
1923 cal conversion or if you get a conformability error. The former case
1924 can be prevented using the ‘--strict’ option, which suppresses recipro‐
1925 cal conversions. Similarly you can suppress unit list conversion using
1926 ‘--nolists’. It is impossible to prevent the three line error output.
1927 $ units --compact --nolists m 'ft;in'
1929 Error in 'ft;in': Parse error
1930 $ units --one-line --strict 23ft 1/m
1932 The various style options can be combined appropriately. The ultimate
1934 combination is the ‘--terse’ option, which combines ‘--strict’,
1935 ‘--quiet’, ‘--one-line’, and ‘--compact’ to produce the minimal output,
1936 just a single number for regular conversions and a semicolon separated
1937 list for conversion to unit lists. This will likely be the best choice
1938 for programs that want to call units and then process its result.
1939 $ units --terse 23ft m
1941 7.0104
1942 $ units --terse m 'ft;in'
1944 3;3.3700787
1945 $ units --terse 23ft 1/m
1947 conformability error
1948 7.0104 m
1949 1 / m
1950
1952 Units Data Files
1953 The units and prefixes that units can convert are defined in the units
1954 data file, typically ‘/usr/share/units/definitions.units’. If you
1955 can’t find this file, run units --version to get information on the
1956 file locations for your installation. Although you can extend or mod‐
1957 ify this data file if you have appropriate user privileges, it’s usu‐
1958 ally better to put extensions in separate files so that the definitions
1959 will be preserved if you update units.
1960 You can include additional data files in the units database using the
1962 ‘!include’ command in the standard units data file. For example
1963 !include /usr/local/share/units/local.units
1965 might be appropriate for a site-wide supplemental data file. The loca‐
1967 tion of the ‘!include’ statement in the standard units data file is im‐
1968 portant; later definitions replace earlier ones, so any definitions in
1969 an included file will override definitions before the ‘!include’ state‐
1970 ment in the standard units data file. With normal invocation, no warn‐
1971 ing is given about redefinitions; to ensure that you don’t have an un‐
1972 intended redefinition, run units -c after making changes to any units
1973 data file.
1974 If you want to add your own units in addition to or in place of stan‐
1976 dard or site-wide supplemental units data files, you can include them
1977 in the ‘.units’ file in your home directory. If this file exists it is
1978 read after the standard units data file, so that any definitions in
1979 this file will replace definitions of the same units in the standard
1980 data file or in files included from the standard data file. This file
1981 will not be read if any units files are specified on the command line.
1982 (Under Windows the personal units file is named ‘unitdef.units’.) Run‐
1983 ning units -V will display the location and name of your personal units
1984 file.
1985 The units program first tries to determine your home directory from the
1987 HOME environment variable. On systems running Microsoft Windows, if
1988 HOME does not exist, units attempts to find your home directory from
1989 HOMEDRIVE, HOMEPATH and USERPROFILE. You can specify an arbitrary file
1990 as your personal units data file with the MYUNITSFILE environment vari‐
1991 able; if this variable exists, its value is used without searching your
1992 home directory. The default units data files are described in more de‐
1993 tail in Data Files.
1994 Defining New Units and Prefixes
1996 A unit is specified on a single line by giving its name and an equiva‐
1997 lence. Comments start with a ‘#’ character, which can appear anywhere
1998 in a line. The backslash character (‘\’) acts as a continuation char‐
1999 acter if it appears as the last character on a line, making it possible
2000 to spread definitions out over several lines if desired. A file can be
2001 included by giving the command ‘!include’ followed by the file’s name.
2002 The ‘!’ must be the first character on the line. The file will be
2003 sought in the same directory as the parent file unless you give a full
2004 path. The name of the file to be included cannot contain spaces or the
2005 comment character ‘#’.
2006 Unit names must not contain any of the operator characters ‘+’, ‘-’,
2008 ‘*’, ‘/’, ‘|’, ‘^’, ‘;’, ‘~’, the comment character ‘#’, or parenthe‐
2009 ses. They cannot begin or end with an underscore (‘_’), a comma (‘,’)
2010 or a decimal point (‘.’). The figure dash (U+2012), typographical mi‐
2011 nus ('-’; U+2212), and en dash ('--’; U+2013) are converted to the op‐
2012 erator ‘-’, so none of these characters can appear in unit names.
2013 Names cannot begin with a digit, and if a name ends in a digit other
2014 than zero or one, the digit must be preceded by a string beginning with
2015 an underscore, and afterwards consisting only of digits, decimal
2016 points, or commas. For example, ‘foo_2’, ‘foo_2,1’, or ‘foo_3.14’ are
2017 valid names but ‘foo2’ or ‘foo_a2’ are invalid. The underscore is nec‐
2018 essary because without it, units cannot determine whether ‘foo2’ is a
2019 unit name or represents ‘foo^2’. Zero and one are exceptions because
2020 units never interprets them as exponents.
2021 You could define nitrous oxide as
2023 N2O nitrogen 2 + oxygen
2025 but would need to define nitrogen dioxide as
2027 NO_2 nitrogen + oxygen 2
2029 Be careful to define new units in terms of old ones so that a reduction
2031 leads to the primitive units, which are marked with ‘!’ characters.
2032 Dimensionless units are indicated by using the string ‘!dimensionless’
2033 for the unit definition.
2034 When adding new units, be sure to use the ‘-c’ option to check that the
2036 new units reduce properly. If you create a loop in the units defini‐
2037 tions, then units will hang when invoked with the ‘-c’ option. You
2038 will need to use the ‘--check-verbose’ option, which prints out each
2039 unit as it is checked. The program will still hang, but the last unit
2040 printed will be the unit that caused the infinite loop.
2041 If you define any units that contain ‘+’ characters in their defini‐
2043 tions, carefully check them because the ‘-c’ option will not catch non-
2044 conformable sums. Be careful with the ‘-’ operator as well. When used
2045 as a binary operator, the ‘-’ character can perform addition or multi‐
2046 plication depending on the options used to invoke units. To ensure
2047 consistent behavior use ‘-’ only as a unary negation operator when
2048 writing units definitions. To multiply two units leave a space or use
2049 the ‘*’ operator with care, recalling that it has two possible prece‐
2050 dence values and may require parentheses to ensure consistent behavior.
2051 To compute the difference of ‘foo’ and ‘bar’ write ‘foo+(-bar)’ or even
2052 ‘foo+-bar’.
2053 You may wish to intentionally redefine a unit. When you do this, and
2055 use the ‘-c’ option, units displays a warning message about the redefi‐
2056 nition. You can suppress these warnings by redefining a unit using a
2057 ‘+’ at the beginning of the unit name. Do not include any white space
2058 between the ‘+’ and the redefined unit name.
2059 Here is an example of a short data file that defines some basic units:
2061 m ! # The meter is a primitive unit
2063 sec ! # The second is a primitive unit
2064 rad !dimensionless # A dimensionless primitive unit
2065 micro- 1e-6 # Define a prefix
2066 minute 60 sec # A minute is 60 seconds
2067 hour 60 min # An hour is 60 minutes
2068 inch 72 m # Inch defined incorrectly terms of meters
2069 ft 12 inches # The foot defined in terms of inches
2070 mile 5280 ft # And the mile
2071 +inch 0.0254 m # Correct redefinition, warning suppressed
2072 A unit that ends with a ‘-’ character is a prefix. If a prefix defini‐
2074 tion contains any ‘/’ characters, be sure they are protected by paren‐
2075 theses. If you define ‘half- 1/2’, then ‘halfmeter’ would be equiva‐
2076 lent to ‘1 / (2 meter)’.
2077 Defining Nonlinear Units
2079 Some unit conversions of interest are nonlinear; for example, tempera‐
2080 ture conversions between the Fahrenheit and Celsius scales cannot be
2081 done by simply multiplying by conversion factors.
2082 When you give a linear unit definition such as ‘inch 2.54 cm’ you are
2084 providing information that units uses to convert values in inches into
2085 primitive units of meters. For nonlinear units, you give a functional
2086 definition that provides the same information.
2087 Nonlinear units are represented using a functional notation. It is
2089 best to regard this notation not as a function call but as a way of
2090 adding units to a number, much the same way that writing a linear unit
2091 name after a number adds units to that number. Internally, nonlinear
2092 units are defined by a pair of functions that convert to and from lin‐
2093 ear units in the database, so that an eventual conversion to primitive
2094 units is possible.
2095 Here is an example nonlinear unit definition:
2097 tempF(x) units=[1;K] domain=[-459.67,) range=[0,) \
2099 (x+(-32)) degF + stdtemp ; (tempF+(-stdtemp))/degF + 32
2100 A nonlinear unit definition comprises a unit name, a formal parameter
2102 name, two functions, and optional specifications for units, the domain,
2103 and the range (the domain of the inverse function). The functions tell
2104 units how to convert to and from the new unit. To produce valid re‐
2105 sults, the arguments of these functions need to have the correct dimen‐
2106 sions and be within the domains for which the functions are defined.
2107 The definition begins with the unit name followed immediately (with no
2109 spaces) by a ‘(’ character. In the parentheses is the name of the for‐
2110 mal parameter. Next is an optional specification of the units required
2111 by the functions in the definition. In the example above, the
2112 ‘units=[1;K]’ specification indicates that the ‘tempF’ function re‐
2113 quires an input argument conformable with ‘1’ (i.e., the argument is
2114 dimensionless), and that the inverse function requires an input argu‐
2115 ment conformable with ‘K’. For normal nonlinear units definition, the
2116 forward function will always take a dimensionless argument; in general,
2117 the inverse function will need units that match the quantity measured
2118 by your nonlinear unit. Specifying the units enables units to perform
2119 error checking on function arguments, and also to assign units to do‐
2120 main and range specifications, which are described later.
2121 Next the function definitions appear. In the example above, the
2123 ‘tempF’ function is defined by
2124 tempF(x) = (x+(-32)) degF + stdtemp
2126 This gives a rule for converting ‘x’ in the units ‘tempF’ to linear
2128 units of absolute temperature, which makes it possible to convert from
2129 tempF to other units.
2130 To enable conversions to Fahrenheit, you must give a rule for the in‐
2132 verse conversions. The inverse will be ‘x(tempF)’ and its definition
2133 appears after a ‘;’ character. In our example, the inverse is
2134 x(tempF) = (tempF+(-stdtemp))/degF + 32
2136 This inverse definition takes an absolute temperature as its argument
2138 and converts it to the Fahrenheit temperature. The inverse can be
2139 omitted by leaving out the ‘;’ character and the inverse definition,
2140 but then conversions to the unit will not be possible. If the inverse
2141 definition is omitted, the ‘--check’ option will display a warning. It
2142 is up to you to calculate and enter the correct inverse function to ob‐
2143 tain proper conversions; the ‘--check’ option tests the inverse at one
2144 point and prints an error if it is not valid there, but this is not a
2145 guarantee that your inverse is correct.
2146 With some definitions, the units may vary. For example, the definition
2148 square(x) x^2
2150 can have any arbitrary units, and can also take dimensionless argu‐
2152 ments. In such a case, you should not specify units. If a definition
2153 takes a root of its arguments, the definition is valid only for units
2154 that yield such a root. For example,
2155 squirt(x) sqrt(x)
2157 is valid for a dimensionless argument, and for arguments with even pow‐
2159 ers of units.
2160 Some definitions may not be valid for all real numbers. In such cases,
2162 units can handle errors better if you specify an appropriate domain and
2163 range. You specify the domain and range as shown below:
2164 baume(d) units=[1;g/cm^3] domain=[0,130.5] range=[1,10] \
2166 (145/(145-d)) g/cm^3 ; (baume+-g/cm^3) 145 / baume
2167 In this example the domain is specified after ‘domain=’ with the end‐
2169 points given in brackets. In accord with mathematical convention,
2170 square brackets indicate a closed interval (one that includes its end‐
2171 points), and parentheses indicate an open interval (one that does not
2172 include its endpoints). An interval can be open or closed on one or
2173 both ends; an interval that is unbounded on either end is indicated by
2174 omitting the limit on that end. For example, a quantity to which deci‐
2175 bel (dB) is applied may have any value greater than zero, so the range
2176 is indicated by ‘(0,)’:
2177 decibel(x) units=[1;1] range=(0,) 10^(x/10); 10 log(decibel)
2179 If the domain or range is given, the second endpoint must be greater
2181 than the first.
2182 The domain and range specifications can appear independently and in any
2184 order along with the units specification. The values for the domain
2185 and range endpoints are attached to the units given in the units speci‐
2186 fication, and if necessary, the parameter value is adjusted for compar‐
2187 ison with the endpoints. For example, if a definition includes
2188 ‘units=[1;ft]’ and ‘range=[3,)’, the range will be taken as 3 ft to in‐
2189 finity. If the function is passed a parameter of ‘900 mm’, that value
2190 will be adjusted to 2.9527559 ft, which is outside the specified range.
2191 If you omit the units specification from the previous example, units
2192 can not tell whether you intend the lower endpoint to be 3 ft or 3 mi‐
2193 crofurlongs, and can not adjust the parameter value of 900 mm for com‐
2194 parison. Without units, numerical values other than zero or plus or
2195 minus infinity for domain or range endpoints are meaningless, and ac‐
2196 cordingly they are not allowed. If you give other values without
2197 units, then the definition will be ignored and you will get an error
2198 message.
2199 Although the units, domain, and range specifications are optional, it’s
2201 best to give them when they are applicable; doing so allows units to
2202 perform better error checking and give more helpful error messages.
2203 Giving the domain and range also enables the ‘--check’ option to find a
2204 point in the domain to use for its point check of your inverse defini‐
2205 tion.
2206 You can make synonyms for nonlinear units by providing both the forward
2208 and inverse functions; inverse functions can be obtained using the ‘~’
2209 operator. So to create a synonym for ‘tempF’ you could write
2210 fahrenheit(x) units=[1;K] tempF(x); ~tempF(fahrenheit)
2212 This is useful for creating a nonlinear unit definition that differs
2214 slightly from an existing definition without having to repeat the orig‐
2215 inal functions. For example,
2216 dBW(x) units=[1;W] range=[0,) dB(x) W ; ~dB(dBW/W)
2218 If you wish a synonym to refer to an existing nonlinear unit without
2220 modification, you can do so more simply by adding the synonym with ap‐
2221 pended parentheses as a new unit, with the existing nonlinear unit—
2222 without parentheses—as the definition. So to create a synonym for
2223 ‘tempF’ you could write
2224 fahrenheit() tempF
2226 The definition must be a nonlinear unit; for example, the synonym
2228 fahrenheit() meter
2230 will result in an error message when units starts.
2232 You may occasionally wish to define a function that operates on units.
2234 This can be done using a nonlinear unit definition. For example, the
2235 definition below provides conversion between radius and the area of a
2236 circle. This definition requires a length as input and produces an
2237 area as output, as indicated by the ‘units=’ specification. Specifying
2238 the range as the nonnegative numbers can prevent cryptic error mes‐
2239 sages.
2240 circlearea(r) units=[m;m^2] range=[0,) pi r^2 ; sqrt(circlearea/pi)
2242 Defining Piecewise Linear Units
2244 Sometimes you may be interested in a piecewise linear unit such as many
2245 wire gauges. Piecewise linear units can be defined by specifying con‐
2246 versions to linear units on a list of points. Conversion at other
2247 points will be done by linear interpolation. A partial definition of
2248 zinc gauge is
2249 zincgauge[in] 1 0.002, 10 0.02, 15 0.04, 19 0.06, 23 0.1
2251 In this example, ‘zincgauge’ is the name of the piecewise linear unit.
2253 The definition of such a unit is indicated by the embedded ‘[’ charac‐
2254 ter. After the bracket, you should indicate the units to be attached
2255 to the numbers in the table. No spaces can appear before the ‘]’ char‐
2256 acter, so a definition like ‘foo[kg meters]’ is invalid; instead write
2257 ‘foo[kg*meters]’. The definition of the unit consists of a list of
2258 pairs optionally separated by commas. This list defines a function for
2259 converting from the piecewise linear unit to linear units. The first
2260 item in each pair is the function argument; the second item is the
2261 value of the function at that argument (in the units specified in
2262 brackets). In this example, we define ‘zincgauge’ at five points. For
2263 example, we set ‘zincgauge(1)’ equal to ‘0.002 in’. Definitions like
2264 this may be more readable if written using continuation characters
2265 as
2266 zincgauge[in] \
2268 1 0.002 \
2269 10 0.02 \
2270 15 0.04 \
2271 19 0.06 \
2272 23 0.1
2273 With the preceding definition, the following conversion can be per‐
2275 formed:
2276 You have: zincgauge(10)
2278 You want: in
2279 * 0.02
2280 / 50
2281 You have: .01 inch
2282 You want: zincgauge
2283 5
2284 If you define a piecewise linear unit that is not strictly monotonic,
2286 then the inverse will not be well defined. If the inverse is requested
2287 for such a unit, units will return the smallest inverse.
2288 After adding nonlinear units definitions, you should normally run
2290 units --check to check for errors. If the ‘units’ keyword is not
2291 given, the ‘--check’ option checks a nonlinear unit definition using a
2292 dimensionless argument, and then checks using an arbitrary combination
2293 of units, as well as the square and cube of that combination; a warning
2294 is given if any of these tests fail. For example,
2295 Warning: function 'squirt(x)' defined as 'sqrt(x)'
2297 failed for some test inputs:
2298 squirt(7(kg K)^1): Unit not a root
2299 squirt(7(kg K)^3): Unit not a root
2300 Running units --check will print a warning if a non-monotonic piecewise
2302 linear unit is encountered. For example, the relationship between ANSI
2303 coated abrasive designation and mean particle size is non-monotonic in
2304 the vicinity of 800 grit:
2305 ansicoated[micron] \
2307 . . .
2308 600 10.55 \
2309 800 11.5 \
2310 1000 9.5 \
2311 Running units --check would give the error message
2313 Table 'ansicoated' lacks unique inverse around entry 800
2315 Although the inverse is not well defined in this region, it’s not re‐
2317 ally an error. Viewing such error messages can be tedious, and if
2318 there are enough of them, they can distract from true errors. Error
2319 checking for nonlinear unit definitions can be suppressed by giving the
2320 ‘noerror’ keyword; for the examples above, this could be done as
2321 squirt(x) noerror domain=[0,) range=[0,) sqrt(x); squirt^2
2323 ansicoated[micron] noerror \
2324 . . .
2325 Use the ‘noerror’ keyword with caution. The safest approach after
2327 adding a nonlinear unit definition is to run units --check and confirm
2328 that there are no actual errors before adding the ‘noerror’ keyword.
2329 Defining Unit List Aliases
2331 Unit list aliases are treated differently from unit definitions, be‐
2332 cause they are a data entry shorthand rather than a true definition for
2333 a new unit. A unit list alias definition begins with ‘!unitlist’ and
2334 includes the alias and the definition; for example, the aliases in‐
2335 cluded in the standard units data file are
2336 !unitlist hms hr;min;sec
2338 !unitlist time year;day;hr;min;sec
2339 !unitlist dms deg;arcmin;arcsec
2340 !unitlist ftin ft;in;1|8 in
2341 !unitlist usvol cup;3|4 cup;2|3 cup;1|2 cup;1|3 cup;1|4 cup;\
2342 tbsp;tsp;1|2 tsp;1|4 tsp;1|8 tsp
2343 Unit list aliases are only for unit lists, so the definition must in‐
2345 clude a ‘;’. Unit list aliases can never be combined with units or
2346 other unit list aliases, so the definition of ‘time’ shown above could
2347 not have been shortened to ‘year;day;hms’.
2348 As usual, be sure to run units --check to ensure that the units listed
2350 in unit list aliases are conformable.
2351
2353 By default, units shows results to eight significant digits. You can
2354 change this with the ‘--exponential’, ‘--digits’, and ‘--output-format’
2355 options. The first sets an exponential format (i.e., scientific nota‐
2356 tion) like that used in the original Unix units program, the second al‐
2357 lows you to specify a different number of significant digits, and the
2358 last allows you to control the output appearance using the format for
2359 the printf() function in the C programming language. If you only want
2360 to change the number of significant digits or specify exponential for‐
2361 mat type, use the ‘--digits’ and ‘--exponential’ options. The
2362 ‘--output-format’ option affords the greatest control of the output ap‐
2363 pearance, but requires at least rudimentary knowledge of the printf()
2364 format syntax. See Invoking Units for descriptions of these options.
2365 Format Specification
2367 The format specification recognized with the ‘--output-format’ option
2368 is a subset of that for printf(). The format specification has the
2369 form %[flags][width][.precision]type; it must begin with ‘%’, and must
2370 end with a floating-point type specifier: ‘g’ or ‘G’ to specify the
2371 number of significant digits, ‘e’ or ‘E’ for scientific notation, and
2372 ‘f’ for fixed-point decimal. The ISO C99 standard added the ‘F’ type
2373 for fixed-point decimal and the ‘a’ and ‘A’ types for hexadecimal
2374 floating point; these types are allowed with compilers that support
2375 them. Type length modifiers (e.g., ‘L’ to indicate a long double) are
2376 inapplicable and are not allowed.
2377 The default format for units is ‘%.8g’; for greater precision, you
2379 could specify ‘-o %.15g’. The ‘g’ and ‘G’ format types use exponential
2380 format whenever the exponent would be less than -4, so the value
2381 0.000013 displays as ‘1.3e-005’. These types also use exponential no‐
2382 tation when the exponent is greater than or equal to the precision, so
2383 with the default format, the value 5e7 displays as ‘50000000’ and the
2384 value 5e8 displays as ‘5e+008’. If you prefer fixed-point display, you
2385 might specify ‘-o %.8f’; however, small numbers will display very few
2386 significant digits, and values less than 0.5e-8 will show nothing but
2387 zeros.
2388 The format specification may include one or more optional flags: ‘+’,
2390 ‘ ’ (space), ‘#’, ‘-’, or ‘0’ (the digit zero). The digit-grouping
2391 flag ‘'’ is allowed with compilers that support it. Flags are followed
2392 by an optional value for the minimum field width, and an optional pre‐
2393 cision specification that begins with a period (e.g., ‘.6’). The field
2394 width includes the digits, decimal point, the exponent, thousands sepa‐
2395 rators (with the digit-grouping flag), and the sign if any of these are
2396 shown.
2397 Flags
2399 The ‘+’ flag causes the output to have a sign (‘+’ or ‘-’). The space
2400 flag ‘ ’ is similar to the ‘+’ flag, except that when the value is pos‐
2401 itive, it is prefixed with a space rather than a plus sign; this flag
2402 is ignored if the ‘+’ flag is also given. The ‘+’ or ‘ ’ flag could be
2403 useful if conversions might include positive and negative results, and
2404 you wanted to align the decimal points in exponential notation. The
2405 ‘#’ flag causes the output value to contain a decimal point in all
2406 cases; by default, the output contains a decimal point only if there
2407 are digits (which can be trailing zeros) to the right of the point.
2408 With the ‘g’ or ‘G’ types, the ‘#’ flag also prevents the suppression
2409 of trailing zeros. The digit-grouping flag ‘'’ shows a thousands sepa‐
2410 rator in digits to the left of the decimal point. This can be useful
2411 when displaying large numbers in fixed-point decimal; for example, with
2412 the format ‘%f’,
2413 You have: mile
2415 You want: microfurlong
2416 * 8000000.000000
2417 / 0.000000
2418 the magnitude of the first result may not be immediately obvious with‐
2420 out counting the digits to the left of the decimal point. If the thou‐
2421 sands separator is the comma (‘,’), the output with the format ‘%'f’
2422 might be
2423 You have: mile
2425 You want: microfurlong
2426 * 8,000,000.000000
2427 / 0.000000
2428 making the magnitude readily apparent. Unfortunately, few compilers
2430 support the digit-grouping flag.
2431 With the ‘-’ flag, the output value is left aligned within the speci‐
2433 fied field width. If a field width greater than needed to show the
2434 output value is specified, the ‘0’ (zero) flag causes the output value
2435 to be left padded with zeros until the specified field width is
2436 reached; for example, with the format ‘%011.6f’,
2437 You have: troypound
2439 You want: grain
2440 * 5760.000000
2441 / 0000.000174
2442 The ‘0’ flag has no effect if the ‘-’ (left align) flag is given.
2444 Field Width
2446 By default, the output value is left aligned and shown with the minimum
2447 width necessary for the specified (or default) precision. If a field
2448 width greater than this is specified, the value shown is right aligned,
2449 and padded on the left with enough spaces to provide the specified
2450 field width. A width specification is typically used with fixed-point
2451 decimal to have columns of numbers align at the decimal point; this ar‐
2452 guably is less useful with units than with long columnar output, but it
2453 may nonetheless assist in quickly assessing the relative magnitudes of
2454 results. For example, with the format ‘%12.6f’,
2455 You have: km
2457 You want: in
2458 * 39370.078740
2459 / 0.000025
2460 You have: km
2461 You want: rod
2462 * 198.838782
2463 / 0.005029
2464 You have: km
2465 You want: furlong
2466 * 4.970970
2467 / 0.201168
2468 Precision
2470 The meaning of “precision” depends on the format type. With ‘g’ or
2471 ‘G’, it specifies the number of significant digits (like the ‘--digits’
2472 option); with ‘e’, ‘E’, ‘f’, or ‘F’, it specifies the maximum number of
2473 digits to be shown after the decimal point.
2474 With the ‘g’ and ‘G’ format types, trailing zeros are suppressed, so
2476 the results may sometimes have fewer digits than the specified preci‐
2477 sion (as indicated above, the ‘#’ flag causes trailing zeros to be dis‐
2478 played).
2479 The default precision is 6, so ‘%g’ is equivalent to ‘%.6g’, and would
2481 show the output to six significant digits. Similarly, ‘%e’ or ‘%f’
2482 would show the output with six digits after the decimal point.
2483 The C printf() function allows a precision of arbitrary size, whether
2485 or not all of the digits are meaningful. With most compilers, the max‐
2486 imum internal precision with units is 15 decimal digits (or 13 hexadec‐
2487 imal digits). With the ‘--digits’ option, you are limited to the maxi‐
2488 mum internal precision; with the ‘--output-format’ option, you may
2489 specify a precision greater than this, but it may not be meaningful.
2490 In some cases, specifying excess precision can result in rounding arti‐
2491 facts. For example, a pound is exactly 7000 grains, but with the for‐
2492 mat ‘%.18g’, the output might be
2493 You have: pound
2495 You want: grain
2496 * 6999.9999999999991
2497 / 0.00014285714285714287
2498 With the format ‘%.25g’ you might get the following:
2500 You have: 1/3
2502 You want:
2503 Definition: 0.333333333333333314829616256247
2504 In this case the displayed value includes a series of digits that rep‐
2506 resent the underlying binary floating-point approximation to 1/3 but
2507 are not meaningful for the desired computation. In general, the result
2508 with excess precision is system dependent. The precision affects only
2509 the display of numbers; if a result relies on physical constants that
2510 are not known to the specified precision, the number of physically
2511 meaningful digits may be less than the number of digits shown.
2512 See the documentation for printf() for more detailed descriptions of
2514 the format specification.
2515 The ‘--output-format’ option is incompatible with the ‘--exponential’
2517 or ‘--digits’ options; if the former is given in combination with ei‐
2518 ther of the latter, the format is controlled by the last option given.
2519
2521 Some units have different values in different locations. The localiza‐
2522 tion feature accommodates this by allowing a units data file to specify
2523 definitions that depend on the user’s locale.
2524 Locale
2526 A locale is a subset of a user’s environment that indicates the user’s
2527 language and country, and some attendant preferences, such as the for‐
2528 matting of dates. The units program attempts to determine the locale
2529 from the POSIX setlocale function; if this cannot be done, units exam‐
2530 ines the environment variables LC_CTYPE and LANG. On POSIX systems, a
2531 locale is of the form language_country, where language is the two-char‐
2532 acter code from ISO 639-1 and country is the two-character code from
2533 ISO 3166-1; language is lower case and country is upper case. For exam‐
2534 ple, the POSIX locale for the United Kingdom is en_GB.
2535 On systems running Microsoft Windows, the value returned by setlocale()
2537 is different from that on POSIX systems; units attempts to map the Win‐
2538 dows value to a POSIX value by means of a table in the file
2539 ‘locale_map.txt’ in the same directory as the other data files. The
2540 file includes entries for many combinations of language and country,
2541 and can be extended to include other combinations. The
2542 ‘locale_map.txt’ file comprises two tab-separated columns; each entry
2543 is of the form
2544 Windows-locale POSIX-locale
2546 where POSIX-locale is as described above, and Windows-locale typically
2548 spells out both the language and country. For example, the entry for
2549 the United States is
2550 English_United States en_US
2552 You can force units to run in a desired locale by using the ‘-l’ op‐
2554 tion.
2555 In order to create unit definitions for a particular locale you begin a
2557 block of definitions in a unit datafile with ‘!locale’ followed by a
2558 locale name. The ‘!’ must be the first character on the line. The
2559 units program reads the following definitions only if the current lo‐
2560 cale matches. You end the block of localized units with ‘!endlocale’.
2561 Here is an example, which defines the British gallon.
2562 !locale en_GB
2564 gallon 4.54609 liter
2565 !endlocale
2566 Additional Localization
2568 Sometimes the locale isn’t sufficient to determine unit preferences.
2569 There could be regional preferences, or a company could have specific
2570 preferences. Though probably uncommon, such differences could arise
2571 with the choice of English customary units outside of English-speaking
2572 countries. To address this, units allows specifying definitions that
2573 depend on environment variable settings. The environment variables can
2574 be controlled based on the current locale, or the user can set them to
2575 force a particular group of definitions.
2576 A conditional block of definitions in a units data file begins with ei‐
2578 ther ‘!var’ or ‘!varnot’ following by an environment variable name and
2579 then a space separated list of values. The leading ‘!’ must appear in
2580 the first column of a units data file, and the conditional block is
2581 terminated by ‘!endvar’. Definitions in blocks beginning with ‘!var’
2582 are executed only if the environment variable is exactly equal to one
2583 of the listed values. Definitions in blocks beginning with ‘!varnot’
2584 are executed only if the environment variable does not equal any of the
2585 list values.
2586 The inch has long been a customary measure of length in many places.
2588 The word comes from the Latin uncia meaning “one twelfth,” referring to
2589 its relationship with the foot. By the 20th century, the inch was of‐
2590 ficially defined in English-speaking countries relative to the yard,
2591 but until 1959, the yard differed slightly among those countries. In
2592 France the customary inch, which was displaced in 1799 by the meter,
2593 had a different length based on a french foot. These customary defini‐
2594 tions could be accommodated as follows:
2595 !var INCH_UNIT usa
2597 yard 3600|3937 m
2598 !endvar
2599 !var INCH_UNIT canada
2600 yard 0.9144 meter
2601 !endvar
2602 !var INCH_UNIT uk
2603 yard 0.91439841 meter
2604 !endvar
2605 !var INCH_UNIT canada uk usa
2606 foot 1|3 yard
2607 inch 1|12 foot
2608 !endvar
2609 !var INCH_UNIT france
2610 foot 144|443.296 m
2611 inch 1|12 foot
2612 line 1|12 inch
2613 !endvar
2614 !varnot INCH_UNIT usa uk france canada
2615 !message Unknown value for INCH_UNIT
2616 !endvar
2617 When units reads the above definitions it will check the environment
2619 variable INCH_UNIT and load only the definitions for the appropriate
2620 section. If INCH_UNIT is unset or is not set to one of the four values
2621 listed, then units will run the last block. In this case that block
2622 uses the ‘!message’ command to display a warning message. Alterna‐
2623 tively that block could set default values.
2624 In order to create default values that are overridden by user settings
2626 the data file can use the ‘!set’ command, which sets an environment
2627 variable only if it is not already set; these settings are only for
2628 the current units invocation and do not persist. So if the example
2629 above were preceded by ‘!set INCH_UNIT france’, then this would make
2630 ‘france’ the default value for INCH_UNIT. If the user had set the
2631 variable in the environment before invoking units, then units would use
2632 the user’s value.
2633 To link these settings to the user’s locale you combine the ‘!set’ com‐
2635 mand with the ‘!locale’ command. If you wanted to combine the above
2636 example with suitable locales you could do by preceding the above defi‐
2637 nition with the following:
2638 !locale en_US
2640 !set INCH_UNIT usa
2641 !endlocale
2642 !locale en_GB
2643 !set INCH_UNIT uk
2644 !endlocale
2645 !locale en_CA
2646 !set INCH_UNIT canada
2647 !endlocale
2648 !locale fr_FR
2649 !set INCH_UNIT france
2650 !endlocale
2651 !set INCH_UNIT france
2652 These definitions set the overall default for INCH_UNIT to ‘france’ and
2654 set default values for four locales appropriately. The overall default
2655 setting comes last so that it only applies when INCH_UNIT was not set
2656 by one of the other commands or by the user.
2657 If the variable given after ‘!var’ or ‘!varnot’ is undefined, then
2659 units prints an error message and ignores the definitions that follow.
2660 Use ‘!set’ to create defaults to prevent this situation from arising.
2661 The ‘-c’ option only checks the definitions that are active for the
2662 current environment and locale, so when adding new definitions take
2663 care to check that all cases give rise to a well defined set of defini‐
2664 tions.
2665
2667 The units program uses the following environment variables:
2668 HOME Specifies the location of your home directory; it is used by
2670 units to find a personal units data file ‘.units’. On systems
2671 running Microsoft Windows, the file is ‘unitdef.units’, and if
2672 HOME does not exist, units tries to determine your home direc‐
2673 tory from the HOMEDRIVE and HOMEPATH environment variables; if
2674 these variables do not exist, units finally tries
2675 USERPROFILE—typically ‘C:\Users\username’ (Windows Vista and
2676 Windows 7) or ‘C:\Documents and Settings\username’ (Windows XP).
2677 LC_CTYPE, LANG
2679 Checked to determine the locale if units cannot obtain it from
2680 the operating system. Sections of the standard units data file
2681 are specific to certain locales.
2682 MYUNITSFILE
2684 Specifies your personal units data file. If this variable ex‐
2685 ists, units uses its value rather than searching your home di‐
2686 rectory for ‘.units’. The personal units file will not be
2687 loaded if any data files are given using the ‘-f’ option.
2688 PAGER Specifies the pager to use for help and for displaying the con‐
2690 formable units. The help function browses the units database
2691 and calls the pager using the ‘+n’n syntax for specifying a line
2692 number. The default pager is more; PAGER can be used to specify
2693 alternatives such as less, pg, emacs, or vi.
2694 UNITS_ENGLISH
2696 Set to either ‘US’ or ‘GB’ to choose United States or British
2697 volume definitions, overriding the default from your locale.
2698 UNITSFILE
2700 Specifies the units data file to use (instead of the default).
2701 You can only specify a single units data file using this envi‐
2702 ronment variable. If units data files are given using the ‘-f’
2703 option, the file specified by UNITSFILE will be not be loaded
2704 unless the ‘-f’ option is given with the empty string (‐
2705 ‘units -f ""’).
2706 UNITSLOCALEMAP
2708 Windows only; this variable has no effect on Unix-like systems.
2709 Specifies the units locale map file to use (instead of the de‐
2710 fault). This variable seldom needs to be set, but you can use
2711 it to ensure that the locale map file will be found if you spec‐
2712 ify a location for the units data file using either the ‘-f’ op‐
2713 tion or the UNITSFILE environment variable, and that location
2714 does not also contain the locale map file.
2715 UNITS_SYSTEM
2717 This environment variable is used in the standard data file to
2718 select CGS measurement systems. Currently supported systems are
2719 ‘esu’, ‘emu’, ‘gauss[ian]’, and ‘si’. The default is ‘si’.
2720
2722 The units program uses two default data files: ‘definitions.units’ and
2723 ‘currency.units’. The program can also use an optional personal units
2724 data file ‘.units’ (‘unitdef.units’ under Windows) located in the
2725 user’s home directory. The personal units data file is described in
2726 more detail in Units Data Files.
2727 On Unix-like systems, the data files are typically located in
2729 ‘/usr/share/units’ if units is provided with the operating system, or
2730 in ‘/usr/local/share/units’ if units is compiled from the source dis‐
2731 tribution. Note that the currency file ‘currency.units’ is a symbolic
2732 link to another location.
2733 On systems running Microsoft Windows, the files may be in the same lo‐
2735 cations if Unix-like commands are available, a Unix-like file structure
2736 is present (e.g., ‘C:/usr/local’), and units is compiled from the
2737 source distribution. If Unix-like commands are not available, a more
2738 common location is ‘C:\Program Files (x86)\GNU\units’ (for 64-bit Win‐
2739 dows installations) or ‘C:\Program Files\GNU\units’ (for 32-bit instal‐
2740 lations).
2741 If units is obtained from the GNU Win32 Project
2743 (http://gnuwin32.sourceforge.net/), the files are commonly in
2744 ‘C:\Program Files\GnuWin32\share\units’.
2745 If the default units data file is not an absolute pathname, units will
2747 look for the file in the directory that contains the units program; if
2748 the file is not found there, units will look in a directory
2749 ../share/units relative to the directory with the units program.
2750 You can determine the location of the files by running units --version.
2752 Running units --info will give you additional information about the
2753 files, how units will attempt to find them, and the status of the re‐
2754 lated environment variables.
2755
2757 The standard units data file is in Unicode, using UTF-8 encoding. Most
2758 definitions use only ASCII characters (i.e., code points U+0000 through
2759 U+007F); definitions using non-ASCII characters appear in blocks begin‐
2760 ning with ‘!utf8’ and ending with ‘!endutf8’.
2761 The non-ASCII definitions are loaded only if the platform and the lo‐
2763 cale support UTF-8. Platform support is determined when units is com‐
2764 piled; the locale is checked at every invocation of units. To see if
2765 your version of units includes Unicode support, invoke the program with
2766 the ‘--version’ option.
2767 When Unicode support is available, units checks every line within UTF-8
2769 blocks in all of the units data files for invalid or non-printing UTF-8
2770 sequences; if such sequences occur, units ignores the entire line. In
2771 addition to checking validity, units determines the display width of
2772 non-ASCII characters to ensure proper positioning of the pointer in
2773 some error messages and to align columns for the ‘search’ and ‘?’ com‐
2774 mands.
2775 As of early 2019, Microsoft Windows provides limited support for UTF-8
2777 in console applications, and accordingly, units does not support Uni‐
2778 code on Windows. The UTF-16 and UTF-32 encodings are not supported on
2779 any platforms.
2780 If Unicode support is available and definitions that contain non-ASCII
2782 UTF-8 characters are added to a units data file, those definitions
2783 should be enclosed within ‘!utf8’ ... ‘!endutf8’ to ensure that they
2784 are only loaded when Unicode support is available. As usual, the ‘!’
2785 must appear as the first character on the line. As discussed in Units
2786 Data Files, it’s usually best to put such definitions in supplemental
2787 data files linked by an ‘!include’ command or in a personal units data
2788 file.
2789 When Unicode support is not available, units makes no assumptions about
2791 character encoding, except that characters in the range 00–7F hexadeci‐
2792 mal correspond to ASCII encoding. Non-ASCII characters are simply se‐
2793 quences of bytes, and have no special meanings; for definitions in sup‐
2794 plementary units data files, you can use any encoding consistent with
2795 this assumption. For example, if you wish to use non-ASCII characters
2796 in definitions when running units under Windows, you can use a charac‐
2797 ter set such as Windows “ANSI” (code page 1252 in the US and Western
2798 Europe); if this is done, the console code page must be set to the same
2799 encoding for the characters to display properly. You can even use
2800 UTF-8, though some messages may be improperly aligned, and units will
2801 not detect invalid UTF-8 sequences. If you use UTF-8 encoding when
2802 Unicode support is not available, you should place any definitions with
2803 non-ASCII characters outside ‘!utf8’
2804 Typeset material other than code examples usually uses the Unicode mi‐
2806 nus (U+2212) rather than the ASCII hyphen-minus operator (U+002D) used
2807 in units; the figure dash (U+2012) and en dash (U+2013) are also occa‐
2808 sionally used. To allow such material to be copied and pasted for in‐
2809 teractive use or in units data files, units converts these characters
2810 to U+002D before further processing. Because of this, none of these
2811 characters can appear in unit names.
2812
2814 If the readline package has been compiled in, then when units is used
2815 interactively, numerous command line editing features are available.
2816 To check if your version of units includes readline, invoke the program
2817 with the ‘--version’ option.
2818 For complete information about readline, consult the documentation for
2820 the readline package. Without any configuration, units will allow
2821 editing in the style of emacs. Of particular use with units are the
2822 completion commands.
2823 If you type a few characters and then hit ESC followed by ?, then units
2825 will display a list of all the units that start with the characters
2826 typed. For example, if you type metr and then request completion, you
2827 will see something like this:
2828 You have: metr
2830 metre metriccup metrichorsepower metrictenth
2831 metretes metricfifth metricounce metricton
2832 metriccarat metricgrain metricquart metricyarncount
2833 You have: metr
2834 If there is a unique way to complete a unit name, you can hit the TAB
2836 key and units will provide the rest of the unit name. If units beeps,
2837 it means that there is no unique completion. Pressing the TAB key a
2838 second time will print the list of all completions.
2839 The readline library also keeps a history of the values you enter. You
2841 can move through this history using the up and down arrows. The his‐
2842 tory is saved to the file ‘.units_history’ in your home directory so
2843 that it will persist across multiple units invocations. If you wish to
2844 keep work for a certain project separate you can change the history
2845 filename using the ‘--history’ option. You could, for example, make an
2846 alias for units to units --history .units_history so that units would
2847 save separate history in the current directory. The length of each
2848 history file is limited to 5000 lines. Note also that if you run sev‐
2849 eral concurrent copies of units each one will save its new history to
2850 the history file upon exit.
2851
2853 The units program database includes currency exchange rates and prices
2854 for some precious metals. Of course, these values change over time,
2855 sometimes very rapidly, and units cannot provide real-time values. To
2856 update the exchange rates, run units_cur, which rewrites the file con‐
2857 taining the currency rates, typically ‘/var/lib/units/currency.units’
2858 or ‘/usr/local/com/units/currency.units’ on a Unix-like system or
2859 ‘C:Program Files (x86)\:GNU\:units\:definitions.units’ on a Windows
2860 system.
2861 This program requires Python (https://www.python.org); either version 2
2863 or 3 will work. The program must be run with suitable permissions to
2864 write the file. To keep the rates updated automatically, run it using
2865 a cron job on a Unix-like system, or a similar scheduling program on a
2866 different system.
2867 Reliable free sources of currency exchange rates have been annoyingly
2869 ephemeral. The program currently supports several sources:
2870 • FloatRates (https://www/floatrates.com). The US dollar (‘USD’) is
2872 the default base currency. You can change the base currency with
2873 the ‘-b’ option described below. Allowable base currencies are
2874 listed on the FloatRates website. Exchange rates update daily.
2875 • The European Central Bank (https://www.ecb.europa.eu). The base
2877 currency is always the euro (‘EUR’). Exchange rates update daily.
2878 This source offers a more limited list of currencies than the oth‐
2879 ers.
2880 • Fixer (https://fixer.io). Registration for a free API key is re‐
2882 quired. With a free API key, base currency is the euro; exchange
2883 rates are updated hourly, the service has a limit of 1,000 API
2884 calls per month, and SSL encryption (https protocol) is not avail‐
2885 able. Most of these restrictions are eliminated or reduced with
2886 paid plans.
2887 • open exchange rates (https://openexchangerates.org). Registration
2889 for a free API key is required. With a free API key, the base cur‐
2890 rency is the US dollar; exchange rates are updated hourly, and
2891 there is a limit of 1,000 API calls per month. Most of these re‐
2892 strictions are eliminated or reduced with paid plans.
2893 ExchangeRate-API.com (https://www.exchangerate-api.com). Allows open
2895 access without an API key, with unlimited API requests. Rates update
2896 once a day, and you can choose your base currency. You can optionally
2897 sign up for an API key to access paid benefits such as faster data up‐
2898 date rates.
2899 The default source is FloatRates; you can select a different one using
2901 ‘-s’ option described below.
2902 Precious metals pricing is obtained from Packetizer (www.packe‐
2904 tizer.com). This site updates once per day.
2905 You invoke units_cur like this:
2907 units_cur [options] [outfile]
2909 By default, the output is written to the default currency file de‐
2911 scribed above; this is usually what you want, because this is where
2912 units looks for the file. If you wish, you can specify a different
2913 filename on the command line and units_cur will write the data to that
2914 file. If you give ‘-’ for the file it will write to standard output.
2915 The following options are available:
2917 -h, --help
2919 Print a summary of the options for units_cur.
2920 -V, --version
2922 Print the units_cur version number.
2923 -v, --verbose
2925 Give slightly more verbose output when attempting to update cur‐
2926 rency exchange rates.
2927 -s source, --source source
2929 Specify the source for currency exchange rates; currently sup‐
2930 ported values are ‘floatrates’ (for FloatRates), ‘eubank’ (for
2931 the European Central Bank), ‘fixer’ (for Fixer), and
2932 ‘openexchangerates’ (for open exchange rates); the last two re‐
2933 quire an API key to be given with the ‘-k’ option.
2934 -b base, --base base
2936 Set the base currency (when allowed by the site providing the
2937 data). base should be a 3-letter ISO currency code, e.g.,
2938 ‘USD’. The specified currency will be the primitive currency
2939 unit used by units. You may find it convenient to specify your
2940 local currency. Conversions may be more accurate and you will
2941 be able to convert to your currency by simply hitting Enter at
2942 the ‘You want:’ prompt. This option is ignored if the source
2943 does not allow specifying the base currency. (Currently only
2944 floatrates supports this option.)
2945 -k key, --key key
2947 Set the API key to key for sources that require it.
2948
2950 unit definition
2951 Define a regular unit.
2952 prefix- definition
2954 Define a prefix.
2955 funcname(var) noerror units=[in-units,out-units] domain=[x1,x2]
2957 range=[y1,y2] definition(var) ; inverse(funcname)
2958 Define a nonlinear unit or unit function. The four optional
2959 keywords noerror, units=, range= and domain= can appear in any
2960 order. The definition of the inverse is optional.
2961 tabname[out-units] noerror pair-list
2963 Define a piecewise linear unit. The pair list gives the points
2964 on the table listed in ascending order. The noerror keyword is
2965 optional.
2966 !endlocale
2968 End a block of definitions beginning with ‘!locale’
2969 !endutf8
2971 End a block of definitions begun with ‘!utf8’
2972 !endvar
2974 End a block of definitions begun with ‘!var’ or ‘!varnot’
2975 !include file
2977 Include the specified file.
2978 !locale value
2980 Load the following definitions only of the locale is set to
2981 value.
2982 !message text
2984 Display text when the database is read unless the quiet option
2985 (‘-q’) is enabled. If you omit text, then units will display a
2986 blank line. Messages will also appear in the log file.
2987 !prompt text
2989 Prefix the ‘You have:’ prompt with the specified text. If you
2990 omit text, then any existing prefix is canceled.
2991 !set variable value
2993 Sets the environment variable, variable, to the specified value
2994 only if it is not already set.
2995 !unitlist alias definition
2997 Define a unit list alias.
2998 !utf8 Load the following definitions only if units is running with
3000 UTF-8 enabled.
3001 !var envar value-list
3003 Load the block of definitions that follows only if the environ‐
3004 ment variable envar is set to one of the values listed in the
3005 space-separated value list. If envar is not set, units prints
3006 an error message and ignores the block of definitions.
3007 !varnot envar value-list
3009 Load the block of definitions that follows only if the environ‐
3010 ment variable envar is set to value that is not listed in the
3011 space-separated value list. If envar is not set, units prints
3012 an error message and ignores the block of definitions.
3013
3015 /usr/share/units/definitions.units — the standard units data file
3016
3018 units was written by Adrian Mariano
3019 25 August 2022 UNITS(1)