1UNITS(1) General Commands Manual UNITS(1)
2
6 units — unit conversion and calculation program
7
9 ‘units’ [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 Basic operation is simple: you enter the units that you want to convert
21 from and the units that you want to convert to. You can use the pro‐
22 gram interactively with prompts, or you can use it from the command
23 line.
24 Beyond simple unit conversions, ‘units’ can be used as a general-pur‐
26 pose scientific calculator that keeps track of units in its calcula‐
27 tions. You can form arbitrary complex mathematical expressions of
28 dimensions including sums, products, quotients, powers, and even roots
29 of dimensions. Thus you can ensure accuracy and dimensional consis‐
30 tency when working with long expressions that involve many different
31 units that may combine in complex ways; for an illustration, see Com‐
32 plicated Unit Expressions.
33 The units are defined in an external data file. You can use the exten‐
35 sive data file that comes with this program, or you can provide your
36 own data file to suit your needs. You can also use your own data file
37 to supplement the standard data file.
38 You can change the default behavior of ‘units’ with various options
40 given on the command line. See Invoking Units for a description of the
41 available options.
42
44 To invoke ‘units’ for interactive use, type ‘units’ at your shell
45 prompt. The program will print something like this:
46 Currency exchange rates from www.timegenie.com on 2014-03-05
48 2860 units, 109 prefixes, 85 nonlinear units
49 You have:
51 At the ‘You have:’ prompt, type the quantity and units that you are
53 converting from. For example, if you want to convert ten meters to
54 feet, type ‘10 meters’. Next, ‘units’ will print ‘You want:’. You
55 should type the units you want to convert to. To convert to feet, you
56 would type ‘feet’. If the ‘readline’ library was compiled in, then tab
57 will complete unit names. See Readline Support for more information
58 about ‘readline’. To quit the program type ‘quit’ or ‘exit’ at either
59 prompt.
60 The result will be displayed in two ways. The first line of output,
62 which is marked with a ‘*’ to indicate multiplication, gives the result
63 of the conversion you have asked for. The second line of output, which
64 is marked with a ‘/’ to indicate division, gives the inverse of the
65 conversion factor. If you convert 10 meters to feet, ‘units’ will
66 print
67 * 32.808399
69 / 0.03048
70 which tells you that 10 meters equals about 32.8 feet. The second num‐
72 ber gives the conversion in the opposite direction. In this case, it
73 tells you that 1 foot is equal to about 0.03 dekameters since the
74 dekameter is 10 meters. It also tells you that 1/32.8 is about 0.03.
75 The ‘units’ program prints the inverse because sometimes it is a more
77 convenient number. In the example above, for example, the inverse
78 value is an exact conversion: a foot is exactly 0.03048 dekameters.
79 But the number given the other direction is inexact.
80 If you convert grains to pounds, you will see the following:
82 You have: grains
84 You want: pounds
85 * 0.00014285714
86 / 7000
87 From the second line of the output you can immediately see that a
89 grain is equal to a seven thousandth of a pound. This is not so obvi‐
90 ous from the first line of the output. If you find the output format
91 confusing, try using the ‘--verbose’ option:
92 You have: grain
94 You want: aeginamina
95 grain = 0.00010416667 aeginamina
96 grain = (1 / 9600) aeginamina
97 If you request a conversion between units that measure reciprocal
99 dimensions, then ‘units’ will display the conversion results with an
100 extra note indicating that reciprocal conversion has been done:
101 You have: 6 ohms
103 You want: siemens
104 reciprocal conversion
105 * 0.16666667
106 / 6
107 Reciprocal conversion can be suppressed by using the ‘--strict’ option.
109 As usual, use the ‘--verbose’ option to get more comprehensible output:
110 You have: tex
112 You want: typp
113 reciprocal conversion
114 1 / tex = 496.05465 typp
115 1 / tex = (1 / 0.0020159069) typp
116 You have: 20 mph
118 You want: sec/mile
119 reciprocal conversion
120 1 / 20 mph = 180 sec/mile
121 1 / 20 mph = (1 / 0.0055555556) sec/mile
122 If you enter incompatible unit types, the ‘units’ program will print a
124 message indicating that the units are not conformable and it will dis‐
125 play the reduced form for each unit:
126 You have: ergs/hour
128 You want: fathoms kg^2 / day
129 conformability error
130 2.7777778e-11 kg m^2 / sec^3
131 2.1166667e-05 kg^2 m / sec
132 If you only want to find the reduced form or definition of a unit, sim‐
134 ply press Enter at the ‘You want:’ prompt. Here is an example:
135 You have: jansky
137 You want:
138 Definition: fluxunit = 1e-26 W/m^2 Hz = 1e-26 kg / s^2
139 The output from ‘units’ indicates that the jansky is defined to be
141 equal to a fluxunit which in turn is defined to be a certain combina‐
142 tion of watts, meters, and hertz. The fully reduced (and in this case
143 somewhat more cryptic) form appears on the far right.
144 Some named units are treated as dimensionless in some situations.
146 These units include the radian and steradian. These units will be
147 treated as equal to 1 in units conversions. Power is equal to torque
148 times angular velocity. This conversion can only be performed if the
149 radian is dimensionless.
150 You have: (14 ft lbf) (12 radians/sec)
152 You want: watts
153 * 227.77742
154 / 0.0043902509
155 It is also possible to compute roots and other non-integer powers of
157 dimensionless units; this allows computations such as the altitude of
158 geosynchronous orbit:
159 You have: cuberoot(G earthmass / (circle/siderealday)^2) - earthradius
161 You want: miles
162 * 22243.267
163 / 4.4957425e-05
164 Named dimensionless units are not treated as dimensionless in other
166 contexts. They cannot be used as exponents so for example,
167 ‘meter^radian’ is forbidden.
168 If you want a list of options you can type ‘?’ at the ‘You want:’
170 prompt. The program will display a list of named units that are con‐
171 formable with the unit that you entered at the ‘You have:’ prompt
172 above. Conformable unit combinations will not appear on this list.
173 Typing ‘help’ at either prompt displays a short help message. You can
175 also type ‘help’ followed by a unit name. This will invoke a pager on
176 the units data base at the point where that unit is defined. You can
177 read the definition and comments that may give more details or histori‐
178 cal information about the unit. (You can generally quit out of the
179 page by pressing ‘q’.)
180 Typing ‘search’ text will display a list of all of the units whose
182 names contain text as a substring along with their definitions. This
183 may help in the case where you aren’t sure of the right unit name.
184
186 The ‘units’ program can perform units conversions non-interactively
187 from the command line. To do this, type the command, type the original
188 unit expression, and type the new units you want. If a units expres‐
189 sion contains non-alphanumeric characters, you may need to protect it
190 from interpretation by the shell using single or double quote charac‐
191 ters.
192 If you type
194 units "2 liters" quarts
196 then ‘units’ will print
198 * 2.1133764
200 / 0.47317647
201 and then exit. The output tells you that 2 liters is about 2.1 quarts,
203 or alternatively that a quart is about 0.47 times 2 liters.
204 ‘units’ does not require a space between a numerical value and the
206 unit, so the previous example can be given as
207 units 2liters quarts
209 to avoid having to quote the first argument.
211 If the conversion is successful, then ‘units’ will return success
213 (zero) to the calling environment. If you enter non-conformable
214 units, then ‘units’ will print a message giving the reduced form of
215 each unit and it will return failure (nonzero) to the calling environ‐
216 ment.
217 When you invoke ‘units’ with only one argument, it will print the defi‐
219 nition of the specified unit. It will return failure if the unit is
220 not defined and success if the unit is defined.
221
223 The conversion information is read from a units data file that is
224 called ‘definitions.units’ and is usually located in the
225 ‘/usr/share/units’ directory. If you invoke ‘units’ with the ‘-V’
226 option, it will print the location of this file. The default file
227 includes definitions for all familiar units, abbreviations and metric
228 prefixes. It also includes many obscure or archaic units. Many common
229 spelled-out numbers (e.g., ‘seventeen’) are recognized.
230 Many constants of nature are defined, including these:
232 pi ratio of circumference to diameter
234 c speed of light
235 e charge on an electron
236 force acceleration of gravity
237 mole Avogadro’s number
238 water pressure per unit height of water
239 Hg pressure per unit height of mercury
240 au astronomical unit
241 k Boltzman’s constant
242 mu0 permeability of vacuum
243 epsilon0 permittivity of vacuum
244 G Gravitational constant
245 mach speed of sound
246 The standard data file includes atomic masses for all of the elements
248 and numerous other constants. Also included are the densities of vari‐
249 ous ingredients used in baking so that ‘2 cups flour_sifted’ can be
250 converted to ‘grams’. This is not an exhaustive list. Consult the
251 units data file to see the complete list, or to see the definitions
252 that are used.
253 The ‘pound’ is a unit of mass. To get force, multiply by the force
255 conversion unit ‘force’ or use the shorthand ‘lbf’. (Note that ‘g’ is
256 already taken as the standard abbreviation for the gram.) The unit
257 ‘ounce’ is also a unit of mass. The fluid ounce is ‘fluidounce’ or
258 ‘floz’. When British capacity units differ from their US counterparts,
259 such as the British Imperial gallon, the unit is defined both ways with
260 ‘br’ and ‘us’ prefixes. Your locale settings will determine the value
261 of the unprefixed unit. Currency is prefixed with its country name:
262 ‘belgiumfranc’, ‘britainpound’.
263 When searching for a unit, if the specified string does not appear
265 exactly as a unit name, then the ‘units’ program will try to remove a
266 trailing ‘s’, ‘es’. Next units will replace a trailing ‘ies’ with ‘y’.
267 If that fails, ‘units’ will check for a prefix. The database includes
268 all of the standard metric prefixes. Only one prefix is permitted per
269 unit, so ‘micromicrofarad’ will fail. However, prefixes can appear
270 alone with no unit following them, so ‘micro*microfarad’ will work, as
271 will ‘micro microfarad’.
272 To find out which units and prefixes are available, read the standard
274 units data file, which is extensively annotated.
275 English Customary Units
277 English customary units differ in various ways in different regions.
278 In Britain a complex system of volume measurements featured different
279 gallons for different materials such as a wine gallon and ale gallon
280 that different by twenty percent. This complexity was swept away in
281 1824 by a reform that created an entirely new gallon, the British Impe‐
282 rial gallon defined as the volume occupied by ten pounds of water.
283 Meanwhile in the USA the gallon is derived from the 1707 Winchester
284 wine gallon, which is 231 cubic inches. These gallons differ by about
285 twenty percent. By default if ‘units’ runs in the ‘en_GB’ locale you
286 will get the British volume measures. If it runs in the ‘en_US’ locale
287 you will get the US volume measures. In other locales the default val‐
288 ues are the US definitions. If you wish to force different defini‐
289 tions, then set the environment variable ‘UNITS_ENGLISH’ to either ‘US’
290 or ‘GB’ to set the desired definitions independent of the locale.
291 Before 1959, the value of a yard (and other units of measure defined in
293 terms of it) differed slightly among English-speaking countries. In
294 1959, Australia, Canada, New Zealand, the United Kingdom, the United
295 States, and South Africa adopted the Canadian value of 1 yard =
296 0.9144 m (exactly), which was approximately halfway between the values
297 used by the UK and the US; it had the additional advantage of making
298 1 inch = 2.54 cm (exactly). This new standard was termed the Interna‐
299 tional Yard. Australia, Canada, and the UK then defined all customary
300 lengths in terms of the International Yard (Australia did not define
301 the furlong or rod); because many US land surveys were in terms of the
302 pre-1959 units, the US continued to define customary surveyors’ units
303 (furlong, chain, rod, and link) in terms of the previous value for the
304 foot, which was termed the US survey foot. The US defined a US survey
305 mile as 5280 US survey feet, and defined a statute mile as a US survey
306 mile. The US values for these units differ from the international val‐
307 ues by about 2 ppm.
308 The ‘units’ program uses the international values for these units; the
310 US values can be obtained by using either the ‘US’ or the ‘survey’ pre‐
311 fix. In either case, the simple familiar relationships among the units
312 are maintained, e.g., 1 ‘furlong’ = 660 ‘ft’, and 1 ‘USfurlong’ = 660
313 ‘USft’, though the metric equivalents differ slightly between the two
314 cases. The ‘US’ prefix or the ‘survey’ prefix can also be used to
315 obtain the US survey mile and the value of the US yard prior to 1959,
316 e.g., ‘USmile’ or ‘surveymile’ (but not ‘USsurveymile’). To get the US
317 value of the statute mile, use either ‘USstatutemile’ or ‘USmile’.
318 Except for distances that extend over hundreds of miles (such as in the
320 US State Plane Coordinate System), the differences in the miles are
321 usually insignificant:
322 You have: 100 surveymile - 100 mile
324 You want: inch
325 * 12.672025
326 / 0.078913984
327 The pre-1959 UK values for these units can be obtained with the prefix
329 ‘UK’.
330 In the US, the acre is officially defined in terms of the US survey
332 foot, but ‘units’ uses a definition based on the international foot.
333 If you want the official US acre use ‘USacre’ and similarly use
334 ‘USacrefoot’ for the official US version of that unit. The difference
335 between these units is about 4 parts per million.
336
338 Operators
339 You can enter more complicated units by combining units with operations
340 such as multiplication, division, powers, addition, subtraction, and
341 parentheses for grouping. You can use the customary symbols for these
342 operators when ‘units’ is invoked with its default options. Addition‐
343 ally, ‘units’ supports some extensions, including high priority multi‐
344 plication using a space, and a high priority numerical division opera‐
345 tor (‘|’) that can simplify some expressions.
346 You multiply units using a space or an asterisk (‘*’). The next exam‐
348 ple shows both forms:
349 You have: arabicfoot * arabictradepound * force
351 You want: ft lbf
352 * 0.7296
353 / 1.370614
354 You can divide units using the slash (‘/’) or with ‘per’:
356 You have: furlongs per fortnight
358 You want: m/s
359 * 0.00016630986
360 / 6012.8727
361 You can use parentheses for grouping:
363 You have: (1/2) kg / (kg/meter)
365 You want: league
366 * 0.00010356166
367 / 9656.0833
368 White space surrounding operators is optional, so the previous example
370 could have used ‘(1/2)kg/(kg/meter)’. As a consequence, however,
371 hyphenated spelled-out numbers (e.g., ‘forty-two’) cannot be used;
372 ‘forty-two’ is interpreted as ‘40 - 2’.
373 Multiplication using a space has a higher precedence than division
375 using a slash and is evaluated left to right; in effect, the first ‘/’
376 character marks the beginning of the denominator of a unit expression.
377 This makes it simple to enter a quotient with several terms in the
378 denominator: ‘J / mol K’. The ‘*’ and ‘/’ operators have the same
379 precedence, and are evaluated left to right; if you multiply with ‘*’,
380 you must group the terms in the denominator with parentheses:
381 ‘J / (mol * K)’.
382 The higher precedence of the space operator may not always be advanta‐
384 geous. For example, ‘m/s s/day’ is equivalent to ‘m / s s day’ and has
385 dimensions of length per time cubed. Similarly, ‘1/2 meter’ refers to
386 a unit of reciprocal length equivalent to 0.5/meter, perhaps not what
387 you would intend if you entered that expression. The get a half meter
388 you would need to use parentheses: ‘(1/2) meter’. The ‘*’ operator is
389 convenient for multiplying a sequence of quotients. For example,
390 ‘m/s * s/day’ is equivalent to ‘m/day’. Similarly, you could write
391 ‘1/2 * meter’ to get half a meter.
392 The ‘units’ program supports another option for numerical fractions:
394 you can indicate division of numbers with the vertical bar (‘|’), so if
395 you wanted half a meter you could write ‘1|2 meter’. You cannot use
396 the vertical bar to indicate division of non-numerical units (e.g.,
397 ‘m|s’ results in an error message).
398 Powers of units can be specified using the ‘^’ character, as shown in
400 the following example, or by simple concatenation of a unit and its
401 exponent: ‘cm3’ is equivalent to ‘cm^3’; if the exponent is more than
402 one digit, the ‘^’ is required. You can also use ‘**’ as an exponent
403 operator.
404 You have: cm^3
406 You want: gallons
407 * 0.00026417205
408 / 3785.4118
409 Concatenation only works with a single unit name: if you write
411 ‘(m/s)2’, ‘units’ will treat it as multiplication by 2. When a unit
412 includes a prefix, exponent operators apply to the combination, so
413 ‘centimeter3’ gives cubic centimeters. If you separate the prefix from
414 the unit with any multiplication operator (e.g., ‘centi meter^3’), the
415 prefix is treated as a separate unit, so the exponent applies only to
416 the unit without the prefix. The second example is equivalent to
417 ‘centi * (meter^3)’, and gives a hundredth of a cubic meter, not a
418 cubic centimeter. The ‘units’ program is limited internally to prod‐
419 ucts of 99 units; accordingly, expressions like ‘meter^100’ or
420 ‘joule^34’ (represented internally as ‘kg^34 m^68 / s^68’) will fail.
421 The ‘|’ operator has the highest precedence, so you can write the
423 square root of two thirds as ‘2|3^1|2’. The ‘^’ operator has the sec‐
424 ond highest precedence, and is evaluated right to left, as usual:
425 You have: 5 * 2^3^2
427 You want:
428 Definition: 2560
429 With a dimensionless base unit, any dimensionless exponent is meaning‐
431 ful (e.g., ‘pi^exp(2.371)’). Even though angle is sometimes treated as
432 dimensionless, exponents cannot have dimensions of angle:
433 You have: 2^radian
435 ^
436 Exponent not dimensionless
437 If the base unit is not dimensionless, the exponent must be a rational
439 number p/q, and the dimension of the unit must be a power of q, so
440 ‘gallon^2|3’ works but ‘acre^2|3’ fails. An exponent using the slash
441 (‘/’) operator (e.g., ‘gallon^(2/3)’) is also acceptable; the parenthe‐
442 ses are needed because the precedence of ‘^’ is higher than that of
443 ‘/’. Since ‘units’ cannot represent dimensions with exponents greater
444 than 99, a fully reduced exponent must have q < 100. When raising a
445 non-dimensionless unit to a power, ‘units’ attempts to convert a deci‐
446 mal exponent to a rational number with q < 100. If this is not possi‐
447 ble ‘units’ displays an error message:
448 You have: ft^1.234
450 Base unit not dimensionless; rational exponent required
451 A decimal exponent must match its rational representation to machine
453 precision, so ‘acre^1.5’ works but ‘gallon^0.666’ does not.
454 Sums and Differences of Units
456 You may sometimes want to add values of different units that are out‐
457 side the SI. You may also wish to use ‘units’ as a calculator that
458 keeps track of units. Sums of conformable units are written with the
459 ‘+’ character, and differences with the ‘-’ character.
460 You have: 2 hours + 23 minutes + 32 seconds
462 You want: seconds
463 * 8612
464 / 0.00011611705
465 You have: 12 ft + 3 in
467 You want: cm
468 * 373.38
469 / 0.0026782366
470 You have: 2 btu + 450 ft lbf
472 You want: btu
473 * 2.5782804
474 / 0.38785542
475 The expressions that are added or subtracted must reduce to identical
477 expressions in primitive units, or an error message will be displayed:
478 You have: 12 printerspoint - 4 heredium
480 ^
481 Illegal sum of non-conformable units
482 As usual, the precedence for ‘+’ and ‘-’ is lower than that of the
484 other operators. A fractional quantity such as 2 1/2 cups can be given
485 as ‘(2+1|2) cups’; the parentheses are necessary because multiplication
486 has higher precedence than addition. If you omit the parentheses,
487 ‘units’ attempts to add ‘2’ and ‘1|2 cups’, and you get an error mes‐
488 sage:
489 You have: 2+1|2 cups
491 ^
492 Illegal sum or difference of non-conformable units
493 The expression could also be correctly written as ‘(2+1/2) cups’. If
495 you write ‘2 1|2 cups’ the space is interpreted as multiplication so
496 the result is the same as ‘1 cup’.
497 The ‘+’ and ‘-’ characters sometimes appears in exponents like
499 ‘3.43e+8’. This leads to an ambiguity in an expression like ‘3e+2 yC’.
500 The unit ‘e’ is a small unit of charge, so this can be regarded as
501 equivalent to ‘(3e+2) yC’ or ‘(3 e)+(2 yC)’. This ambiguity is
502 resolved by always interpreting ‘+’ and ‘-’ as part of an exponent if
503 possible.
504 Numbers as Units
506 For ‘units’, numbers are just another kind of unit. They can appear as
507 many times as you like and in any order in a unit expression. For
508 example, to find the volume of a box that is 2 ft by 3 ft by 12 ft in
509 steres, you could do the following:
510 You have: 2 ft 3 ft 12 ft
512 You want: stere
513 * 2.038813
514 / 0.49048148
515 You have: $ 5 / yard
517 You want: cents / inch
518 * 13.888889
519 / 0.072
520 And the second example shows how the dollar sign in the units conver‐
522 sion can precede the five. Be careful: ‘units’ will interpret ‘$5’
523 with no space as equivalent to ‘dollar^5’.
524 Built-in Functions
526 Several built-in functions are provided: ‘sin’, ‘cos’, ‘tan’, ‘ln’,
527 ‘log’, ‘exp’, ‘acos’, ‘atan’, ‘asin’, ‘cosh’, ‘sinh’, ‘tanh’, ‘acosh’,
528 ‘asinh’, and ‘atanh’. The ‘sin’, ‘cos’, and ‘tan’ functions require
529 either a dimensionless argument or an argument with dimensions of
530 angle.
531 You have: sin(30 degrees)
533 You want:
534 Definition: 0.5
535 You have: sin(pi/2)
537 You want:
538 Definition: 1
539 You have: sin(3 kg)
541 ^
542 Unit not dimensionless
543 The other functions on the list require dimensionless arguments. The
545 inverse trigonometric functions return arguments with dimensions of
546 angle.
547 The ‘ln’ and ‘log’ functions give natural log and log base 10 respec‐
549 tively. To obtain logs for any integer base, enter the desired base
550 immediately after ‘log’. For example, to get log base 2 you would
551 write ‘log2’ and to get log base 47 you could write ‘log47’.
552 You have: log2(32)
554 You want:
555 Definition: 5
556 You have: log3(32)
557 You want:
558 Definition: 3.1546488
559 You have: log4(32)
560 You want:
561 Definition: 2.5
562 You have: log32(32)
563 You want:
564 Definition: 1
565 You have: log(32)
566 You want:
567 Definition: 1.50515
568 You have: log10(32)
569 You want:
570 Definition: 1.50515
571 If you wish to take roots of units, you may use the ‘sqrt’ or
573 ‘cuberoot’ functions. These functions require that the argument have
574 the appropriate root. You can obtain higher roots by using fractional
575 exponents:
576 You have: sqrt(acre)
578 You want: feet
579 * 208.71074
580 / 0.0047913202
581 You have: (400 W/m^2 / stefanboltzmann)^(1/4)
583 You have:
584 Definition: 289.80882 K
585 You have: cuberoot(hectare)
587 ^
588 Unit not a root
589 Previous Result
591 You can insert the result of the previous conversion using the under‐
592 score (‘_’). It is useful when you want to convert the same input to
593 several different units, for example
594 You have: 2.3 tonrefrigeration
596 You want: btu/hr
597 * 27600
598 / 3.6231884e-005
599 You have: _
600 You want: kW
601 * 8.0887615
602 / 0.12362832
603 Suppose you want to do some deep frying that requires an oil depth of
605 2 inches. You have 1/2 gallon of oil, and want to know the largest-
606 diameter pan that will maintain the required depth. The nonlinear unit
607 ‘circlearea’ gives the radius of the circle (see Other Nonlinear Units,
608 for a more detailed description) in SI units; you want the diameter in
609 inches:
610 You have: 1|2 gallon / 2 in
612 You want: circlearea
613 0.10890173 m
614 You have: 2 _
615 You want: in
616 * 8.5749393
617 / 0.1166189
618 In most cases, surrounding white space is optional, so the previous
620 example could have used ‘2_’. If ‘_’ follows a non-numerical unit sym‐
621 bol, however, the space is required:
622 You have: m_
624 ^
625 Parse error
626 When ‘_’ is followed by a digit, the operation is multiplication rather
628 than exponentiation, so that ‘_2’, is equivalent to ‘_ * 2’ rather than
629 ‘_^2’.
630 You can use the ‘_’ symbol any number of times; for example,
632 You have: m
634 You want:
635 Definition: 1 m
636 You have: _ _
637 You want:
638 Definition: 1 m^2
639 Using ‘_’ before a conversion has been performed (e.g., immediately
641 after invocation) generates an error:
642 You have: _
644 ^
645 No previous result; '_' not set
646 Accordingly, ‘_’ serves no purpose when ‘units’ is invoked non-interac‐
648 tively.
649 If ‘units’ is invoked with the ‘--verbose’ option (see Invoking Units),
651 the value of ‘_’ is not expanded:
652 You have: mile
654 You want: ft
655 mile = 5280 ft
656 mile = (1 / 0.00018939394) ft
657 You have: _
658 You want: m
659 _ = 1609.344 m
660 _ = (1 / 0.00062137119) m
661 You can give ‘_’ at the ‘You want:’ prompt, but it usually is not very
663 useful.
664 Complicated Unit Expressions
666 The ‘units’ program is especially helpful in ensuring accuracy and
667 dimensional consistency when converting lengthy unit expressions. For
668 example, one form of the Darcy-Weisbach fluid-flow equation is
669 Delta P = (8 / pi)^2 (rho fLQ^2) / d^5,
671 where Delta P is the pressure drop, rho is the mass density, f is the
673 (dimensionless) friction factor, L is the length of the pipe, Q is the
674 volumetric flow rate, and d is the pipe diameter. It might be desired
675 to have the equation in the form
676 Delta P = A1 rho fLQ^2 / d^5
678 that accepted the user’s normal units; for typical units used in the
680 US, the required conversion could be something like
681 You have: (8/pi^2)(lbm/ft^3)ft(ft^3/s)^2(1/in^5)
683 You want: psi
684 * 43.533969
685 / 0.022970568
686 The parentheses allow individual terms in the expression to be entered
688 naturally, as they might be read from the formula. Alternatively, the
689 multiplication could be done with the ‘*’ rather than a space; then
690 parentheses are needed only around ‘ft^3/s’ because of its exponent:
691 You have: 8/pi^2 * lbm/ft^3 * ft * (ft^3/s)^2 /in^5
693 You want: psi
694 * 43.533969
695 / 0.022970568
696 Without parentheses, and using spaces for multiplication, the previous
698 conversion would need to be entered as
699 You have: 8 lb ft ft^3 ft^3 / pi^2 ft^3 s^2 in^5
701 You want: psi
702 * 43.533969
703 / 0.022970568
704 Backwards Compatibility:
706 ‘*’ and ‘-’ The original ‘units’ assigned multiplication a higher
707 precedence than division using the slash. This differs from the usual
708 precedence rules, which give multiplication and division equal prece‐
709 dence, and can be confusing for people who think of units as a calcula‐
710 tor.
711 The star operator (‘*’) included in this ‘units’ program has, by
713 default, the same precedence as division, and hence follows the usual
714 precedence rules. For backwards compatibility you can invoke ‘units’
715 with the ‘--oldstar’ option. Then ‘*’ has a higher precedence than
716 division, and the same precedence as multiplication using the space.
717 Historically, the hyphen (‘-’) has been used in technical publications
719 to indicate products of units, and the original ‘units’ program treated
720 it as a multiplication operator. Because ‘units’ provides several
721 other ways to obtain unit products, and because ‘-’ is a subtraction
722 operator in general algebraic expressions, ‘units’ treats the binary
723 ‘-’ as a subtraction operator by default. For backwards compatibility
724 use the ‘--product’ option, which causes ‘units’ to treat the binary
725 ‘-’ operator as a product operator. When ‘-’ is a multiplication oper‐
726 ator it has the same precedence as multiplication with a space, giving
727 it a higher precedence than division.
728 When ‘-’ is used as a unary operator it negates its operand. Regard‐
730 less of the ‘units’ options, if ‘-’ appears after ‘(’ or after ‘+’,
731 then it will act as a negation operator. So you can always compute 20
732 degrees minus 12 minutes by entering ‘20 degrees + -12 arcmin’. You
733 must use this construction when you define new units because you cannot
734 know what options will be in force when your definition is processed.
735
737 Nonlinear units are represented using functional notation. They make
738 possible nonlinear unit conversions such as temperature.
739 Temperature Conversions
741 Conversions between temperatures are different from linear conversions
742 between temperature increments—see the example below. The absolute
743 temperature conversions are handled by units starting with ‘temp’, and
744 you must use functional notation. The temperature-increment conver‐
745 sions are done using units starting with ‘deg’ and they do not require
746 functional notation.
747 You have: tempF(45)
749 You want: tempC
750 7.2222222
751 You have: 45 degF
753 You want: degC
754 * 25
755 / 0.04
756 Think of ‘tempF(x)’ not as a function but as a notation that indicates
758 that x should have units of ‘tempF’ attached to it. See Defining Non‐
759 linear Units. The first conversion shows that if it’s 45 degrees
760 Fahrenheit outside, it’s 7.2 degrees Celsius. The second conversion
761 indicates that a change of 45 degrees Fahrenheit corresponds to a
762 change of 25 degrees Celsius. The conversion from ‘tempF(x)’ is to
763 absolute temperature, so that
764 You have: tempF(45)
766 You want: degR
767 * 504.67
768 / 0.0019814929
769 gives the same result as
771 You have: tempF(45)
773 You want: tempR
774 * 504.67
775 / 0.0019814929
776 But if you convert ‘tempF(x)’ to ‘degC’, the output is probably not
778 what you expect:
779 You have: tempF(45)
781 You want: degC
782 * 280.37222
783 / 0.0035666871
784 The result is the temperature in K, because ‘degC’ is defined as ‘K’,
786 the Kelvin. For consistent results, use the ‘tempX’ units when convert‐
787 ing to a temperature rather than converting a temperature increment.
788 The ‘tempC()’ and ‘tempF()’ definitions are limited to positive abso‐
790 lute temperatures, and giving a value that would result in a negative
791 absolute temperature generates an error message:
792 You have: tempC(-275)
794 ^
795 Argument of function outside domain
796 ^
797 Other Nonlinear Units
799 Some other examples of nonlinear units are numerous different ring
800 sizes and wire gauges, the grit sizes used for abrasives, the decibel
801 scale, shoe size, scales for the density of sugar (e.g., baume). The
802 standard data file also supplies units for computing the area of a cir‐
803 cle and the volume of a sphere. See the standard units data file for
804 more details. Wire gauges with multiple zeroes are signified using
805 negative numbers where two zeroes is ‘-1’. Alternatively, you can use
806 the synonyms ‘g00’, ‘g000’, and so on that are defined in the standard
807 units data file.
808 You have: wiregauge(11)
810 You want: inches
811 * 0.090742002
812 / 11.020255
813 You have: brwiregauge(g00)
815 You want: inches
816 * 0.348
817 / 2.8735632
818 You have: 1 mm
820 You want: wiregauge
821 18.201919
822 You have: grit_P(600)
824 You want: grit_ansicoated
825 342.76923
826 The last example shows the conversion from P graded sand paper, which
828 is the European standard and may be marked “P600” on the back, to the
829 USA standard.
830 You can compute the area of a circle using the nonlinear unit,
832 ‘circlearea’. You can also do this using the circularinch or cir‐
833 cleinch. The next example shows two ways to compute the area of a cir‐
834 cle with a five inch radius and one way to compute the volume of a
835 sphere with a radius of one meter.
836 You have: circlearea(5 in)
838 You want: in2
839 * 78.539816
840 / 0.012732395
841 You have: 10^2 circleinch
843 You want: in2
844 * 78.539816
845 / 0.012732395
846 You have: spherevol(meter)
848 You want: ft3
849 * 147.92573
850 / 0.0067601492
851 The inverse of a nonlinear conversion is indicated by prefixing a tilde
853 (‘~’) to the nonlinear unit name:
854 You have: ~wiregauge(0.090742002 inches)
856 You want:
857 Definition: 11
858 You can give a nonlinear unit definition without an argument or paren‐
860 theses, and press Enter at the ‘You want:’ prompt to get the definition
861 of a nonlinear unit; if the definition is not valid for all real num‐
862 bers, the range of validity is also given. If the definition requires
863 specific units this information is also displayed:
864 You have: tempC
866 Definition: tempC(x) = x K + stdtemp
867 defined for x >= -273.15
868 You have: ~tempC
869 Definition: ~tempC(tempC) = (tempC +(-stdtemp))/K
870 defined for tempC >= 0 K
871 You have: circlearea
872 Definition: circlearea(r) = pi r^2
873 r has units m
874 To see the definition of the inverse use the ‘~’ notation. In this
876 case the parameter in the functional definition will usually be the
877 name of the unit. Note that the inverse for ‘tempC’ shows that it
878 requires units of ‘K’ in the specification of the allowed range of val‐
879 ues. Nonlinear unit conversions are described in more detail in Defin‐
880 ing Nonlinear Units.
881
883 Outside of the SI, it is sometimes desirable to convert a single unit
884 to a sum of units—for example, feet to feet plus inches. The conver‐
885 sion from sums of units was described in Sums and Differences of Units,
886 and is a simple matter of adding the units with the ‘+’ sign:
887 You have: 12 ft + 3 in + 3|8 in
889 You want: ft
890 * 12.28125
891 / 0.081424936
892 Although you can similarly write a sum of units to convert to, the
894 result will not be the conversion to the units in the sum, but rather
895 the conversion to the particular sum that you have entered:
896 You have: 12.28125 ft
898 You want: ft + in + 1|8 in
899 * 11.228571
900 / 0.089058524
901 The unit expression given at the ‘You want:’ prompt is equivalent to
903 asking for conversion to multiples of ‘1 ft + 1 in + 1|8 in’, which is
904 1.09375 ft, so the conversion in the previous example is equivalent to
905 You have: 12.28125 ft
907 You want: 1.09375 ft
908 * 11.228571
909 / 0.089058524
910 In converting to a sum of units like miles, feet and inches, you typi‐
912 cally want the largest integral value for the first unit, followed by
913 the largest integral value for the next, and the remainder converted to
914 the last unit. You can do this conversion easily with ‘units’ using a
915 special syntax for lists of units. You must list the desired units in
916 order from largest to smallest, separated by the semicolon (‘;’) char‐
917 acter:
918 You have: 12.28125 ft
920 You want: ft;in;1|8 in
921 12 ft + 3 in + 3|8 in
922 The conversion always gives integer coefficients on the units in the
924 list, except possibly the last unit when the conversion is not exact:
925 You have: 12.28126 ft
927 You want: ft;in;1|8 in
928 12 ft + 3 in + 3.00096 * 1|8 in
929 The order in which you list the units is important:
931 You have: 3 kg
933 You want: oz;lb
934 105 oz + 0.051367866 lb
935 You have: 3 kg
937 You want: lb;oz
938 6 lb + 9.8218858 oz
939 Listing ounces before pounds produces a technically correct result, but
941 not a very useful one. You must list the units in descending order of
942 size in order to get the most useful result.
943 Ending a unit list with the separator ‘;’ has the same effect as
945 repeating the last unit on the list, so ‘ft;in;1|8 in;’ is equivalent
946 to ‘ft;in;1|8 in;1|8 in’. With the example above, this gives
947 You have: 12.28126 ft
949 You want: ft;in;1|8 in;
950 12 ft + 3 in + 3|8 in + 0.00096 * 1|8 in
951 in effect separating the integer and fractional parts of the coeffi‐
953 cient for the last unit. If you instead prefer to round the last coef‐
954 ficient to an integer you can do this with the ‘--round’ (‘-r’) option.
955 With the previous example, the result is
956 You have: 12.28126 ft
958 You want: ft;in;1|8 in
959 12 ft + 3 in + 3|8 in (rounded down to nearest 1|8 in)
960 When you use the ‘-r’ option, repeating the last unit on the list has
962 no effect (e.g., ‘ft;in;1|8 in;1|8 in’ is equivalent to ‘ft;in;1|8
963 in’), and hence neither does ending a list with a ‘;’. With a single
964 unit and the ‘-r’ option, a terminal ‘;’ does have an effect: it causes
965 ‘units’ to treat the single unit as a list and produce a rounded value
966 for the single unit. Without the extra ‘;’, the ‘-r’ option has no
967 effect on single unit conversions. This example shows the output using
968 the ‘-r’ option:
969 You have: 12.28126 ft
971 You want: in
972 * 147.37512
973 / 0.0067854058
974 You have: 12.28126 ft
976 You want: in;
977 147 in (rounded down to nearest in)
978 Each unit that appears in the list must be conformable with the first
980 unit on the list, and of course the listed units must also be conform‐
981 able with the unit that you enter at the ‘You have:’ prompt.
982 You have: meter
984 You want: ft;kg
985 ^
986 conformability error
987 ft = 0.3048 m
988 kg = 1 kg
989 You have: meter
991 You want: lb;oz
992 conformability error
993 1 m
994 0.45359237 kg
995 In the first case, ‘units’ reports the disagreement between units
997 appearing on the list. In the second case, ‘units’ reports disagree‐
998 ment between the unit you entered and the desired conversion. This
999 conformability error is based on the first unit on the unit list.
1000 Other common candidates for conversion to sums of units are angles and
1002 time:
1003 You have: 23.437754 deg
1005 You want; deg;arcmin;arcsec
1006 23 deg + 26 arcmin + 15.9144 arcsec
1007 You have: 7.2319 hr
1009 You want: hr;min;sec
1010 7 hr + 13 min + 54.84 sec
1011 In North America, recipes for cooking typically measure ingredients by
1013 volume, and use units that are not always convenient multiples of each
1014 other. Suppose that you have a recipe for 6 and you wish to make a
1015 portion for 1. If the recipe calls for 2 1/2 cups of an ingredient,
1016 you might wish to know the measurements in terms of measuring devices
1017 you have available, you could use ‘units’ and enter
1018 You have: (2+1|2) cup / 6
1020 You want: cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
1021 1|3 cup + 1 tbsp + 1 tsp
1022 By default, if a unit in a list begins with fraction of the form 1|x
1024 and its multiplier is an integer, the fraction is given as the product
1025 of the multiplier and the numerator; for example,
1026 You have: 12.28125 ft
1028 You want: ft;in;1|8 in;
1029 12 ft + 3 in + 3|8 in
1030 In many cases, such as the example above, this is what is wanted, but
1032 sometimes it is not. For example, a cooking recipe for 6 might call
1033 for 5 1/4 cup of an ingredient, but you want a portion for 2, and your
1034 1-cup measure is not available; you might try
1035 You have: (5+1|4) cup / 3
1037 You want: 1|2 cup;1|3 cup;1|4 cup
1038 3|2 cup + 1|4 cup
1039 This result might be fine for a baker who has a 1 1/2-cup measure (and
1041 recognizes the equivalence), but it may not be as useful to someone
1042 with more limited set of measures, who does want to do additional cal‐
1043 culations, and only wants to know “How many 1/2-cup measures to I need
1044 to add?” After all, that’s what was actually asked. With the ‘--show-
1045 factor’ option, the factor will not be combined with a unity numerator,
1046 so that you get
1047 You have: (5+1|4) cup / 3
1049 You want: 1|2 cup;1|3 cup;1|4 cup
1050 3 * 1|2 cup + 1|4 cup
1051 A user-specified fractional unit with a numerator other than 1 is never
1053 overridden, however—if a unit list specifies ‘3|4 cup;1|2 cup’, a
1054 result equivalent to 1 1/2 cups will always be shown as ‘2 * 3|4 cup’
1055 whether or not the ‘--show-factor’ option is given.
1056 Some applications for unit lists may be less obvious. Suppose that you
1058 have a postal scale and wish to ensure that it’s accurate at 1 oz, but
1059 have only metric calibration weights. You might try
1060 You have: 1 oz
1062 You want: 100 g;50 g; 20 g;10 g;5 g;2 g;1 g;
1063 20 g + 5 g + 2 g + 1 g + 0.34952312 * 1 g
1064 You might then place one each of the 20 g, 5 g, 2 g, and 1 g weights on
1066 the scale and hope that it indicates close to
1067 You have: 20 g + 5 g + 2 g + 1 g
1069 You want: oz;
1070 0.98767093 oz
1071 Appending ‘;’ to ‘oz’ forces a one-line display that includes the unit;
1073 here the integer part of the result is zero, so it is not displayed.
1074 A unit list such as
1076 cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
1078 can be tedious to enter. The ‘units’ program provides shorthand names
1080 for some common combinations:
1081 hms hours, minutes, seconds
1083 dms angle: degrees, minutes, seconds
1084 time years, days, hours, minutes and seconds
1085 usvol US cooking volume: cups and smaller
1086 Using these shorthands, or unit list aliases, you can do the following
1088 conversions:
1089 You have: anomalisticyear
1091 You want: time
1092 1 year + 25 min + 3.4653216 sec
1093 You have: 1|6 cup
1094 You want: usvol
1095 2 tbsp + 2 tsp
1096 You cannot combine a unit list alias with other units: it must appear
1098 alone at the ‘You want:’ prompt.
1099 You can display the definition of a unit list alias by entering it at
1101 the ‘You have:’ prompt:
1102 You have: dms
1104 Definition: unit list, deg;arcmin;arcsec
1105 When you specify compact output with ‘--compact’, ‘--terse’ or ‘-t’ and
1107 perform conversion to a unit list, ‘units’ lists the conversion factors
1108 for each unit in the list, separated by semicolons.
1109 You have: year
1111 You want: day;min;sec
1112 365;348;45.974678
1113 Unlike the case of regular output, zeros are included in this output
1115 list:
1116 You have: liter
1118 You want: cup;1|2 cup;1|4 cup;tbsp
1119 4;0;0;3.6280454
1120
1122 The SI—an extension of the MKS (meter-kilogram-second) system—has
1123 largely supplanted the older CGS (centimeter-gram-second) system, but
1124 CGS units are still used in a few specialized fields, especially in
1125 physics where they lead to a more elegant formulation of Maxwell’s
1126 equations. Conversions between SI and CGS involving mechanical units
1127 are straightforward, involving powers of 10 (e.g., 1 m = 100 cm). Con‐
1128 versions involving electromagnetic units are more complicated, and
1129 ‘units’ supports three different systems of CGS units: electrostatic
1130 units (ESU), electromagnetic units (EMU), and the Gaussian system. The
1131 differences between these systems arise from different choices made for
1132 proportionality constants in electromagnetic equations. Coulomb’s law
1133 gives electrostatic force between two charges separated by a distance
1134 delim $$ r:
1135 F = k_C q_1 q_2 / r^2.
1137 Ampere’s law gives the electromagnetic force per unit length between
1139 two current-carrying conductors separated by a distance r:
1140 F/l = 2 k_A I_1 I_2 / r.
1142 The two constants, k_C and k_A, are related by the square of the speed
1144 of light: k_A = k_C / c^2.
1145 In the SI, the constants have dimensions, and an additional base unit,
1147 the ampere, measures electric current. The CGS systems do not define
1148 new base units, but express charge and current as derived units in
1149 terms of mass, length, and time. In the ESU system, the constant for
1150 Coulomb’s law is chosen to be unity and dimensionless, which defines
1151 the unit of charge. In the EMU system, the constant for Ampere’s law
1152 is chosen to be unity and dimensionless, which defines a unit of cur‐
1153 rent. The Gaussian system usually uses the ESU units for charge and
1154 current; it chooses another constant so that the units for the electric
1155 and magnetic fields are the same.
1156 The dimensions of electrical quantities in the various CGS systems are
1158 different from the SI dimensions for the same units; strictly, conver‐
1159 sions between these systems and SI are not possible. But units in dif‐
1160 ferent systems relate to the same physical quantities, so there is a
1161 correspondence between these units. The ‘units’ program defines the
1162 units so that you can convert between corresponding units in the vari‐
1163 ous systems.
1164 Specifying CGS Units
1166 The CGS definitions involve cm^(1/2) and g^(1/2), which is problematic
1167 because ‘units’ does not normally support fractional roots of base
1168 units. The ‘--units’ (‘-u’) option allows selection of a CGS unit sys‐
1169 tem and works around this restriction by introducing base units for the
1170 square roots of length and mass: ‘sqrt_cm’ and ‘sqrt_g’. The centime‐
1171 ter then becomes ‘sqrt_cm^2’ and the gram, ‘sqrt_g^2’. This allows
1172 working from equations using the units in the CGS system, and enforcing
1173 dimensional conformity within that system. Recognized arguments to the
1174 ‘--units’ option are ‘gauss[ian]’, ‘esu’, ‘emu’, and ‘si’; the argument
1175 is case insensitive. The default mode for ‘units’ is SI units; the
1176 only effect of giving ‘si’ with the ‘--units’ option is to prepend
1177 ‘(SI)’ to the ‘You have:’ prompt. Giving an unrecognized system gener‐
1178 ates a warning, and ‘units’ uses SI units.
1179 The changes resulting from the ‘--units’ option are actually controlled
1181 by the ‘UNITS_SYSTEM’ environment variable. If you frequently work
1182 with one of the supported CGS units systems, you may set this environ‐
1183 ment variable rather than giving the ‘--units’ option at each invoca‐
1184 tion. As usual, an option given on the command line overrides the set‐
1185 ting of the environment variable. For example, if you would normally
1186 work with Gaussian units but might occasionally work with SI, you could
1187 set ‘UNITS_SYSTEM’ to ‘gaussian’ and specify SI with the ‘--units’
1188 option. Unlike the argument to the ‘--units’ option, the value of
1189 ‘UNITS_SYSTEM’ is case sensitive, so setting a value of ‘EMU’ will have
1190 no effect other than to give an error message and set SI units.
1191 The CGS definitions appear as conditional settings in the standard
1193 units data file, which you can consult for more information on how
1194 these units are defined, or on how to define an alternate units system.
1195 CGS Units Systems
1197 The ESU system derives the electromagnetic units from its unit of
1198 charge, the statcoulomb, which is defined from Coulomb’s law. The
1199 statcoulomb equals dyne^(1/2) cm, or cm^(3/2) g^(1/2) s^(−1). The unit
1200 of current, the statampere, is statcoulomb sec, analogous to the rela‐
1201 tionship in SI. Other electrical units are then derived in a manner
1202 similar to that for SI units; the units use the SI names prefixed by
1203 ‘stat-’, e.g., ‘statvolt’ or ‘statV’. The prefix ‘st-’ is also recog‐
1204 nized (e.g., ‘stV’).
1205 The EMU system derives the electromagnetic units from its unit of cur‐
1207 rent, the abampere, which is defined in terms of Ampere’s law. The
1208 abampere is equal to dyne^(1/2), or cm^(1/2) g^(1/2) s^(−1). delim off
1209 The unit of charge, the abcoulomb, is abampere sec, again analogous to
1210 the SI relationship. Other electrical units are then derived in a man‐
1211 ner similar to that for SI units; the units use the SI names prefixed
1212 by ‘ab-’, e.g., ‘abvolt’ or ‘abV’. The magnetic field units include
1213 the gauss, the oersted and the maxwell.
1214 The Gaussian units system, which was also known as the Symmetric Sys‐
1216 tem, uses the same charge and current units as the ESU system (e.g.,
1217 ‘statC’, ‘statA’); it differs by defining the magnetic field so that it
1218 has the same units as the electric field. The resulting magnetic field
1219 units are the same ones used in the EMU system: the gauss, the oersted
1220 and the maxwell.
1221 Conversions Between Different Systems
1223 The CGS systems define units that measure the same thing but may have
1224 conflicting dimensions. Furthermore, the dimensions of the electromag‐
1225 netic CGS units are never compatible with SI. But if you measure
1226 charge in two different systems you have measured the same physical
1227 thing, so there is a correspondence between the units in the different
1228 systems, and ‘units’ supports conversions between corresponding units.
1229 When running with SI, ‘units’ defines all of the CGS units in terms of
1230 SI. When you select a CGS system, ‘units’ defines the SI units and the
1231 other CGS system units in terms of the system you have selected.
1232 (Gaussian) You have: statA
1234 You want: abA
1235 * 3.335641e-11
1236 / 2.9979246e+10
1237 (Gaussian) You have: abA
1238 You want: sqrt(dyne)
1239 conformability error
1240 2.9979246e+10 sqrt_cm^3 sqrt_g / s^2
1241 1 sqrt_cm sqrt_g / s
1242 In the above example, ‘units’ converts between the current units statA
1244 and abA even though the abA, from the EMU system, has incompatible
1245 dimensions. This works because in Gaussian mode, the abA is defined in
1246 terms of the statA, so it does not have the correct definition for EMU;
1247 consequently, you cannot convert the abA to its EMU definition.
1248 One challenge of conversion is that because the CGS system has fewer
1250 base units, quantities that have different dimensions in SI may have
1251 the same dimension in a CGS system. And yet, they may not have the
1252 same conversion factor. For example, the unit for the E field and B
1253 fields are the same in the Gaussian system, but the conversion factors
1254 to SI are quite different. This means that correct conversion is only
1255 possible if you keep track of what quantity is being measured. You
1256 cannot convert statV/cm to SI without indicating which type of field
1257 the unit measures. To aid in dimensional analysis, ‘units’ defines
1258 various dimension units such as LENGTH, TIME, and CHARGE to be the
1259 appropriate dimension in SI. The electromagnetic dimensions such as
1260 B_FIELD or E_FIELD may be useful aids both for conversion and dimen‐
1261 sional analysis in CGS. You can convert them to or from CGS in order
1262 to perform SI conversions that in some cases will not work directly due
1263 to dimensional incompatibilities. This example shows how the Gaussian
1264 system uses the same units for all of the fields, but they all have
1265 different conversion factors with SI.
1266 (Gaussian) You have: statV/cm
1268 You want: E_FIELD
1269 * 29979.246
1270 / 3.335641e-05
1271 (Gaussian) You have: statV/cm
1272 You want: B_FIELD
1273 * 0.0001
1274 / 10000
1275 (Gaussian) You have: statV/cm
1276 You want: H_FIELD
1277 * 79.577472
1278 / 0.012566371
1279 (Gaussian) You have: statV/cm
1280 You want: D_FIELD
1281 * 2.6544187e-07
1282 / 3767303.1
1283 The next example shows that the oersted cannot be converted directly to
1285 the SI unit of magnetic field, A/m, because the dimensions conflict.
1286 We cannot redefine the ampere to make this work because then it would
1287 not convert with the statampere. But you can still do this conversion
1288 as shown below.
1289 (Gaussian) You have: oersted
1291 You want: A/m
1292 conformability error
1293 1 sqrt_g / s sqrt_cm
1294 29979246 sqrt_cm sqrt_g / s^2
1295 (Gaussian) You have: oersted
1296 You want: H_FIELD
1297 * 79.577472
1298 / 0.012566371
1299 Prompt Prefix
1301 If a unit system is specified with the ‘--units’ option, the selected
1302 system’s name is prepended to the ‘You have:’ prompt as a reminder,
1303 e.g.,
1304 (Gaussian) You have: stC
1306 You want:
1307 Definition: statcoulomb = sqrt(dyne) cm = 1 sqrt_cm^3 sqrt_g / s
1308 You can suppressed the prefix by including a line
1310 !prompt
1312 with no argument in a site or personal units data file. The prompt can
1314 be conditionally suppressed by including such a line within ‘!var’
1315 ‘!endvar’ constructs, e.g.,
1316 !var UNITS_SYSTEM gaussian gauss
1318 !prompt
1319 !endvar
1320 This might be appropriate if you normally use Gaussian units and find
1322 the prefix distracting but want to be reminded when you have selected a
1323 different CGS system.
1324
1326 The ‘--log’ option allows you to save the results of calculations in a
1327 file; this can be useful if you need a permanent record of your work.
1328 For example, the fluid-flow conversion in Complicated Unit Expressions,
1329 is lengthy, and if you were to use it in designing a piping system, you
1330 might want a record of it for the project file. If the interactive
1331 session
1332 # Conversion factor A1 for pressure drop
1334 # dP = A1 rho f L Q^2/d^5
1335 You have: (8/pi^2) (lbm/ft^3)ft(ft^3/s)^2(1/in^5) # Input units
1336 You want: psi
1337 * 43.533969
1338 / 0.022970568
1339 were logged, the log file would contain
1341 ### Log started Fri Oct 02 15:55:35 2015
1343 # Conversion factor A1 for pressure drop
1345 # dP = A1 rho f L Q^2/d^5
1346 From: (8/pi^2) (lbm/ft^3)ft(ft^3/s)^2(1/in^5) # Input units
1347 To: psi
1348 * 43.533969
1349 / 0.022970568
1350 The time is written to the log file when the file is opened.
1352 The use of comments can help clarify the meaning of calculations for
1354 the log. The log includes conformability errors between the units at
1355 the ‘You have:’ and ‘You want:’ prompts, but not other errors, includ‐
1356 ing lack of conformability of items in sums or differences or among
1357 items in a unit list. For example, a conversion between zenith angle
1358 and elevation angle could involve
1359 You have: 90 deg - (5 deg + 22 min + 9 sec)
1361 ^
1362 Illegal sum or difference of non-conformable units
1363 You have: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
1364 You want: dms
1365 84 deg + 37 arcmin + 51 arcsec
1366 You have: _
1367 You want: deg
1368 * 84.630833
1369 / 0.011816024
1370 You have:
1371 The log file would contain
1373 From: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
1375 To: deg;arcmin;arcsec
1376 84 deg + 37 arcmin + 51 arcsec
1377 From: _
1378 To: deg
1379 * 84.630833
1380 / 0.011816024
1381 The initial entry error (forgetting that minutes have dimension of
1383 time, and that arcminutes must be used for dimensions of angle) does
1384 not appear in the output. When converting to a unit list alias,
1385 ‘units’ expands the alias in the log file.
1386 The ‘From:’ and ‘To:’ tags are written to the log file even if the
1388 ‘--quiet’ option is given. If the log file exists when ‘units’ is
1389 invoked, the new results are appended to the log file. The time is
1390 written to the log file each time the file is opened. The ‘--log’
1391 option is ignored when ‘units’ is used non-interactively.
1392
1394 You invoke ‘units’ like this:
1395 units [options] [from-unit [to-unit]]
1397 If the from-unit and to-unit are omitted, the program will use interac‐
1399 tive prompts to determine which conversions to perform. See Interac‐
1400 tive Use. If both from-unit and to-unit are given, ‘units’ will print
1401 the result of that single conversion and then exit. If only from-unit
1402 appears on the command line, ‘units’ will display the definition of
1403 that unit and exit. Units specified on the command line may need to be
1404 quoted to protect them from shell interpretation and to group them into
1405 two arguments. Note also that the ‘--quiet’ option is enabled by
1406 default if you specify from-unit on the command line. See Command Line
1407 Use.
1408 The default behavior of ‘units’ can be changed by various options given
1410 on the command line. In most cases, the options may be given in either
1411 short form (a single ‘-’ followed by a single character) or long form
1412 (‘--’ followed by a word or hyphen-separated words). Short-form
1413 options are cryptic but require less typing; long-form options require
1414 more typing but are more explanatory and may be more mnemonic. With
1415 long-form options you need only enter sufficient characters to uniquely
1416 identify the option to the program. For example, ‘--out %f’ works, but
1417 ‘--o %f’ fails because ‘units’ has other long options beginning with
1418 ‘o’. However, ‘--q’ works because ‘--quiet’ is the only long option
1419 beginning with ‘q’.
1420 Some options require arguments to specify a value (e.g., ‘-d 12’ or
1422 ‘--digits 12’). Short-form options that do not take arguments may be
1423 concatenated (e.g., ‘-erS’ is equivalent to ‘-e -r -S’); the last
1424 option in such a list may be one that takes an argument (e.g.,
1425 ‘-ed 12’). With short-form options, the space between an option and
1426 its argument is optional (e.g., ‘-d12’ is equivalent to ‘-d 12’).
1427 Long-form options may not be concatenated, and the space between a
1428 long-form option and its argument is required. Short-form and long-
1429 form options may be intermixed on the command line. Options may be
1430 given in any order, but when incompatible options (e.g., ‘--output-
1431 format’ and ‘--exponential’) are given in combination, behavior is con‐
1432 trolled by the last option given. For example, ‘-o%.12f -e’ gives
1433 exponential format with the default eight significant digits).
1434 The following options are available:
1436 -c, --check
1438 Check that all units and prefixes defined in the units data file
1439 reduce to primitive units. Print a list of all units that can‐
1440 not be reduced. Also display some other diagnostics about sus‐
1441 picious definitions in the units data file. Only definitions
1442 active in the current locale are checked. You should always run
1443 ‘units’ with this option after modifying a units data file.
1444 --check-verbose, --verbose-check
1446 Like the ‘--check’ option, this option prints a list of units
1447 that cannot be reduced. But to help find unit definitions that
1448 cause endless loops, it lists the units as they are checked. If
1449 ‘units’ hangs, then the last unit to be printed has a bad defi‐
1450 nition. Only definitions active in the current locale are
1451 checked.
1452 -d ndigits, --digits ndigits
1454 Set the number of significant digits in the output to the value
1455 specified (which must be greater than zero). For example,
1456 ‘-d 12’ sets the number of significant digits to 12. With expo‐
1457 nential output ‘units’ displays one digit to the left of the
1458 decimal point and eleven digits to the right of the decimal
1459 point. On most systems, the maximum number of internally mean‐
1460 ingful digits is 15; if you specify a greater number than your
1461 system’s maximum, ‘units’ will print a warning and set the num‐
1462 ber to the largest meaningful value. To directly set the maxi‐
1463 mum value, give an argument of ‘max’ (e.g., ‘-d max’). Be
1464 aware, of course, that “significant” here refers only to the
1465 display of numbers; if results depend on physical constants not
1466 known to this precision, the physically meaningful precision may
1467 be less than that shown. The ‘--digits’ option conflicts with
1468 the ‘--output-format’ option.
1469 -e, --exponential
1471 Set the numeric output format to exponential (i.e., scientific
1472 notation), like that used in the Unix ‘units’ program. The
1473 default precision is eight significant digits (seven digits to
1474 the right of the decimal point); this can be changed with the
1475 ‘--digits’ option. The ‘--exponential’ option conflicts with
1476 the ‘--output-format’ option.
1477 -o format, --output-format format
1479 This option affords complete control over the numeric output
1480 format using the specified format. The format is a single float‐
1481 ing point numeric format for the ‘printf()’ function in the C
1482 programming language. All compilers support the format types
1483 ‘g’ and ‘G’ to specify significant digits, ‘e’ and ‘E’ for sci‐
1484 entific notation, and ‘f’ for fixed-point decimal. The ISO C99
1485 standard introduced the ‘F’ type for fixed-point decimal and the
1486 ‘a’ and ‘A’ types for hexadecimal floating point; these types
1487 are allowed with compilers that support them. The default for‐
1488 mat is ‘%.8g’; for greater precision, you could specify
1489 ‘-o %.15g’. See Numeric Output Format and the documentation for
1490 ‘printf()’ for more detailed descriptions of the format specifi‐
1491 cation. The ‘--output-format’ option affords the greatest con‐
1492 trol of the output appearance, but requires at least rudimentary
1493 knowledge of the ‘printf()’ format syntax. If you don’t want to
1494 bother with the ‘printf()’ syntax, you can specify greater pre‐
1495 cision more simply with the ‘--digits’ option or select exponen‐
1496 tial format with ‘--exponential’. The ‘--output-format’ option
1497 is incompatible with the ‘--exponential’ and ‘--digits’ options.
1498 -f filename, --file filename
1500 Instruct ‘units’ to load the units file filename. You can spec‐
1501 ify up to 25 units files on the command line. When you use this
1502 option, ‘units’ will load only the files you list on the command
1503 line; it will not load the standard file or your personal units
1504 file unless you explicitly list them. If filename is the empty
1505 string (‘-f ""’), the default units file (or that specified by
1506 ‘UNITSFILE’) will be loaded in addition to any others specified
1507 with ‘-f’.
1508 -L logfile, --log logfile
1510 Save the results of calculations in the file logfile; this can
1511 be useful if it is important to have a record of unit conver‐
1512 sions or other calculations that are to be used extensively or
1513 in a critical activity such as a program or design project. If
1514 logfile exits, the new results are appended to the file. This
1515 option is ignored when ‘units’ is used non-interactively. See
1516 Logging Calculations for a more detailed description and some
1517 examples.
1518 -H filename, --history filename
1520 Instruct ‘units’ to save history to filename, so that a record
1521 of your commands is available for retrieval across different
1522 ‘units’ invocations. To prevent the history from being saved
1523 set filename to the empty string (‘-H ""’). This option has no
1524 effect if readline is not available.
1525 -h, --help
1527 Print out a summary of the options for ‘units’.
1528 -m, --minus
1530 Causes ‘-’ to be interpreted as a subtraction operator. This is
1531 the default behavior.
1532 -p, --product
1534 Causes ‘-’ to be interpreted as a multiplication operator when
1535 it has two operands. It will act as a negation operator when it
1536 has only one operand: ‘(-3)’. By default ‘-’ is treated as a
1537 subtraction operator.
1538 --oldstar
1540 Causes ‘*’ to have the old-style precedence, higher than the
1541 precedence of division so that ‘1/2*3’ will equal ‘1/6’.
1542 --newstar
1544 Forces ‘*’ to have the new (default) precedence that follows the
1545 usual rules of algebra: the precedence of ‘*’ is the same as the
1546 precedence of ‘/’, so that ‘1/2*3’ will equal ‘3/2’.
1547 -r, --round
1549 When converting to a combination of units given by a unit list,
1550 round the value of the last unit in the list to the nearest
1551 integer.
1552 -S, --show-factor
1554 When converting to a combination of units specified in a list,
1555 always show a non-unity factor before a unit that begins with a
1556 fraction with a unity denominator. By default, if the unit in a
1557 list begins with fraction of the form 1|x and its multiplier is
1558 an integer other than 1, the fraction is given as the product of
1559 the multiplier and the numerator (e.g., ‘3|8 in’ rather than ‘3
1560 * 1|8 in’). In some cases, this is not what is wanted; for
1561 example, the results for a cooking recipe might show ‘3 *
1562 1|2 cup’ as ‘3|2 cup’. With the ‘--show-factor’ option, a
1563 result equivalent to 1.5 cups will display as ‘3 * 1|2 cup’
1564 rather than ‘3|2 cup’. A user-specified fractional unit with a
1565 numerator other than 1 is never overridden, however—if a unit
1566 list specifies ‘3|4 cup;1|2 cup’, a result equivalent to 1 1/2
1567 cups will always be shown as ‘2 * 3|4 cup’ whether or not the
1568 ‘--show-factor’ option is given.
1569 -v, --verbose
1571 Give slightly more verbose output when converting units. When
1572 combined with the ‘-c’ option this gives the same effect as
1573 ‘--check-verbose’. When combined with ‘--version’ produces a
1574 more detailed output, equivalent to the ‘--info’ option.
1575 -V, --version
1577 Print the program version number, tell whether the ‘readline’
1578 library has been included, tell whether UTF-8 support has been
1579 included; give the locale, the location of the default units
1580 data file, and the location of the personal units data file;
1581 indicate if the personal units data file does not exist.
1582 When given in combination with the ‘--terse’ option, the program
1584 prints only the version number and exits.
1585 When given in combination with the ‘--verbose’ option, the pro‐
1587 gram, the ‘--version’ option has the same effect as the ‘--info’
1588 option below.
1589 -I, --info
1591 Print the information given with the ‘--version’ option, show
1592 the pathname of the units program, show the status of the
1593 ‘UNITSFILE’ and ‘MYUNITSFILE’ environment variables, and addi‐
1594 tional information about how ‘units’ locates the related files.
1595 On systems running Microsoft Windows, the status of the
1596 ‘UNITSLOCALE’ environment variable and information about the
1597 related locale map are also given. This option is usually of
1598 interest only to developers and administrators, but it can some‐
1599 times be useful for troubleshooting.
1600 Combining the ‘--version’ and ‘--verbose’ options has the same
1602 effect as giving ‘--info’.
1603 -U, --unitsfile
1605 Print the location of the default units data file and exit; if
1606 the file cannot be found, print “Units data file not found”.
1607 -u (gauss[ian]|esu|emu), --units (gauss[ian]|esu|emu)
1609 Specify a CGS units system: Gaussian, ESU, or EMU.
1610 -l locale, --locale locale
1612 Force a specified locale such as ‘en_GB’ to get British defini‐
1613 tions by default. This overrides the locale determined from
1614 system settings or environment variables. See Locale for a
1615 description of locale format.
1616 -n, --nolists
1618 Disable conversion to unit lists.
1619 -s, --strict
1621 Suppress conversion of units to their reciprocal units. For
1622 example, ‘units’ will normally convert hertz to seconds because
1623 these units are reciprocals of each other. The strict option
1624 requires that units be strictly conformable to perform a conver‐
1625 sion, and will give an error if you attempt to convert hertz to
1626 seconds.
1627 -1, --one-line
1629 Give only one line of output (the forward conversion); do not
1630 print the reverse conversion. If a reciprocal conversion is
1631 performed, then ‘units’ will still print the “reciprocal conver‐
1632 sion” line.
1633 -t, --terse
1635 Print only a single conversion factor. This option can be used
1636 when calling ‘units’ from another program so that the output is
1637 easy to parse. This option has the combined effect of these
1638 options: ‘--strict’ ‘--quiet’ ‘--one-line’ ‘--compact’. When
1639 combined with ‘--version’ it produces a display showing only the
1640 program name and version number.
1641 --compact
1643 Give compact output featuring only the conversion factor; the
1644 multiplication and division signs are not shown, and there is no
1645 leading whitespace. If you convert to a unit list, then the
1646 output is a semicolon separated list of factors. This turns off
1647 the ‘--verbose’ option.
1648 -q, --quiet, --silent
1650 Suppress the display of statistics about the number of units
1651 loaded, any messages printed by the units database, and the
1652 prompting of the user for units. This option does not affect
1653 how ‘units’ displays the results. This option is turned on by
1654 default if you invoke ‘units’ with a unit expression on the com‐
1655 mand line.
1656
1658 The output can be tweaked in various ways using command line options.
1659 With no options, the output looks like this
1660 $ units
1662 Currency exchange rates from FloatRates (USD base) on 2019-02-20
1663 3070 units, 109 prefixes, 109 nonlinear units
1664 You have: 23ft
1666 You want: m
1667 * 7.0104
1668 / 0.14264521
1669 You have: m
1670 You want: ft;in
1671 3 ft + 3.3700787 in
1672 This is arguably a bit cryptic; the ‘--verbose’ option makes clear what
1674 the output means:
1675 $ units --verbose
1677 Currency exchange rates from FloatRates (USD base) on 2019-02-20
1678 3070 units, 109 prefixes, 109 nonlinear units
1679 You have: 23 ft
1681 You want: m
1682 23 ft = 7.0104 m
1683 23 ft = (1 / 0.14264521) m
1684 You have: meter
1685 You want: ft;in
1686 meter = 3 ft + 3.3700787 in
1687 The ‘--quiet’ option suppresses the clutter displayed when ‘units’
1689 starts, as well as the prompts to the user. This option is enabled by
1690 default when you give units on the command line.
1691 $ units --quiet
1693 23 ft
1694 m
1695 * 7.0104
1696 / 0.14264521
1697 $ units 23ft m
1699 * 7.0104
1700 / 0.14264521
1701 The remaining style options allow you to display only numerical values
1703 without the tab or the multiplication and division signs, or to display
1704 just a single line showing the forward conversion:
1705 $ units --compact 23ft m
1707 7.0104
1708 0.14264521
1709 $ units --compact m 'ft;in'
1711 3;3.3700787
1712 $ units --one-line 23ft m
1714 * 7.0104
1715 $ units --one-line 23ft 1/m
1717 reciprocal conversion
1718 * 0.14264521
1719 $ units --one-line 23ft kg
1721 conformability error
1722 7.0104 m
1723 1 kg
1724 Note that when converting to a unit list, the ‘--compact’ option dis‐
1726 plays a semicolon separated list of results. Also be aware that the
1727 ‘one-line’ option doesn't live up to its name if you execute a recipro‐
1728 cal conversion or if you get a conformability error. The former case
1729 can be prevented using the ‘--strict’ option, which suppresses recipro‐
1730 cal conversions. Similarly you can suppress unit list conversion using
1731 ‘--nolists’. It is impossible to prevent the three line error output.
1732 $ units --compact --nolists m 'ft;in'
1734 Error in 'ft;in': Parse error
1735 $ units --one-line --strict 23ft 1/m
1737 The various style options can be combined appropriately. The ultimate
1739 combination is the ‘--terse’ option, which combines ‘--strict’,
1740 ‘--quiet’, ‘--one-line’, and ‘--compact’ to produce the minimal output,
1741 just a single number for regular conversions and a semicolon separated
1742 list for conversion to unit lists. This will likely be the best choice
1743 for programs that want to call ‘units’ and then process its result.
1744 $ units --terse 23ft m
1746 7.0104
1747 $ units --terse m 'ft;in'
1749 3;3.3700787
1750 $ units --terse 23ft 1/m
1752 conformability error
1753 7.0104 m
1754 1 / m
1755
1757 Units Data Files
1758 The units and prefixes that ‘units’ can convert are defined in the
1759 units data file, typically ‘/usr/share/units/definitions.units’. If
1760 you can’t find this file, run ‘units --version’ to get information on
1761 the file locations for your installation. Although you can extend or
1762 modify this data file if you have appropriate user privileges, it’s
1763 usually better to put extensions in separate files so that the defini‐
1764 tions will be preserved if you update ‘units’.
1765 You can include additional data files in the units database using the
1767 ‘!include’ command in the standard units data file. For example
1768 !include /usr/local/share/units/local.units
1770 might be appropriate for a site-wide supplemental data file. The loca‐
1772 tion of the ‘!include’ statement in the standard units data file is
1773 important; later definitions replace earlier ones, so any definitions
1774 in an included file will override definitions before the ‘!include’
1775 statement in the standard units data file. With normal invocation, no
1776 warning is given about redefinitions; to ensure that you don’t have an
1777 unintended redefinition, run ‘units -c’ after making changes to any
1778 units data file.
1779 If you want to add your own units in addition to or in place of stan‐
1781 dard or site-wide supplemental units data files, you can include them
1782 in the ‘.units’ file in your home directory. If this file exists it is
1783 read after the standard units data file, so that any definitions in
1784 this file will replace definitions of the same units in the standard
1785 data file or in files included from the standard data file. This file
1786 will not be read if any units files are specified on the command line.
1787 (Under Windows the personal units file is named ‘unitdef.units’.) Run‐
1788 ning ‘units -V’ will display the location and name of your personal
1789 units file.
1790 The ‘units’ program first tries to determine your home directory from
1792 the ‘HOME’ environment variable. On systems running Microsoft Windows,
1793 if ‘HOME’ does not exist, ‘units’ attempts to find your home directory
1794 from ‘HOMEDRIVE’, ‘HOMEPATH’ and ‘USERPROFILE’. You can specify an
1795 arbitrary file as your personal units data file with the ‘MYUNITSFILE’
1796 environment variable; if this variable exists, its value is used with‐
1797 out searching your home directory. The default units data files are
1798 described in more detail in Data Files.
1799 Defining New Units and Prefixes
1801 A unit is specified on a single line by giving its name and an equiva‐
1802 lence. Comments start with a ‘#’ character, which can appear anywhere
1803 in a line. The backslash character (‘\’) acts as a continuation char‐
1804 acter if it appears as the last character on a line, making it possible
1805 to spread definitions out over several lines if desired. A file can be
1806 included by giving the command ‘!include’ followed by the file’s name.
1807 The ‘!’ must be the first character on the line. The file will be
1808 sought in the same directory as the parent file unless you give a full
1809 path. The name of the file to be included cannot contain spaces or the
1810 comment character ‘#’.
1811 Unit names must not contain any of the operator characters ‘+’, ‘-’,
1813 ‘*’, ‘/’, ‘|’, ‘^’, ‘;’, ‘~’, the comment character ‘#’, or parenthe‐
1814 ses. They cannot begin or end with an underscore (‘_’), a comma (‘,’)
1815 or a decimal point (‘.’). The figure dash (U+2012), typographical
1816 minus (‘-’; U+2212), and en dash (‘-’; U+2013) are converted to the
1817 operator ‘-’, so none of these characters can appear in unit names.
1818 Names cannot begin with a digit, and if a name ends in a digit other
1819 than zero, the digit must be preceded by a string beginning with an
1820 underscore, and afterwards consisting only of digits, decimal points,
1821 or commas. For example, ‘foo_2’, ‘foo_2,1’, or ‘foo_3.14’ are valid
1822 names but ‘foo2’ or ‘foo_a2’ are invalid. You could define nitrous
1823 oxide as
1824 N2O nitrogen 2 + oxygen
1826 but would need to define nitrogen dioxide as
1828 NO_2 nitrogen + oxygen 2
1830 Be careful to define new units in terms of old ones so that a reduction
1832 leads to the primitive units, which are marked with ‘!’ characters.
1833 Dimensionless units are indicated by using the string ‘!dimensionless’
1834 for the unit definition.
1835 When adding new units, be sure to use the ‘-c’ option to check that the
1837 new units reduce properly. If you create a loop in the units defini‐
1838 tions, then ‘units’ will hang when invoked with the ‘-c’ option. You
1839 will need to use the ‘--check-verbose’ option, which prints out each
1840 unit as it is checked. The program will still hang, but the last unit
1841 printed will be the unit that caused the infinite loop.
1842 If you define any units that contain ‘+’ characters in their defini‐
1844 tions, carefully check them because the ‘-c’ option will not catch non-
1845 conformable sums. Be careful with the ‘-’ operator as well. When used
1846 as a binary operator, the ‘-’ character can perform addition or multi‐
1847 plication depending on the options used to invoke ‘units’. To ensure
1848 consistent behavior use ‘-’ only as a unary negation operator when
1849 writing units definitions. To multiply two units leave a space or use
1850 the ‘*’ operator with care, recalling that it has two possible prece‐
1851 dence values and may require parentheses to ensure consistent behavior.
1852 To compute the difference of ‘foo’ and ‘bar’ write ‘foo+(-bar)’ or even
1853 ‘foo+-bar’.
1854 You may wish to intentionally redefine a unit. When you do this, and
1856 use the ‘-c’ option, ‘units’ displays a warning message about the
1857 redefinition. You can suppress these warnings by redefining a unit
1858 using a ‘+’ at the beginning of the unit name. Do not include any
1859 white space between the ‘+’ and the redefined unit name.
1860 Here is an example of a short data file that defines some basic units:
1862 m ! # The meter is a primitive unit
1864 sec ! # The second is a primitive unit
1865 rad !dimensionless # A dimensionless primitive unit
1866 micro- 1e-6 # Define a prefix
1867 minute 60 sec # A minute is 60 seconds
1868 hour 60 min # An hour is 60 minutes
1869 inch 72 m # Inch defined incorrectly terms of meters
1870 ft 12 inches # The foot defined in terms of inches
1871 mile 5280 ft # And the mile
1872 +inch 0.0254 m # Correct redefinition, warning suppressed
1873 A unit that ends with a ‘-’ character is a prefix. If a prefix defini‐
1875 tion contains any ‘/’ characters, be sure they are protected by paren‐
1876 theses. If you define ‘half- 1/2’, then ‘halfmeter’ would be equiva‐
1877 lent to ‘1 / (2 meter)’.
1878 Defining Nonlinear Units
1880 Some unit conversions of interest are nonlinear; for example, tempera‐
1881 ture conversions between the Fahrenheit and Celsius scales cannot be
1882 done by simply multiplying by conversion factors.
1883 When you give a linear unit definition such as ‘inch 2.54 cm’ you are
1885 providing information that ‘units’ uses to convert values in inches
1886 into primitive units of meters. For nonlinear units, you give a func‐
1887 tional definition that provides the same information.
1888 Nonlinear units are represented using a functional notation. It is
1890 best to regard this notation not as a function call but as a way of
1891 adding units to a number, much the same way that writing a linear unit
1892 name after a number adds units to that number. Internally, nonlinear
1893 units are defined by a pair of functions that convert to and from lin‐
1894 ear units in the database, so that an eventual conversion to primitive
1895 units is possible.
1896 Here is an example nonlinear unit definition:
1898 tempF(x) units=[1;K] domain=[-459.67,) range=[0,) \
1900 (x+(-32)) degF + stdtemp ; (tempF+(-stdtemp))/degF + 32
1901 A nonlinear unit definition comprises a unit name, a formal parameter
1903 name, two functions, and optional specifications for units, the domain,
1904 and the range (the domain of the inverse function). The functions tell
1905 ‘units’ how to convert to and from the new unit. To produce valid
1906 results, the arguments of these functions need to have the correct
1907 dimensions and be within the domains for which the functions are
1908 defined.
1909 The definition begins with the unit name followed immediately (with no
1911 spaces) by a ‘(’ character. In the parentheses is the name of the for‐
1912 mal parameter. Next is an optional specification of the units required
1913 by the functions in the definition. In the example above, the
1914 ‘units=[1;K]’ specification indicates that the ‘tempF’ function
1915 requires an input argument conformable with ‘1’ (i.e., the argument is
1916 dimensionless), and that the inverse function requires an input argu‐
1917 ment conformable with ‘K’. For normal nonlinear units definition, the
1918 forward function will always take a dimensionless argument; in general,
1919 the inverse function will need units that match the quantity measured
1920 by your nonlinear unit. Specifying the units enables ‘units’ to per‐
1921 form error checking on function arguments, and also to assign units to
1922 domain and range specifications, which are described later.
1923 Next the function definitions appear. In the example above, the
1925 ‘tempF’ function is defined by
1926 tempF(x) = (x+(-32)) degF + stdtemp
1928 This gives a rule for converting ‘x’ in the units ‘tempF’ to linear
1930 units of absolute temperature, which makes it possible to convert from
1931 tempF to other units.
1932 To enable conversions to Fahrenheit, you must give a rule for the
1934 inverse conversions. The inverse will be ‘x(tempF)’ and its definition
1935 appears after a ‘;’ character. In our example, the inverse is
1936 x(tempF) = (tempF+(-stdtemp))/degF + 32
1938 This inverse definition takes an absolute temperature as its argument
1940 and converts it to the Fahrenheit temperature. The inverse can be
1941 omitted by leaving out the ‘;’ character and the inverse definition,
1942 but then conversions to the unit will not be possible. If the inverse
1943 definition is omitted, the ‘--check’ option will display a warning. It
1944 is up to you to calculate and enter the correct inverse function to
1945 obtain proper conversions; the ‘--check’ option tests the inverse at
1946 one point and prints an error if it is not valid there, but this is not
1947 a guarantee that your inverse is correct.
1948 With some definitions, the units may vary. For example, the definition
1950 square(x) x^2
1952 can have any arbitrary units, and can also take dimensionless argu‐
1954 ments. In such a case, you should not specify units. If a definition
1955 takes a root of its arguments, the definition is valid only for units
1956 that yield such a root. For example,
1957 squirt(x) sqrt(x)
1959 is valid for a dimensionless argument, and for arguments with even pow‐
1961 ers of units.
1962 Some definitions may not be valid for all real numbers. In such cases,
1964 ‘units’ can handle errors better if you specify an appropriate domain
1965 and range. You specify the domain and range as shown below:
1966 baume(d) units=[1;g/cm^3] domain=[0,130.5] range=[1,10] \
1968 (145/(145-d)) g/cm^3 ; (baume+-g/cm^3) 145 / baume
1969 In this example the domain is specified after ‘domain=’ with the end‐
1971 points given in brackets. In accord with mathematical convention,
1972 square brackets indicate a closed interval (one that includes its end‐
1973 points), and parentheses indicate an open interval (one that does not
1974 include its endpoints). An interval can be open or closed on one or
1975 both ends; an interval that is unbounded on either end is indicated by
1976 omitting the limit on that end. For example, a quantity to which deci‐
1977 bel (dB) is applied may have any value greater than zero, so the range
1978 is indicated by ‘(0,)’:
1979 decibel(x) units=[1;1] range=(0,) 10^(x/10); 10 log(decibel)
1981 If the domain or range is given, the second endpoint must be greater
1983 than the first.
1984 The domain and range specifications can appear independently and in any
1986 order along with the units specification. The values for the domain
1987 and range endpoints are attached to the units given in the units speci‐
1988 fication, and if necessary, the parameter value is adjusted for compar‐
1989 ison with the endpoints. For example, if a definition includes
1990 ‘units=[1;ft]’ and ‘range=[3,)’, the range will be taken as 3 ft to
1991 infinity. If the function is passed a parameter of ‘900 mm’, that
1992 value will be adjusted to 2.9527559 ft, which is outside the specified
1993 range. If you omit the units specification from the previous example,
1994 ‘units’ can not tell whether you intend the lower endpoint to be 3 ft
1995 or 3 microfurlongs, and can not adjust the parameter value of 900 mm
1996 for comparison. Without units, numerical values other than zero or
1997 plus or minus infinity for domain or range endpoints are meaningless,
1998 and accordingly they are not allowed. If you give other values without
1999 units, then the definition will be ignored and you will get an error
2000 message.
2001 Although the units, domain, and range specifications are optional, it’s
2003 best to give them when they are applicable; doing so allows ‘units’ to
2004 perform better error checking and give more helpful error messages.
2005 Giving the domain and range also enables the ‘--check’ option to find a
2006 point in the domain to use for its point check of your inverse defini‐
2007 tion.
2008 You can make synonyms for nonlinear units by providing both the forward
2010 and inverse functions; inverse functions can be obtained using the ‘~’
2011 operator. So to create a synonym for ‘tempF’ you could write
2012 fahrenheit(x) units=[1;K] tempF(x); ~tempF(fahrenheit)
2014 This is useful for creating a nonlinear unit definition that differs
2016 slightly from an existing definition without having to repeat the orig‐
2017 inal functions. For example,
2018 dBW(x) units=[1;W] range=[0,) dB(x) W ; ~dB(dBW/W)
2020 If you wish a synonym to refer to an existing nonlinear unit without
2022 modification, you can do so more simply by adding the synonym with
2023 appended parentheses as a new unit, with the existing nonlinear unit—
2024 without parentheses—as the definition. So to create a synonym for
2025 ‘tempF’ you could write
2026 fahrenheit() tempF
2028 The definition must be a nonlinear unit; for example, the synonym
2030 fahrenheit() meter
2032 will result in an error message when ‘units’ starts.
2034 You may occasionally wish to define a function that operates on units.
2036 This can be done using a nonlinear unit definition. For example, the
2037 definition below provides conversion between radius and the area of a
2038 circle. This definition requires a length as input and produces an
2039 area as output, as indicated by the ‘units=’ specification. Specifying
2040 the range as the nonnegative numbers can prevent cryptic error mes‐
2041 sages.
2042 circlearea(r) units=[m;m^2] range=[0,) pi r^2 ; sqrt(circlearea/pi)
2044 Defining Piecewise Linear Units
2046 Sometimes you may be interested in a piecewise linear unit such as many
2047 wire gauges. Piecewise linear units can be defined by specifying con‐
2048 versions to linear units on a list of points. Conversion at other
2049 points will be done by linear interpolation. A partial definition of
2050 zinc gauge is
2051 zincgauge[in] 1 0.002, 10 0.02, 15 0.04, 19 0.06, 23 0.1
2053 In this example, ‘zincgauge’ is the name of the piecewise linear unit.
2055 The definition of such a unit is indicated by the embedded ‘[’ charac‐
2056 ter. After the bracket, you should indicate the units to be attached
2057 to the numbers in the table. No spaces can appear before the ‘]’ char‐
2058 acter, so a definition like ‘foo[kg meters]’ is invalid; instead write
2059 ‘foo[kg*meters]’. The definition of the unit consists of a list of
2060 pairs optionally separated by commas. This list defines a function for
2061 converting from the piecewise linear unit to linear units. The first
2062 item in each pair is the function argument; the second item is the
2063 value of the function at that argument (in the units specified in
2064 brackets). In this example, we define ‘zincgauge’ at five points. For
2065 example, we set ‘zincgauge(1)’ equal to ‘0.002 in’. Definitions like
2066 this may be more readable if written using continuation characters
2067 as
2068 zincgauge[in] \
2070 1 0.002 \
2071 10 0.02 \
2072 15 0.04 \
2073 19 0.06 \
2074 23 0.1
2075 With the preceding definition, the following conversion can be per‐
2077 formed:
2078 You have: zincgauge(10)
2080 You want: in
2081 * 0.02
2082 / 50
2083 You have: .01 inch
2084 You want: zincgauge
2085 5
2086 If you define a piecewise linear unit that is not strictly monotonic,
2088 then the inverse will not be well defined. If the inverse is requested
2089 for such a unit, ‘units’ will return the smallest inverse.
2090 After adding nonlinear units definitions, you should normally run
2092 ‘units --check’ to check for errors. If the ‘units’ keyword is not
2093 given, the ‘--check’ option checks a nonlinear unit definition using a
2094 dimensionless argument, and then checks using an arbitrary combination
2095 of units, as well as the square and cube of that combination; a warning
2096 is given if any of these tests fail. For example,
2097 Warning: function 'squirt(x)' defined as 'sqrt(x)'
2099 failed for some test inputs:
2100 squirt(7(kg K)^1): Unit not a root
2101 squirt(7(kg K)^3): Unit not a root
2102 Running ‘units --check’ will print a warning if a non-monotonic piece‐
2104 wise linear unit is encountered. For example, the relationship between
2105 ANSI coated abrasive designation and mean particle size is non-mono‐
2106 tonic in the vicinity of 800 grit:
2107 ansicoated[micron] \
2109 . . .
2110 600 10.55 \
2111 800 11.5 \
2112 1000 9.5 \
2113 Running ‘units --check’ would give the error message
2115 Table 'ansicoated' lacks unique inverse around entry 800
2117 Although the inverse is not well defined in this region, it’s not
2119 really an error. Viewing such error messages can be tedious, and if
2120 there are enough of them, they can distract from true errors. Error
2121 checking for nonlinear unit definitions can be suppressed by giving the
2122 ‘noerror’ keyword; for the examples above, this could be done as
2123 squirt(x) noerror domain=[0,) range=[0,) sqrt(x); squirt^2
2125 ansicoated[micron] noerror \
2126 . . .
2127 Use the ‘noerror’ keyword with caution. The safest approach after
2129 adding a nonlinear unit definition is to run ‘units --check’ and con‐
2130 firm that there are no actual errors before adding the ‘noerror’ key‐
2131 word.
2132 Defining Unit List Aliases
2134 Unit list aliases are treated differently from unit definitions,
2135 because they are a data entry shorthand rather than a true definition
2136 for a new unit. A unit list alias definition begins with ‘!unitlist’
2137 and includes the alias and the definition; for example, the aliases
2138 included in the standard units data file are
2139 !unitlist hms hr;min;sec
2141 !unitlist time year;day;hr;min;sec
2142 !unitlist dms deg;arcmin;arcsec
2143 !unitlist ftin ft;in;1|8 in
2144 !unitlist usvol cup;3|4 cup;2|3 cup;1|2 cup;1|3 cup;1|4 cup;\
2145 tbsp;tsp;1|2 tsp;1|4 tsp;1|8 tsp
2146 Unit list aliases are only for unit lists, so the definition must
2148 include a ‘;’. Unit list aliases can never be combined with units or
2149 other unit list aliases, so the definition of ‘time’ shown above could
2150 not have been shortened to ‘year;day;hms’.
2151 As usual, be sure to run ‘units --check’ to ensure that the units
2153 listed in unit list aliases are conformable.
2154
2156 By default, ‘units’ shows results to eight significant digits. You can
2157 change this with the ‘--exponential’, ‘--digits’, and ‘--output-format’
2158 options. The first sets an exponential format (i.e., scientific nota‐
2159 tion) like that used in the original Unix ‘units’ program, the second
2160 allows you to specify a different number of significant digits, and the
2161 last allows you to control the output appearance using the format for
2162 the ‘printf()’ function in the C programming language. If you only
2163 want to change the number of significant digits or specify exponential
2164 format type, use the ‘--digits’ and ‘--exponential’ options. The
2165 ‘--output-format’ option affords the greatest control of the output
2166 appearance, but requires at least rudimentary knowledge of the
2167 ‘printf()’ format syntax. See Invoking Units for descriptions of these
2168 options.
2169 Format Specification
2171 The format specification recognized with the ‘--output-format’ option
2172 is a subset of that for ‘printf()’. The format specification has the
2173 form ‘%’[flags][width][‘.’precision]type; it must begin with ‘%’, and
2174 must end with a floating-point type specifier: ‘g’ or ‘G’ to specify
2175 the number of significant digits, ‘e’ or ‘E’ for scientific notation,
2176 and ‘f’ for fixed-point decimal. The ISO C99 standard added the ‘F’
2177 type for fixed-point decimal and the ‘a’ and ‘A’ types for hexadecimal
2178 floating point; these types are allowed with compilers that support
2179 them. Type length modifiers (e.g., ‘L’ to indicate a long double) are
2180 inapplicable and are not allowed.
2181 The default format for ‘units’ is ‘%.8g’; for greater precision, you
2183 could specify ‘-o %.15g’. The ‘g’ and ‘G’ format types use exponential
2184 format whenever the exponent would be less than -4, so the value
2185 0.000013 displays as ‘1.3e-005’. These types also use exponential
2186 notation when the exponent is greater than or equal to the precision,
2187 so with the default format, the value 5e7 displays as ‘50000000’ and
2188 the value 5e8 displays as ‘5e+008’. If you prefer fixed-point display,
2189 you might specify ‘-o %.8f’; however, small numbers will display very
2190 few significant digits, and values less than 0.5e-8 will show nothing
2191 but zeros.
2192 The format specification may include one or more optional flags: ‘+’,
2194 ‘ ’ (space), ‘#’, ‘-’, or ‘0’ (the digit zero). The digit-grouping
2195 flag ‘'’ is allowed with compilers that support it. Flags are followed
2196 by an optional value for the minimum field width, and an optional pre‐
2197 cision specification that begins with a period (e.g., ‘.6’). The field
2198 width includes the digits, decimal point, the exponent, thousands sepa‐
2199 rators (with the digit-grouping flag), and the sign if any of these are
2200 shown.
2201 Flags
2203 The ‘+’ flag causes the output to have a sign (‘+’ or ‘-’). The space
2204 flag ‘ ’ is similar to the ‘+’ flag, except that when the value is pos‐
2205 itive, it is prefixed with a space rather than a plus sign; this flag
2206 is ignored if the ‘+’ flag is also given. The ‘+’ or ‘ ’ flag could be
2207 useful if conversions might include positive and negative results, and
2208 you wanted to align the decimal points in exponential notation. The
2209 ‘#’ flag causes the output value to contain a decimal point in all
2210 cases; by default, the output contains a decimal point only if there
2211 are digits (which can be trailing zeros) to the right of the point.
2212 With the ‘g’ or ‘G’ types, the ‘#’ flag also prevents the suppression
2213 of trailing zeros. The digit-grouping flag ‘'’ shows a thousands sepa‐
2214 rator in digits to the left of the decimal point. This can be useful
2215 when displaying large numbers in fixed-point decimal; for example, with
2216 the format ‘%f’,
2217 You have: mile
2219 You want: microfurlong
2220 * 8000000.000000
2221 / 0.000000
2222 the magnitude of the first result may not be immediately obvious with‐
2224 out counting the digits to the left of the decimal point. If the thou‐
2225 sands separator is the comma (‘,’), the output with the format ‘%'f’
2226 might be
2227 You have: mile
2229 You want: microfurlong
2230 * 8,000,000.000000
2231 / 0.000000
2232 making the magnitude readily apparent. Unfortunately, few compilers
2234 support the digit-grouping flag.
2235 With the ‘-’ flag, the output value is left aligned within the speci‐
2237 fied field width. If a field width greater than needed to show the
2238 output value is specified, the ‘0’ (zero) flag causes the output value
2239 to be left padded with zeros until the specified field width is
2240 reached; for example, with the format ‘%011.6f’,
2241 You have: troypound
2243 You want: grain
2244 * 5760.000000
2245 / 0000.000174
2246 The ‘0’ flag has no effect if the ‘-’ (left align) flag is given.
2248 Field Width
2250 By default, the output value is left aligned and shown with the minimum
2251 width necessary for the specified (or default) precision. If a field
2252 width greater than this is specified, the value shown is right aligned,
2253 and padded on the left with enough spaces to provide the specified
2254 field width. A width specification is typically used with fixed-point
2255 decimal to have columns of numbers align at the decimal point; this
2256 arguably is less useful with ‘units’ than with long columnar output,
2257 but it may nonetheless assist in quickly assessing the relative magni‐
2258 tudes of results. For example, with the format ‘%12.6f’,
2259 You have: km
2261 You want: in
2262 * 39370.078740
2263 / 0.000025
2264 You have: km
2265 You want: rod
2266 * 198.838782
2267 / 0.005029
2268 You have: km
2269 You want: furlong
2270 * 4.970970
2271 / 0.201168
2272 Precision
2274 The meaning of “precision” depends on the format type. With ‘g’ or
2275 ‘G’, it specifies the number of significant digits (like the ‘--digits’
2276 option); with ‘e’, ‘E’, ‘f’, or ‘F’, it specifies the maximum number of
2277 digits to be shown after the decimal point.
2278 With the ‘g’ and ‘G’ format types, trailing zeros are suppressed, so
2280 the results may sometimes have fewer digits than the specified preci‐
2281 sion (as indicated above, the ‘#’ flag causes trailing zeros to be dis‐
2282 played).
2283 The default precision is 6, so ‘%g’ is equivalent to ‘%.6g’, and would
2285 show the output to six significant digits. Similarly, ‘%e’ or ‘%f’
2286 would show the output with six digits after the decimal point.
2287 The C ‘printf()’ function allows a precision of arbitrary size, whether
2289 or not all of the digits are meaningful. With most compilers, the max‐
2290 imum internal precision with ‘units’ is 15 decimal digits (or 13 hexa‐
2291 decimal digits). With the ‘--digits’ option, you are limited to the
2292 maximum internal precision; with the ‘--output-format’ option, you may
2293 specify a precision greater than this, but it may not be meaningful.
2294 In some cases, specifying excess precision can result in rounding arti‐
2295 facts. For example, a pound is exactly 7000 grains, but with the for‐
2296 mat ‘%.18g’, the output might be
2297 You have: pound
2299 You want: grain
2300 * 6999.9999999999991
2301 / 0.00014285714285714287
2302 With the format ‘%.25g’ you might get the following:
2304 You have: 1/3
2306 You want:
2307 Definition: 0.333333333333333314829616256247
2308 In this case the displayed value includes a series of digits that rep‐
2310 resent the underlying binary floating-point approximation to 1/3 but
2311 are not meaningful for the desired computation. In general, the result
2312 with excess precision is system dependent. The precision affects only
2313 the display of numbers; if a result relies on physical constants that
2314 are not known to the specified precision, the number of physically
2315 meaningful digits may be less than the number of digits shown.
2316 See the documentation for ‘printf()’ for more detailed descriptions of
2318 the format specification.
2319 The ‘--output-format’ option is incompatible with the ‘--exponential’
2321 or ‘--digits’ options; if the former is given in combination with
2322 either of the latter, the format is controlled by the last option
2323 given.
2324
2326 Some units have different values in different locations. The localiza‐
2327 tion feature accommodates this by allowing a units data file to specify
2328 definitions that depend on the user’s locale.
2329 Locale
2331 A locale is a subset of a user’s environment that indicates the user’s
2332 language and country, and some attendant preferences, such as the for‐
2333 matting of dates. The ‘units’ program attempts to determine the locale
2334 from the POSIX setlocale function; if this cannot be done, ‘units’
2335 examines the environment variables ‘LC_CTYPE’ and ‘LANG’. On POSIX
2336 systems, a locale is of the form language‘_’country, where language is
2337 the two-character code from ISO 639-1 and country is the two-character
2338 code from ISO 3166-1; language is lower case and country is upper case.
2339 For example, the POSIX locale for the United Kingdom is ‘en_GB’.
2340 On systems running Microsoft Windows, the value returned by setlocale()
2342 is different from that on POSIX systems; ‘units’ attempts to map the
2343 Windows value to a POSIX value by means of a table in the file
2344 ‘locale_map.txt’ in the same directory as the other data files. The
2345 file includes entries for many combinations of language and country,
2346 and can be extended to include other combinations. The
2347 ‘locale_map.txt’ file comprises two tab-separated columns; each entry
2348 is of the form
2349 Windows-locale POSIX-locale
2351 where POSIX-locale is as described above, and Windows-locale typically
2353 spells out both the language and country. For example, the entry for
2354 the United States is
2355 English_United States en_US
2357 You can force ‘units’ to run in a desired locale by using the ‘-l’
2359 option.
2360 In order to create unit definitions for a particular locale you begin a
2362 block of definitions in a unit datafile with ‘!locale’ followed by a
2363 locale name. The ‘!’ must be the first character on the line. The
2364 ‘units’ program reads the following definitions only if the current
2365 locale matches. You end the block of localized units with
2366 ‘!endlocale’. Here is an example, which defines the British gallon.
2367 !locale en_GB
2369 gallon 4.54609 liter
2370 !endlocale
2371 Additional Localization
2373 Sometimes the locale isn’t sufficient to determine unit preferences.
2374 There could be regional preferences, or a company could have specific
2375 preferences. Though probably uncommon, such differences could arise
2376 with the choice of English customary units outside of English-speaking
2377 countries. To address this, ‘units’ allows specifying definitions that
2378 depend on environment variable settings. The environment variables can
2379 be controled based on the current locale, or the user can set them to
2380 force a particular group of definitions.
2381 A conditional block of definitions in a units data file begins with
2383 either ‘!var’ or ‘!varnot’ following by an environment variable name
2384 and then a space separated list of values. The leading ‘!’ must appear
2385 in the first column of a units data file, and the conditional block is
2386 terminated by ‘!endvar’. Definitions in blocks beginning with ‘!var’
2387 are executed only if the environment variable is exactly equal to one
2388 of the listed values. Definitions in blocks beginning with ‘!varnot’
2389 are executed only if the environment variable does not equal any of the
2390 list values.
2391 The inch has long been a customary measure of length in many places.
2393 The word comes from the Latin uncia meaning “one twelfth,” referring to
2394 its relationship with the foot. By the 20th century, the inch was
2395 officially defined in English-speaking countries relative to the yard,
2396 but until 1959, the yard differed slightly among those countries. In
2397 France the customary inch, which was displaced in 1799 by the meter,
2398 had a different length based on a french foot. These customary defini‐
2399 tions could be accommodated as follows:
2400 !var INCH_UNIT usa
2402 yard 3600|3937 m
2403 !endvar
2404 !var INCH_UNIT canada
2405 yard 0.9144 meter
2406 !endvar
2407 !var INCH_UNIT uk
2408 yard 0.91439841 meter
2409 !endvar
2410 !var INCH_UNIT canada uk usa
2411 foot 1|3 yard
2412 inch 1|12 foot
2413 !endvar
2414 !var INCH_UNIT france
2415 foot 144|443.296 m
2416 inch 1|12 foot
2417 line 1|12 inch
2418 !endvar
2419 !varnot INCH_UNIT usa uk france canada
2420 !message Unknown value for INCH_UNIT
2421 !endvar
2422 When ‘units’ reads the above definitions it will check the environment
2424 variable ‘INCH_UNIT’ and load only the definitions for the appropriate
2425 section. If ‘INCH_UNIT’ is unset or is not set to one of the four val‐
2426 ues listed, then ‘units’ will run the last block. In this case that
2427 block uses the ‘!message’ command to display a warning message. Alter‐
2428 natively that block could set default values.
2429 In order to create default values that are overridden by user settings
2431 the data file can use the ‘!set’ command, which sets an environment
2432 variable only if it is not already set; these settings are only for
2433 the current ‘units’ invocation and do not persist. So if the example
2434 above were preceded by ‘!set INCH_UNIT france’, then this would make
2435 ‘france’ the default value for ‘INCH_UNIT’. If the user had set the
2436 variable in the environment before invoking ‘units’, then ‘units’ would
2437 use the user’s value.
2438 To link these settings to the user’s locale you combine the ‘!set’ com‐
2440 mand with the ‘!locale’ command. If you wanted to combine the above
2441 example with suitable locales you could do by preceding the above defi‐
2442 nition with the following:
2443 !locale en_US
2445 !set INCH_UNIT usa
2446 !endlocale
2447 !locale en_GB
2448 !set INCH_UNIT uk
2449 !endlocale
2450 !locale en_CA
2451 !set INCH_UNIT canada
2452 !endlocale
2453 !locale fr_FR
2454 !set INCH_UNIT france
2455 !endlocale
2456 !set INCH_UNIT france
2457 These definitions set the overall default for ‘INCH_UNIT’ to ‘france’
2459 and set default values for four locales appropriately. The overall
2460 default setting comes last so that it only applies when ‘INCH_UNIT’ was
2461 not set by one of the other commands or by the user.
2462 If the variable given after ‘!var’ or ‘!varnot’ is undefined, then
2464 ‘units’ prints an error message and ignores the definitions that fol‐
2465 low. Use ‘!set’ to create defaults to prevent this situation from
2466 arising. The ‘-c’ option only checks the definitions that are active
2467 for the current environment and locale, so when adding new definitions
2468 take care to check that all cases give rise to a well defined set of
2469 definitions.
2470
2472 The ‘units’ program uses the following environment variables:
2473 HOME Specifies the location of your home directory; it is used by
2475 ‘units’ to find a personal units data file ‘.units’. On systems
2476 running Microsoft Windows, the file is ‘unitdef.units’, and if
2477 ‘HOME’ does not exist, ‘units’ tries to determine your home
2478 directory from the ‘HOMEDRIVE’ and ‘HOMEPATH’ environment vari‐
2479 ables; if these variables do not exist, units finally tries
2480 ‘USERPROFILE’—typically ‘C:\Users\username’ (Windows Vista and
2481 Windows 7) or ‘C:\Documents and Settings\username’ (Windows XP).
2482 LC_CTYPE, LANG
2484 Checked to determine the locale if ‘units’ cannot obtain it from
2485 the operating system. Sections of the standard units data file
2486 are specific to certain locales.
2487 MYUNITSFILE
2489 Specifies your personal units data file. If this variable
2490 exists, ‘units’ uses its value rather than searching your home
2491 directory for ‘.units’. The personal units file will not be
2492 loaded if any data files are given using the ‘-f’ option.
2493 PAGER Specifies the pager to use for help and for displaying the con‐
2495 formable units. The help function browses the units database
2496 and calls the pager using the ‘+n’n syntax for specifying a line
2497 number. The default pager is ‘more’; ‘PAGER’ can be used to
2498 specify alternatives such as ‘less’, ‘pg’, ‘emacs’, or ‘vi’.
2499 UNITS_ENGLISH
2501 Set to either ‘US’ or ‘GB’ to choose United States or British
2502 volume definitions, overriding the default from your locale.
2503 UNITSFILE
2505 Specifies the units data file to use (instead of the default).
2506 You can only specify a single units data file using this envi‐
2507 ronment variable. If units data files are given using the ‘-f’
2508 option, the file specified by ‘UNITSFILE’ will be not be loaded
2509 unless the ‘-f’ option is given with the empty string
2510 (‘units -f ""’).
2511 UNITSLOCALEMAP
2513 Windows only; this variable has no effect on Unix-like systems.
2514 Specifies the units locale map file to use (instead of the
2515 default). This variable seldom needs to be set, but you can use
2516 it to ensure that the locale map file will be found if you spec‐
2517 ify a location for the units data file using either the ‘-f’
2518 option or the ‘UNITSFILE’ environment variable, and that loca‐
2519 tion does not also contain the locale map file.
2520 UNITS_SYSTEM
2522 This environment variable is used in the standard data file to
2523 select CGS measurement systems. Currently supported systems are
2524 ‘esu’, ‘emu’, ‘gauss[ian]’, and ‘si’. The default is ‘si’.
2525
2527 The ‘units’ program uses two default data files: ‘definitions.units’
2528 and ‘currency.units’. The program can also use an optional personal
2529 units data file ‘.units’ (‘unitdef.units’ under Windows) located in the
2530 user’s home directory. The personal units data file is described in
2531 more detail in Units Data Files.
2532 On Unix-like systems, the data files are typically located in
2534 ‘/usr/share/units’ if ‘units’ is provided with the operating system, or
2535 in ‘/usr/local/share/units’ if ‘units’ is compiled from the source dis‐
2536 tribution. Note that the currency file ‘currency.units’ is a symbolic
2537 link to another location.
2538 On systems running Microsoft Windows, the files may be in the same
2540 locations if Unix-like commands are available, a Unix-like file struc‐
2541 ture is present (e.g., ‘C:/usr/local’), and ‘units’ is compiled from
2542 the source distribution. If Unix-like commands are not available, a
2543 more common location is ‘C:\Program Files (x86)\GNU\units’ (for 64-bit
2544 Windows installations) or ‘C:\Program Files\GNU\units’ (for 32-bit
2545 installations).
2546 If ‘units’ is obtained from the GNU Win32 Project
2548 (http://gnuwin32.sourceforge.net/), the files are commonly in
2549 ‘C:\Program Files\GnuWin32\share\units’.
2550 If the default units data file is not an absolute pathname, ‘units’
2552 will look for the file in the directory that contains the ‘units’ pro‐
2553 gram; if the file is not found there, ‘units’ will look in a directory
2554 ‘../share/units’ relative to the directory with the ‘units’ program.
2555 You can determine the location of the files by running
2557 ‘units --version’. Running ‘units --info’ will give you additional
2558 information about the files, how ‘units’ will attempt to find them, and
2559 the status of the related environment variables.
2560
2562 The standard units data file is in Unicode, using UTF-8 encoding. Most
2563 definitions use only ASCII characters (i.e., code points U+0000 through
2564 U+007F); definitions using non-ASCII characters appear in blocks begin‐
2565 ning with ‘!utf8’ and ending with ‘!endutf8’.
2566 The non-ASCII definitions are loaded only if the platform and the
2568 locale support UTF-8. Platform support is determined when ‘units’ is
2569 compiled; the locale is checked at every invocation of ‘units’. To see
2570 if your version of ‘units’ includes Unicode support, invoke the program
2571 with the ‘--version’ option.
2572 When Unicode support is available, ‘units’ checks every line within
2574 UTF-8 blocks in all of the units data files for invalid or non-printing
2575 UTF-8 sequences; if such sequences occur, ‘units’ ignores the entire
2576 line. In addition to checking validity, ‘units’ determines the display
2577 width of non-ASCII characters to ensure proper positioning of the
2578 pointer in some error messages and to align columns for the ‘search’
2579 and ‘?’ commands.
2580 As of early 2019, Microsoft Windows provides limited support for UTF-8
2582 in console applications, and accordingly, ‘units’ does not support Uni‐
2583 code on Windows. The UTF-16 and UTF-32 encodings are not supported on
2584 any platforms.
2585 If Unicode support is available and definitions that contain non-ASCII
2587 UTF-8 characters are added to a units data file, those definitions
2588 should be enclosed within ‘!utf8’ ... ‘!endutf8’ to ensure that they
2589 are only loaded when Unicode support is available. As usual, the ‘!’
2590 must appear as the first character on the line. As discussed in Units
2591 Data Files, it’s usually best to put such definitions in supplemental
2592 data files linked by an ‘!include’ command or in a personal units data
2593 file.
2594 When Unicode support is not available, ‘units’ makes no assumptions
2596 about character encoding, except that characters in the range 00-7F
2597 hexadecimal correspond to ASCII encoding. Non-ASCII characters are
2598 simply sequences of bytes, and have no special meanings; for defini‐
2599 tions in supplementary units data files, you can use any encoding con‐
2600 sistent with this assumption. For example, if you wish to use non-
2601 ASCII characters in definitions when running ‘units’ under Windows, you
2602 can use a character set such as Windows “ANSI” (code page 1252 in the
2603 US and Western Europe); if this is done, the console code page must be
2604 set to the same encoding for the characters to display properly. You
2605 can even use UTF-8, though some messages may be improperly aligned, and
2606 ‘units’ will not detect invalid UTF-8 sequences. If you use UTF-8
2607 encoding when Unicode support is not available, you should place any
2608 definitions with non-ASCII characters outside ‘!utf8’ ... ‘!endutf8’
2609 blocks—otherwise, they will be ignored.
2610 Typeset material other than code examples usually uses the Unicode
2612 minus (U+2212) rather than the ASCII hyphen-minus operator (U+002D)
2613 used in ‘units’; the figure dash (U+2012) and en dash (U+2013) are also
2614 occasionally used. To allow such material to be copied and pasted for
2615 interactive use or in units data files, ‘units’ converts these charac‐
2616 ters to U+002D before further processing. Because of this, none of
2617 these characters can appear in unit names.
2618
2620 If the ‘readline’ package has been compiled in, then when ‘units’ is
2621 used interactively, numerous command line editing features are avail‐
2622 able. To check if your version of ‘units’ includes ‘readline’, invoke
2623 the program with the ‘--version’ option.
2624 For complete information about ‘readline’, consult the documentation
2626 for the ‘readline’ package. Without any configuration, ‘units’ will
2627 allow editing in the style of emacs. Of particular use with ‘units’
2628 are the completion commands.
2629 If you type a few characters and then hit ESC followed by ‘?’, then
2631 ‘units’ will display a list of all the units that start with the char‐
2632 acters typed. For example, if you type ‘metr’ and then request comple‐
2633 tion, you will see something like this:
2634 You have: metr
2636 metre metriccup metrichorsepower metrictenth
2637 metretes metricfifth metricounce metricton
2638 metriccarat metricgrain metricquart metricyarncount
2639 You have: metr
2640 If there is a unique way to complete a unit name, you can hit the TAB
2642 key and ‘units’ will provide the rest of the unit name. If ‘units’
2643 beeps, it means that there is no unique completion. Pressing the TAB
2644 key a second time will print the list of all completions.
2645 The readline library also keeps a history of the values you enter. You
2647 can move through this history using the up and down arrows. The his‐
2648 tory is saved to the file ‘.units_history’ in your home directory so
2649 that it will persist across multiple ‘units’ invocations. If you wish
2650 to keep work for a certain project separate you can change the history
2651 filename using the ‘--history’ option. You could, for example, make an
2652 alias for ‘units’ to ‘units --history .units_history’ so that ‘units’
2653 would save separate history in the current directory. The length of
2654 each history file is limited to 5000 lines. Note also that if you run
2655 several concurrent copies of ‘units’ each one will save its new history
2656 to the history file upon exit.
2657
2659 The units program database includes currency exchange rates and prices
2660 for some precious metals. Of course, these values change over time,
2661 sometimes very rapidly, and ‘units’ cannot provide real-time values.
2662 To update the exchange rates, run ‘units_cur’, which rewrites the file
2663 containing the currency rates, typically ‘/var/lib/units/
2664 currency.units’ or ‘/usr/local/com/units/currency.units’ on a Unix-like
2665 system or ‘C:\Program Files (x86)\GNU\units\definitions.units’ on a
2666 Windows system.
2667 This program requires Python (https://www.python.org); either version 2
2669 or 3 will work. The program must be run with suitable permissions to
2670 write the file. To keep the rates updated automatically, run it using
2671 a cron job on a Unix-like system, or a similar scheduling program on a
2672 different system.
2673 Reliable free sources of currency exchange rates have been annoyingly
2675 ephemeral. The program currently supports several sources:
2676 • FloatRates (https://www/floatrates.com). The US dollar (‘USD’) is
2678 the default base currency. You can change the base currency with
2679 the ‘-b’ option described below. Allowable base currencies are
2680 listed on the FloatRates website. Exchange rates update daily.
2681 • The European Central Bank (https://www.ecb.europa.eu). The base
2683 currency is always the euro (‘EUR’). Exchange rates update daily.
2684 This source offers a more limited list of currencies than the oth‐
2685 ers.
2686 • Fixer (https://fixer.io). Registration for a free API key is
2688 required. With a free API key, base currency is the euro; exchange
2689 rates are updated hourly, the service has a limit of 1,000 API
2690 calls per month, and SSL encryption (https protocol) is not avail‐
2691 able. Most of these restrictions are eliminated or reduced with
2692 paid plans.
2693 • open exchange rates (https://openexchangerates.org). Registration
2695 for a free API key is required. With a free API key, the base cur‐
2696 rency is the US dollar; exchange rates are updated hourly, and
2697 there is a limit of 1,000 API calls per month. Most of these
2698 restrictions are eliminated or reduced with paid plans.
2699 The default source is FloatRates; you can select a different one using
2701 ‘-s’ option described below.
2702 Precious metals pricing is obtained from Packetizer (www.packe‐
2704 tizer.com). This site updates once per day.
2705 You invoke ‘units_cur’ like this:
2707 units_cur [options] [outfile]
2709 By default, the output is written to the default currency file
2711 described above; this is usually what you want, because this is where
2712 ‘units’ looks for the file. If you wish, you can specify a different
2713 filename on the command line and ‘units_cur’ will write the data to
2714 that file. If you give ‘-’ for the file it will write to standard out‐
2715 put.
2716 The following options are available:
2718 -h, --help
2720 Print a summary of the options for ‘units_cur’.
2721 -V, --version
2723 Print the ‘units_cur’ version number.
2724 -v, --verbose
2726 Give slightly more verbose output when attempting to update cur‐
2727 rency exchange rates.
2728 -s source, --source source
2730 Specify the source for currency exchange rates; currently sup‐
2731 ported values are ‘floatrates’ (for FloatRates), ‘eubank’ (for
2732 the European Central Bank), ‘fixer’ (for Fixer), and
2733 ‘openexchangerates’ (for open exchange rates); the last two
2734 require an API key to be given with the ‘-k’ option.
2735 -b base, --base base
2737 Set the base currency (when allowed by the site providing the
2738 data). base should be a 3-letter ISO currency code, e.g.,
2739 ‘USD’. The specified currency will be the primitive currency
2740 unit used by ‘units’. You may find it convenient to specify
2741 your local currency. Conversions may be more accurate and you
2742 will be able to convert to your currency by simply hitting Enter
2743 at the ‘You want:’ prompt. This option is ignored if the source
2744 does not allow specifying the base currency. (Currently only
2745 floatrates supports this option.)
2746 -k key, --key key
2748 Set the API key to key for sources that require it.
2749
2751 unit definition
2752 Define a regular unit.
2753 prefix- definition
2755 Define a prefix.
2756 funcname(var) noerror units=[in-units,out-units] domain=[x1,x2]
2758 range=[y1,y2] definition(var) ; inverse(funcname)
2759 Define a nonlinear unit or unit function. The four optional
2760 keywords ‘noerror’, ‘units=’, ‘range=’ and ‘domain=’ can appear
2761 in any order. The definition of the inverse is optional.
2762 tabname[out-units] noerror pair-list
2764 Define a piecewise linear unit. The pair list gives the points
2765 on the table listed in ascending order. The ‘noerror’ keyword
2766 is optional.
2767 !endlocale
2769 End a block of definitions beginning with ‘!locale’
2770 !endutf8
2772 End a block of definitions begun with ‘!utf8’
2773 !endvar
2775 End a block of definitions begun with ‘!var’ or ‘!varnot’
2776 !include file
2778 Include the specified file.
2779 !locale value
2781 Load the following definitions only of the locale is set to
2782 value.
2783 !message text
2785 Display text when the database is read unless the quiet option
2786 (‘-q’) is enabled. If you omit text, then units will display a
2787 blank line. Messages will also appear in the log file.
2788 !prompt text
2790 Prefix the ‘You have:’ prompt with the specified text. If you
2791 omit text, then any existing prefix is canceled.
2792 !set variable value
2794 Sets the environment variable, variable, to the specified value
2795 only if it is not already set.
2796 !unitlist alias definition
2798 Define a unit list alias.
2799 !utf8 Load the following definitions only if ‘units’ is running with
2801 UTF-8 enabled.
2802 !var envar value-list
2804 Load the block of definitions that follows only if the environ‐
2805 ment variable envar is set to one of the values listed in the
2806 space-separated value list. If envar is not set, ‘units’ prints
2807 an error message and ignores the block of definitions.
2808 !varnot envar value-list
2810 Load the block of definitions that follows only if the environ‐
2811 ment variable envar is set to value that is not listed in the
2812 space-separated value list. If envar is not set, ‘units’ prints
2813 an error message and ignores the block of definitions.
2814
2816 /usr/share/units/definitions.units — the standard units data file
2817
2819 units was written by Adrian Mariano
2820 19 March 2019 UNITS(1)