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 If the conversion is successful, then 'units' will return success
206 (zero) to the calling environment. If you enter non-conformable units
207 then 'units' will print a message giving the reduced form of each unit
208 and it will return failure (nonzero) to the calling environment.
209 When you invoke 'units' with only one argument, it will print out the
211 definition of the specified unit. It will return failure if the unit
212 is not defined and success if the unit is defined.
213
215 The conversion information is read from a units data file that is
216 called 'definitions.units' and is usually located in the
217 '/usr/share/units' directory. If you invoke 'units' with the '-V'
218 option, it will print the location of this file. The default file
219 includes definitions for all familiar units, abbreviations and metric
220 prefixes. It also includes many obscure or archaic units. Many common
221 spelled-out numbers (e.g., 'seventeen') are recognized.
222 Many constants of nature are defined, including these:
224 pi ratio of circumference to diameter
226 c speed of light
227 e charge on an electron
228 force acceleration of gravity
229 mole Avogadro's number
230 water pressure per unit height of water
231 Hg pressure per unit height of mercury
232 au astronomical unit
233 k Boltzman's constant
234 mu0 permeability of vacuum
235 epsilon0 permittivity of vacuum
236 G Gravitational constant
237 mach speed of sound
238 The standard data file includes atomic masses for all of the elements
240 and numerous other constants. Also included are the densities of vari‐
241 ous ingredients used in baking so that '2 cups flour_sifted' can be
242 converted to 'grams'. This is not an exhaustive list. Consult the
243 units data file to see the complete list, or to see the definitions
244 that are used.
245 The 'pound' is a unit of mass. To get force, multiply by the force
247 conversion unit 'force' or use the shorthand 'lbf'. (Note that 'g' is
248 already taken as the standard abbreviation for the gram.) The unit
249 'ounce' is also a unit of mass. The fluid ounce is 'fluidounce' or
250 'floz'. When British capacity units differ from their US counterparts,
251 such as the British Imperial gallon, the unit is defined both ways with
252 'br' and 'us' prefixes. Your locale settings will determine the value
253 of the unprefixed unit. Currency is prefixed with its country name:
254 'belgiumfranc', 'britainpound'.
255 When searching for a unit, if the specified string does not appear
257 exactly as a unit name, then the 'units' program will try to remove a
258 trailing 's', 'es'. Next units will replace a trailing 'ies' with 'y'.
259 If that fails, 'units' will check for a prefix. The database includes
260 all of the standard metric prefixes. Only one prefix is permitted per
261 unit, so 'micromicrofarad' will fail. However, prefixes can appear
262 alone with no unit following them, so 'micro*microfarad' will work, as
263 will 'micro microfarad'.
264 To find out which units and prefixes are available, read the standard
266 units data file, which is extensively annotated.
267 English Customary Units
269 English customary units differ in various ways in different regions.
270 In Britain a complex system of volume measurements featured different
271 gallons for different materials such as a wine gallon and ale gallon
272 that different by twenty percent. This complexity was swept away in
273 1824 by a reform that created an entirely new gallon, the British Impe‐
274 rial gallon defined as the volume occupied by ten pounds of water.
275 Meanwhile in the USA the gallon is derived from the 1707 Winchester
276 wine gallon, which is 231 cubic inches. These gallons differ by about
277 twenty percent. By default if 'units' runs in the 'en_GB' locale you
278 will get the British volume measures. If it runs in the 'en_US' locale
279 you will get the US volume measures. In other locales the default val‐
280 ues are the US definitions. If you wish to force different definitions
281 then set the environment variable 'UNITS_ENGLISH' to either 'US' or
282 'GB' to set the desired definitions independent of the locale.
283 Before 1959, the value of a yard (and other units of measure defined in
285 terms of it) differed slightly among English-speaking countries. In
286 1959, Australia, Canada, New Zealand, the United Kingdom, the United
287 States, and South Africa adopted the Canadian value of 1 yard =
288 0.9144 m (exactly), which was approximately halfway between the values
289 used by the UK and the US; it had the additional advantage of making
290 1 inch = 2.54 cm (exactly). This new standard was termed the Interna‐
291 tional Yard. Australia, Canada, and the UK then defined all customary
292 lengths in terms of the International Yard (Australia did not define
293 the furlong or rod); because many US land surveys were in terms of the
294 pre-1959 units, the US continued to define customary surveyors' units
295 (furlong, chain, rod, and link) in terms of the previous value for the
296 foot, which was termed the US survey foot. The US defined a US survey
297 mile as 5280 US survey feet, and defined a statute mile as a US survey
298 mile. The US values for these units differ from the international val‐
299 ues by about 2 ppm.
300 The 'units' program uses the international values for these units; the
302 US values can be obtained by using either the 'US' or the 'survey' pre‐
303 fix. In either case, the simple familiar relationships among the units
304 are maintained, e.g., 1 'furlong' = 660 'ft', and 1 'USfurlong' = 660
305 'USft', though the metric equivalents differ slightly between the two
306 cases. The 'US' prefix or the 'survey' prefix can also be used to
307 obtain the US survey mile and the value of the US yard prior to 1959,
308 e.g., 'USmile' or 'surveymile' (but not 'USsurveymile'). To get the US
309 value of the statute mile, use either 'USstatutemile' or 'USmile'.
310 Except for distances that extend over hundreds of miles (such as in the
312 US State Plane Coordinate System), the differences in the miles are
313 usually insignificant:
314 You have: 100 surveymile - 100 mile
316 You want: inch
317 * 12.672025
318 / 0.078913984
319 The pre-1959 UK values for these units can be obtained with the prefix
321 'UK'.
322 In the US, the acre is officially defined in terms of the US survey
324 foot, but 'units' uses a definition based on the international foot.
325 If you want the official US acre use 'USacre' and similarly use
326 'USacrefoot' for the official US version of that unit. The difference
327 between these units is about 4 parts per million.
328
330 Operators
331 You can enter more complicated units by combining units with operations
332 such as multiplication, division, powers, addition, subtraction, and
333 parentheses for grouping. You can use the customary symbols for these
334 operators when 'units' is invoked with its default options. Addition‐
335 ally, 'units' supports some extensions, including high priority multi‐
336 plication using a space, and a high priority numerical division opera‐
337 tor ('|') that can simplify some expressions.
338 You multiply units using a space or an asterisk ('*'). The next exam‐
340 ple shows both forms:
341 You have: arabicfoot * arabictradepound * force
343 You want: ft lbf
344 * 0.7296
345 / 1.370614
346 You can divide units using the slash ('/') or with 'per':
348 You have: furlongs per fortnight
350 You want: m/s
351 * 0.00016630986
352 / 6012.8727
353 You can use parentheses for grouping:
355 You have: (1/2) kg / (kg/meter)
357 You want: league
358 * 0.00010356166
359 / 9656.0833
360 White space surrounding operators is optional, so the previous example
362 could have used '(1/2)kg/(kg/meter)'. As a consequence, however,
363 hyphenated spelled-out numbers (e.g., 'forty-two') cannot be used;
364 'forty-two' is interpreted as '40 - 2'.
365 Multiplication using a space has a higher precedence than division
367 using a slash and is evaluated left to right; in effect, the first '/'
368 character marks the beginning of the denominator of a unit expression.
369 This makes it simple to enter a quotient with several terms in the
370 denominator: 'J / mol K'. The '*' and '/' operators have the same
371 precedence, and are evaluated left to right; if you multiply with '*',
372 you must group the terms in the denominator with parentheses:
373 'J / (mol * K)'.
374 The higher precedence of the space operator may not always be advanta‐
376 geous. For example, 'm/s s/day' is equivalent to 'm / s s day' and has
377 dimensions of length per time cubed. Similarly, '1/2 meter' refers to
378 a unit of reciprocal length equivalent to 0.5/meter, perhaps not what
379 you would intend if you entered that expression. The get a half meter
380 you would need to use parentheses: '(1/2) meter'. The '*' operator is
381 convenient for multiplying a sequence of quotients. For example,
382 'm/s * s/day' is equivalent to 'm/day'. Similarly, you could write
383 '1/2 * meter' to get half a meter.
384 The 'units' program supports another option for numerical fractions:
386 you can indicate division of numbers with the vertical bar ('|'), so if
387 you wanted half a meter you could write '1|2 meter'. You cannot use
388 the vertical bar to indicate division of non-numerical units (e.g.,
389 'm|s' results in an error message).
390 Powers of units can be specified using the '^' character, as shown in
392 the following example, or by simple concatenation of a unit and its
393 exponent: 'cm3' is equivalent to 'cm^3'; if the exponent is more than
394 one digit, the '^' is required. You can also use '**' as an exponent
395 operator.
396 You have: cm^3
398 You want: gallons
399 * 0.00026417205
400 / 3785.4118
401 Concatenation only works with a single unit name: if you write
403 '(m/s)2', 'units' will treat it as multiplication by 2. When a unit
404 includes a prefix, exponent operators apply to the combination, so
405 'centimeter3' gives cubic centimeters. If you separate the prefix from
406 the unit with any multiplication operator (e.g., 'centi meter^3'), the
407 prefix is treated as a separate unit, so the exponent applies only to
408 the unit without the prefix. The second example is equivalent to
409 'centi * (meter^3)', and gives a hundredth of a cubic meter, not a
410 cubic centimeter. The 'units' program is limited internally to prod‐
411 ucts of 99 units; accordingly, expressions like 'meter^100' or
412 'joule^34' (represented internally as 'kg^34 m^68 / s^68') will fail.
413 The '|' operator has the highest precedence, so you can write the
415 square root of two thirds as '2|3^1|2'. The '^' operator has the sec‐
416 ond highest precedence, and is evaluated right to left, as usual:
417 You have: 5 * 2^3^2
419 You want:
420 Definition: 2560
421 With a dimensionless base unit, any dimensionless exponent is meaning‐
423 ful (e.g., 'pi^exp(2.371)'). Even though angle is sometimes treated as
424 dimensionless, exponents cannot have dimensions of angle:
425 You have: 2^radian
427 ^
428 Exponent not dimensionless
429 If the base unit is not dimensionless, the exponent must be a rational
431 number p/q, and the dimension of the unit must be a power of q, so
432 'gallon^2|3' works but 'acre^2|3' fails. An exponent using the slash
433 ('/') operator (e.g., 'gallon^(2/3)') is also acceptable; the parenthe‐
434 ses are needed because the precedence of '^' is higher than that of
435 '/'. Since 'units' cannot represent dimensions with exponents greater
436 than 99, a fully reduced exponent must have q < 100. When raising a
437 non-dimensionless unit to a power, 'units' attempts to convert a deci‐
438 mal exponent to a rational number with q < 100. If this is not possi‐
439 ble 'units' displays an error message:
440 You have: ft^1.234
442 Base unit not dimensionless; rational exponent required
443 A decimal exponent must match its rational representation to machine
445 precision, so 'acre^1.5' works but 'gallon^0.666' does not.
446 Sums and Differences of Units
448 You may sometimes want to add values of different units that are out‐
449 side the SI. You may also wish to use 'units' as a calculator that
450 keeps track of units. Sums of conformable units are written with the
451 '+' character, and differences with the '-' character.
452 You have: 2 hours + 23 minutes + 32 seconds
454 You want: seconds
455 * 8612
456 / 0.00011611705
457 You have: 12 ft + 3 in
459 You want: cm
460 * 373.38
461 / 0.0026782366
462 You have: 2 btu + 450 ft lbf
464 You want: btu
465 * 2.5782804
466 / 0.38785542
467 The expressions that are added or subtracted must reduce to identical
469 expressions in primitive units, or an error message will be displayed:
470 You have: 12 printerspoint - 4 heredium
472 ^
473 Illegal sum of non-conformable units
474 As usual, the precedence for '+' and '-' is lower than that of the
476 other operators. A fractional quantity such as 2 1/2 cups can be given
477 as '(2+1|2) cups'; the parentheses are necessary because multiplication
478 has higher precedence than addition. If you omit the parentheses,
479 'units' attempts to add '2' and '1|2 cups', and you get an error mes‐
480 sage:
481 You have: 2+1|2 cups
483 ^
484 Illegal sum or difference of non-conformable units
485 The expression could also be correctly written as '(2+1/2) cups'. If
487 you write '2 1|2 cups' the space is interpreted as multiplication so
488 the result is the same as '1 cup'.
489 The '+' and '-' characters sometimes appears in exponents like
491 '3.43e+8'. This leads to an ambiguity in an expression like '3e+2 yC'.
492 The unit 'e' is a small unit of charge, so this can be regarded as
493 equivalent to '(3e+2) yC' or '(3 e)+(2 yC)'. This ambiguity is
494 resolved by always interpreting '+' and '-' as part of an exponent if
495 possible.
496 Numbers as Units
498 For 'units', numbers are just another kind of unit. They can appear as
499 many times as you like and in any order in a unit expression. For
500 example, to find the volume of a box that is 2 ft by 3 ft by 12 ft in
501 steres, you could do the following:
502 You have: 2 ft 3 ft 12 ft
504 You want: stere
505 * 2.038813
506 / 0.49048148
507 You have: $ 5 / yard
509 You want: cents / inch
510 * 13.888889
511 / 0.072
512 And the second example shows how the dollar sign in the units conver‐
514 sion can precede the five. Be careful: 'units' will interpret '$5'
515 with no space as equivalent to 'dollar^5'.
516 Built-in Functions
518 Several built-in functions are provided: 'sin', 'cos', 'tan', 'ln',
519 'log', 'exp', 'acos', 'atan', 'asin', 'cosh', 'sinh', 'tanh', 'acosh',
520 'asinh', and 'atanh'. The 'sin', 'cos', and 'tan' functions require
521 either a dimensionless argument or an argument with dimensions of
522 angle.
523 You have: sin(30 degrees)
525 You want:
526 Definition: 0.5
527 You have: sin(pi/2)
529 You want:
530 Definition: 1
531 You have: sin(3 kg)
533 ^
534 Unit not dimensionless
535 The other functions on the list require dimensionless arguments. The
537 inverse trigonometric functions return arguments with dimensions of
538 angle.
539 The 'ln' and 'log' functions give natural log and log base 10 respec‐
541 tively. To obtain logs for any integer base, enter the desired base
542 immediately after 'log'. For example, to get log base 2 you would
543 write 'log2' and to get log base 47 you could write 'log47'.
544 You have: log2(32)
546 You want:
547 Definition: 5
548 You have: log3(32)
549 You want:
550 Definition: 3.1546488
551 You have: log4(32)
552 You want:
553 Definition: 2.5
554 You have: log32(32)
555 You want:
556 Definition: 1
557 You have: log(32)
558 You want:
559 Definition: 1.50515
560 You have: log10(32)
561 You want:
562 Definition: 1.50515
563 If you wish to take roots of units, you may use the 'sqrt' or
565 'cuberoot' functions. These functions require that the argument have
566 the appropriate root. You can obtain higher roots by using fractional
567 exponents:
568 You have: sqrt(acre)
570 You want: feet
571 * 208.71074
572 / 0.0047913202
573 You have: (400 W/m^2 / stefanboltzmann)^(1/4)
575 You have:
576 Definition: 289.80882 K
577 You have: cuberoot(hectare)
579 ^
580 Unit not a root
581 Previous Result
583 You can insert the result of the previous conversion using the under‐
584 score ('_'). It is useful when you want to convert the same input to
585 several different units, for example
586 You have: 2.3 tonrefrigeration
588 You want: btu/hr
589 * 27600
590 / 3.6231884e-005
591 You have: _
592 You want: kW
593 * 8.0887615
594 / 0.12362832
595 Suppose you want to do some deep frying that requires an oil depth of
597 2 inches. You have 1/2 gallon of oil, and want to know the largest-
598 diameter pan that will maintain the required depth. The nonlinear unit
599 'circlearea' gives the radius of the circle (see Other Nonlinear Units,
600 for a more detailed description) in SI units; you want the diameter in
601 inches:
602 You have: 1|2 gallon / 2 in
604 You want: circlearea
605 0.10890173 m
606 You have: 2 _
607 You want: in
608 * 8.5749393
609 / 0.1166189
610 In most cases, surrounding white space is optional, so the previous
612 example could have used '2_'. If '_' follows a non-numerical unit sym‐
613 bol, however, the space is required:
614 You have: m_
616 ^
617 Parse error
618 When '_' is followed by a digit, the operation is multiplication rather
620 than exponentiation, so that '_2', is equivalent to '_ * 2' rather than
621 '_^2'.
622 You can use the '_' symbol any number of times; for example,
624 You have: m
626 You want:
627 Definition: 1 m
628 You have: _ _
629 You want:
630 Definition: 1 m^2
631 Using '_' before a conversion has been performed (e.g., immediately
633 after invocation) generates an error:
634 You have: _
636 ^
637 No previous result; '_' not set
638 Accordingly, '_' serves no purpose when 'units' is invoked non-interac‐
640 tively.
641 If 'units' is invoked with the '--verbose' option (see Invoking Units),
643 the value of '_' is not expanded:
644 You have: mile
646 You want: ft
647 mile = 5280 ft
648 mile = (1 / 0.00018939394) ft
649 You have: _
650 You want: m
651 _ = 1609.344 m
652 _ = (1 / 0.00062137119) m
653 You can give '_' at the 'You want:' prompt, but it usually is not very
655 useful.
656 Complicated Unit Expressions
658 The 'units' program is especially helpful in ensuring accuracy and
659 dimensional consistency when converting lengthy unit expressions. For
660 example, one form of the Darcy-Weisbach fluid-flow equation is
661 Delta P = (8 / pi)^2 (rho fLQ^2) / d^5,
663 where Delta P is the pressure drop, rho is the mass density, f is the
665 (dimensionless) friction factor, L is the length of the pipe, Q is the
666 volumetric flow rate, and d is the pipe diameter. It might be desired
667 to have the equation in the form
668 Delta P = A1 rho fLQ^2 / d^5
670 that accepted the user's normal units; for typical units used in the
672 US, the required conversion could be something like
673 You have: (8/pi^2)(lbm/ft^3)ft(ft^3/s)^2(1/in^5)
675 You want: psi
676 * 43.533969
677 / 0.022970568
678 The parentheses allow individual terms in the expression to be entered
680 naturally, as they might be read from the formula. Alternatively, the
681 multiplication could be done with the '*' rather than a space; then
682 parentheses are needed only around 'ft^3/s' because of its exponent:
683 You have: 8/pi^2 * lbm/ft^3 * ft * (ft^3/s)^2 /in^5
685 You want: psi
686 * 43.533969
687 / 0.022970568
688 Without parentheses, and using spaces for multiplication, the previous
690 conversion would need to be entered as
691 You have: 8 lb ft ft^3 ft^3 / pi^2 ft^3 s^2 in^5
693 You want: psi
694 * 43.533969
695 / 0.022970568
696 Backwards Compatibility:
698 '*' and '-' The original 'units' assigned multiplication a higher
699 precedence than division using the slash. This differs from the usual
700 precedence rules, which give multiplication and division equal prece‐
701 dence, and can be confusing for people who think of units as a calcula‐
702 tor.
703 The star operator ('*') included in this 'units' program has, by
705 default, the same precedence as division, and hence follows the usual
706 precedence rules. For backwards compatibility you can invoke 'units'
707 with the '--oldstar' option. Then '*' has a higher precedence than
708 division, and the same precedence as multiplication using the space.
709 Historically, the hyphen ('-') has been used in technical publications
711 to indicate products of units, and the original 'units' program treated
712 it as a multiplication operator. Because 'units' provides several
713 other ways to obtain unit products, and because '-' is a subtraction
714 operator in general algebraic expressions, 'units' treats the binary
715 '-' as a subtraction operator by default. For backwards compatibility
716 use the '--product' option, which causes 'units' to treat the binary
717 '-' operator as a product operator. When '-' is a multiplication oper‐
718 ator it has the same precedence as multiplication with a space, giving
719 it a higher precedence than division.
720 When '-' is used as a unary operator it negates its operand. Regard‐
722 less of the 'units' options, if '-' appears after '(' or after '+' then
723 it will act as a negation operator. So you can always compute 20
724 degrees minus 12 minutes by entering '20 degrees + -12 arcmin'. You
725 must use this construction when you define new units because you cannot
726 know what options will be in force when your definition is processed.
727
729 Nonlinear units are represented using functional notation. They make
730 possible nonlinear unit conversions such as temperature.
731 Temperature Conversions
733 Conversions between temperatures are different from linear conversions
734 between temperature increments—see the example below. The absolute
735 temperature conversions are handled by units starting with 'temp', and
736 you must use functional notation. The temperature-increment conver‐
737 sions are done using units starting with 'deg' and they do not require
738 functional notation.
739 You have: tempF(45)
741 You want: tempC
742 7.2222222
743 You have: 45 degF
745 You want: degC
746 * 25
747 / 0.04
748 Think of 'tempF(x)' not as a function but as a notation that indicates
750 that x should have units of 'tempF' attached to it. See Defining Non‐
751 linear Units. The first conversion shows that if it's 45 degrees
752 Fahrenheit outside, it's 7.2 degrees Celsius. The second conversion
753 indicates that a change of 45 degrees Fahrenheit corresponds to a
754 change of 25 degrees Celsius. The conversion from 'tempF(x)' is to
755 absolute temperature, so that
756 You have: tempF(45)
758 You want: degR
759 * 504.67
760 / 0.0019814929
761 gives the same result as
763 You have: tempF(45)
765 You want: tempR
766 * 504.67
767 / 0.0019814929
768 But if you convert 'tempF(x)' to 'degC', the output is probably not
770 what you expect:
771 You have: tempF(45)
773 You want: degC
774 * 280.37222
775 / 0.0035666871
776 The result is the temperature in K, because 'degC' is defined as 'K',
778 the Kelvin. For consistent results, use the 'tempX' units when convert‐
779 ing to a temperature rather than converting a temperature increment.
780 The 'tempC()' and 'tempF()' definitions are limited to positive abso‐
782 lute temperatures, and giving a value that would result in a negative
783 absolute temperature generates an error message:
784 You have: tempC(-275)
786 ^
787 Argument of function outside domain
788 ^
789 Other Nonlinear Units
791 Some other examples of nonlinear units are numerous different ring
792 sizes and wire gauges, the grit sizes used for abrasives, the decibel
793 scale, shoe size, scales for the density of sugar (e.g., baume). The
794 standard data file also supplies units for computing the area of a cir‐
795 cle and the volume of a sphere. See the standard units data file for
796 more details. Wire gauges with multiple zeroes are signified using
797 negative numbers where two zeroes is '-1'. Alternatively, you can use
798 the synonyms 'g00', 'g000', and so on that are defined in the standard
799 units data file.
800 You have: wiregauge(11)
802 You want: inches
803 * 0.090742002
804 / 11.020255
805 You have: brwiregauge(g00)
807 You want: inches
808 * 0.348
809 / 2.8735632
810 You have: 1 mm
812 You want: wiregauge
813 18.201919
814 You have: grit_P(600)
816 You want: grit_ansicoated
817 342.76923
818 The last example shows the conversion from P graded sand paper, which
820 is the European standard and may be marked ``P600'' on the back, to the
821 USA standard.
822 You can compute the area of a circle using the nonlinear unit,
824 'circlearea'. You can also do this using the circularinch or cir‐
825 cleinch. The next example shows two ways to compute the area of a cir‐
826 cle with a five inch radius and one way to compute the volume of a
827 sphere with a radius of one meter.
828 You have: circlearea(5 in)
830 You want: in2
831 * 78.539816
832 / 0.012732395
833 You have: 10^2 circleinch
835 You want: in2
836 * 78.539816
837 / 0.012732395
838 You have: spherevol(meter)
840 You want: ft3
841 * 147.92573
842 / 0.0067601492
843 The inverse of a nonlinear conversion is indicated by prefixing a tilde
845 ('~') to the nonlinear unit name:
846 You have: ~wiregauge(0.090742002 inches)
848 You want:
849 Definition: 11
850 You can give a nonlinear unit definition without an argument or paren‐
852 theses, and press Enter at the 'You want:' prompt to get the definition
853 of a nonlinear unit; if the definition is not valid for all real num‐
854 bers, the range of validity is also given. If the definition requires
855 specific units this information is also displayed:
856 You have: tempC
858 Definition: tempC(x) = x K + stdtemp
859 defined for x >= -273.15
860 You have: ~tempC
861 Definition: ~tempC(tempC) = (tempC +(-stdtemp))/K
862 defined for tempC >= 0 K
863 You have: circlearea
864 Definition: circlearea(r) = pi r^2
865 r has units m
866 To see the definition of the inverse use the '~' notation. In this
868 case the parameter in the functional definition will usually be the
869 name of the unit. Note that the inverse for 'tempC' shows that it
870 requires units of 'K' in the specification of the allowed range of val‐
871 ues. Nonlinear unit conversions are described in more detail in Defin‐
872 ing Nonlinear Units.
873
875 Outside of the SI, it is sometimes desirable to convert a single unit
876 to a sum of units—for example, feet to feet plus inches. The
877 conversion from sums of units was described in Sums and Differences of
878 Units, and is a simple matter of adding the units with the '+' sign:
879 You have: 12 ft + 3 in + 3|8 in
881 You want: ft
882 * 12.28125
883 / 0.081424936
884 Although you can similarly write a sum of units to convert to, the
886 result will not be the conversion to the units in the sum, but rather
887 the conversion to the particular sum that you have entered:
888 You have: 12.28125 ft
890 You want: ft + in + 1|8 in
891 * 11.228571
892 / 0.089058524
893 The unit expression given at the 'You want:' prompt is equivalent to
895 asking for conversion to multiples of '1 ft + 1 in + 1|8 in', which is
896 1.09375 ft, so the conversion in the previous example is equivalent to
897 You have: 12.28125 ft
899 You want: 1.09375 ft
900 * 11.228571
901 / 0.089058524
902 In converting to a sum of units like miles, feet and inches, you typi‐
904 cally want the largest integral value for the first unit, followed by
905 the largest integral value for the next, and the remainder converted to
906 the last unit. You can do this conversion easily with 'units' using a
907 special syntax for lists of units. You must list the desired units in
908 order from largest to smallest, separated by the semicolon (';') char‐
909 acter:
910 You have: 12.28125 ft
912 You want: ft;in;1|8 in
913 12 ft + 3 in + 3|8 in
914 The conversion always gives integer coefficients on the units in the
916 list, except possibly the last unit when the conversion is not exact:
917 You have: 12.28126 ft
919 You want: ft;in;1|8 in
920 12 ft + 3 in + 3.00096 * 1|8 in
921 The order in which you list the units is important:
923 You have: 3 kg
925 You want: oz;lb
926 105 oz + 0.051367866 lb
927 You have: 3 kg
929 You want: lb;oz
930 6 lb + 9.8218858 oz
931 Listing ounces before pounds produces a technically correct result, but
933 not a very useful one. You must list the units in descending order of
934 size in order to get the most useful result.
935 Ending a unit list with the separator ';' has the same effect as
937 repeating the last unit on the list, so 'ft;in;1|8 in;' is equivalent
938 to 'ft;in;1|8 in;1|8 in'. With the example above, this gives
939 You have: 12.28126 ft
941 You want: ft;in;1|8 in;
942 12 ft + 3 in + 3|8 in + 0.00096 * 1|8 in
943 in effect separating the integer and fractional parts of the
945 coefficient for the last unit. If you instead prefer to round the last
946 coefficient to an integer you can do this with the '--round' ('-r')
947 option. With the previous example, the result is
948 You have: 12.28126 ft
950 You want: ft;in;1|8 in
951 12 ft + 3 in + 3|8 in (rounded down to nearest 1|8 in)
952 When you use the '-r' option, repeating the last unit on the list has
954 no effect (e.g., 'ft;in;1|8 in;1|8 in' is equivalent to 'ft;in;1|8
955 in'), and hence neither does ending a list with a ';'. With a single
956 unit and the '-r' option, a terminal ';' does have an effect: it causes
957 'units' to treat the single unit as a list and produce a rounded value
958 for the single unit. Without the extra ';', the '-r' option has no
959 effect on single unit conversions. This example shows the output using
960 the '-r' option:
961 You have: 12.28126 ft
963 You want: in
964 * 147.37512
965 / 0.0067854058
966 You have: 12.28126 ft
968 You want: in;
969 147 in (rounded down to nearest in)
970 Each unit that appears in the list must be conformable with the first
972 unit on the list, and of course the listed units must also be conform‐
973 able with the unit that you enter at the 'You have:' prompt.
974 You have: meter
976 You want: ft;kg
977 ^
978 conformability error
979 ft = 0.3048 m
980 kg = 1 kg
981 You have: meter
983 You want: lb;oz
984 conformability error
985 1 m
986 0.45359237 kg
987 In the first case, 'units' reports the disagreement between units
989 appearing on the list. In the second case, 'units' reports disagree‐
990 ment between the unit you entered and the desired conversion. This
991 conformability error is based on the first unit on the unit list.
992 Other common candidates for conversion to sums of units are angles and
994 time:
995 You have: 23.437754 deg
997 You want; deg;arcmin;arcsec
998 23 deg + 26 arcmin + 15.9144 arcsec
999 You have: 7.2319 hr
1001 You want: hr;min;sec
1002 7 hr + 13 min + 54.84 sec
1003 In North America, recipes for cooking typically measure ingredients by
1005 volume, and use units that are not always convenient multiples of each
1006 other. Suppose that you have a recipe for 6 and you wish to make a
1007 portion for 1. If the recipe calls for 2 1/2 cups of an ingredient,
1008 you might wish to know the measurements in terms of measuring devices
1009 you have available, you could use 'units' and enter
1010 You have: (2+1|2) cup / 6
1012 You want: cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
1013 1|3 cup + 1 tbsp + 1 tsp
1014 By default, if a unit in a list begins with fraction of the form 1|x
1016 and its multiplier is an integer, the fraction is given as the product
1017 of the multiplier and the numerator; for example,
1018 You have: 12.28125 ft
1020 You want: ft;in;1|8 in;
1021 12 ft + 3 in + 3|8 in
1022 In many cases, such as the example above, this is what is wanted, but
1024 sometimes it is not. For example, a cooking recipe for 6 might call
1025 for 5 1/4 cup of an ingredient, but you want a portion for 2, and your
1026 1-cup measure is not available; you might try
1027 You have: (5+1|4) cup / 3
1029 You want: 1|2 cup;1|3 cup;1|4 cup
1030 3|2 cup + 1|4 cup
1031 This result might be fine for a baker who has a 1 1/2-cup measure (and
1033 recognizes the equivalence), but it may not be as useful to someone
1034 with more limited set of measures, who does want to do additional cal‐
1035 culations, and only wants to know ``How many 1/2-cup measures to I need
1036 to add?'' After all, that's what was actually asked. With the
1037 '--show-factor' option, the factor will not be combined with a unity
1038 numerator, so that you get
1039 You have: (5+1|4) cup / 3
1041 You want: 1|2 cup;1|3 cup;1|4 cup
1042 3 * 1|2 cup + 1|4 cup
1043 A user-specified fractional unit with a numerator other than 1 is never
1045 overridden, however—if a unit list specifies '3|4 cup;1|2 cup', a
1046 result equivalent to 1 1/2 cups will always be shown as '2 * 3|4 cup'
1047 whether or not the '--show-factor' option is given.
1048 Some applications for unit lists may be less obvious. Suppose that you
1050 have a postal scale and wish to ensure that it's accurate at 1 oz, but
1051 have only metric calibration weights. You might try
1052 You have: 1 oz
1054 You want: 100 g;50 g; 20 g;10 g;5 g;2 g;1 g;
1055 20 g + 5 g + 2 g + 1 g + 0.34952312 * 1 g
1056 You might then place one each of the 20 g, 5 g, 2 g, and 1 g weights on
1058 the scale and hope that it indicates close to
1059 You have: 20 g + 5 g + 2 g + 1 g
1061 You want: oz;
1062 0.98767093 oz
1063 Appending ';' to 'oz' forces a one-line display that includes the unit;
1065 here the integer part of the result is zero, so it is not displayed.
1066 A unit list such as
1068 cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
1070 can be tedious to enter. The 'units' program provides shorthand names
1072 for some common combinations:
1073 hms hours, minutes, seconds
1075 dms angle: degrees, minutes, seconds
1076 time years, days, hours, minutes and seconds
1077 usvol US cooking volume: cups and smaller
1078 Using these shorthands, or unit list aliases, you can do the following
1080 conversions:
1081 You have: anomalisticyear
1083 You want: time
1084 1 year + 25 min + 3.4653216 sec
1085 You have: 1|6 cup
1086 You want: usvol
1087 2 tbsp + 2 tsp
1088 You cannot combine a unit list alias with other units: it must appear
1090 alone at the 'You want:' prompt.
1091 You can display the definition of a unit list alias by entering it at
1093 the 'You have:' prompt:
1094 You have: dms
1096 Definition: unit list, deg;arcmin;arcsec
1097 When you specify compact output with '--compact', '--terse' or '-t' and
1099 perform conversion to a unit list, 'units' lists the conversion factors
1100 for each unit in the list, separated by semicolons.
1101 You have: year
1103 You want: day;min;sec
1104 365;348;45.974678
1105 Unlike the case of regular output, zeros are included in this output
1107 list:
1108 You have: liter
1110 You want: cup;1|2 cup;1|4 cup;tbsp
1111 4;0;0;3.6280454
1112
1114 The SI—an extension of the MKS (meter-kilogram-second) system—has
1115 largely supplanted the older CGS (centimeter-gram-second) system, but
1116 CGS units are still used in a few specialized fields, especially in
1117 physics where they lead to a more elegant formulation of Maxwell's
1118 equations. Conversions between SI and CGS involving mechanical units
1119 are straightforward, involving powers of 10 (e.g., 1 m = 100 cm). Con‐
1120 versions involving electromagnetic units are more complicated, and
1121 'units' supports three different systems of CGS units: electrostatic
1122 units (ESU), electromagnetic units (EMU), and the Gaussian system. The
1123 differences between these systems arise from different choices made for
1124 proportionality constants in electromagnetic equations. Coulomb's law
1125 gives electrostatic force between two charges separated by a distance
1126 delim $$ r:
1127 F = k_C q_1 q_2 / r^2.
1129 Ampere's law gives the electromagnetic force per unit length between
1131 two current-carrying conductors separated by a distance r:
1132 F/l = 2 k_A I_1 I_2 / r.
1134 The two constants, k_C and k_A, are related by the square of the speed
1136 of light: k_A = k_C / c^2.
1137 In the SI, the constants have dimensions, and an additional base unit,
1139 the ampere, measures electric current. The CGS systems do not define
1140 new base units, but express charge and current as derived units in
1141 terms of mass, length, and time. In the ESU system, the constant for
1142 Coulomb's law is chosen to be unity and dimensionless, which defines
1143 the unit of charge. In the EMU system, the constant for Ampere's law
1144 is chosen to be unity and dimensionless, which defines a unit of cur‐
1145 rent. The Gaussian system usually uses the ESU units for charge and
1146 current; it chooses another constant so that the units for the electric
1147 and magnetic fields are the same.
1148 The dimensions of electrical quantities in the various CGS systems are
1150 different from the SI dimensions for the same units; strictly, conver‐
1151 sions between these systems and SI are not possible. But units in dif‐
1152 ferent systems relate to the same physical quantities, so there is a
1153 correspondence between these units. The 'units' program defines the
1154 units so that you can convert between corresponding units in the vari‐
1155 ous systems.
1156 Specifying CGS Units
1158 The CGS definitions involve cm^(1/2) and g^(1/2), which is problematic
1159 because 'units' does not normally support fractional roots of base
1160 units. The '--units' ('-u') option allows selection of a CGS unit sys‐
1161 tem and works around this restriction by introducing base units for the
1162 square roots of length and mass: 'sqrt_cm' and 'sqrt_g'. The centime‐
1163 ter then becomes 'sqrt_cm^2' and the gram, 'sqrt_g^2'. This allows
1164 working from equations using the units in the CGS system, and enforcing
1165 dimensional conformity within that system. Recognized arguments to the
1166 '--units' option are 'gauss[ian]', 'esu', 'emu', and 'si'; the argument
1167 is case insensitive. The default mode for 'units' is SI units; the
1168 only effect of giving 'si' with the '--units' option is to prepend
1169 '(SI)' to the 'You have:' prompt. Giving an unrecognized system gener‐
1170 ates a warning, and 'units' uses SI units.
1171 The changes resulting from the '--units' option are actually controlled
1173 by the 'UNITS_SYSTEM' environment variable. If you frequently work
1174 with one of the supported CGS units systems, you may set this environ‐
1175 ment variable rather than giving the '--units' option at each invoca‐
1176 tion. As usual, an option given on the command line overrides the set‐
1177 ting of the environment variable. For example, if you would normally
1178 work with Gaussian units but might occasionally work with SI, you could
1179 set 'UNITS_SYSTEM' to 'gaussian' and specify SI with the '--units'
1180 option. Unlike the argument to the '--units' option, the value of
1181 'UNITS_SYSTEM' is case sensitive, so setting a value of 'EMU' will have
1182 no effect other than to give an error message and set SI units.
1183 The CGS definitions appear as conditional settings in the standard
1185 units data file, which you can consult for more information on how
1186 these units are defined, or on how to define an alternate units system.
1187 CGS Units Systems
1189 The ESU system derives the electromagnetic units from its unit of
1190 charge, the statcoulomb, which is defined from Coulomb's law. The
1191 statcoulomb equals dyne^(1/2) cm, or cm^(3/2) g^(1/2) s^(−1). The unit
1192 of current, the statampere, is statcoulomb sec, analogous to the rela‐
1193 tionship in SI. Other electrical units are then derived in a manner
1194 similar to that for SI units; the units use the SI names prefixed by
1195 'stat-', e.g., 'statvolt' or 'statV'. The prefix 'st-' is also recog‐
1196 nized (e.g., 'stV').
1197 The EMU system derives the electromagnetic units from its unit of cur‐
1199 rent, the abampere, which is defined in terms of Ampere's law. The
1200 abampere is equal to dyne^(1/2), or cm^(1/2) g^(1/2) s^(−1). delim off
1201 The unit of charge, the abcoulomb, is abampere sec, again analogous to
1202 the SI relationship. Other electrical units are then derived in a man‐
1203 ner similar to that for SI units; the units use the SI names prefixed
1204 by 'ab-', e.g., 'abvolt' or 'abV'. The magnetic field units include
1205 the gauss, the oersted and the maxwell.
1206 The Gaussian units system, which was also known as the Symmetric Sys‐
1208 tem, uses the same charge and current units as the ESU system (e.g.,
1209 'statC', 'statA'); it differs by defining the magnetic field so that it
1210 has the same units as the electric field. The resulting magnetic field
1211 units are the same ones used in the EMU system: the gauss, the oersted
1212 and the maxwell.
1213 Conversions Between Different Systems
1215 The CGS systems define units that measure the same thing but may have
1216 conflicting dimensions. Furthermore, the dimensions of the
1217 electromagnetic CGS units are never compatible with SI. But if you
1218 measure charge in two different systems you have measured the same
1219 physical thing, so there is a correspondence between the units in the
1220 different systems, and 'units' supports conversions between correspond‐
1221 ing units. When running with SI, 'units' defines all of the CGS units
1222 in terms of SI. When you select a CGS system, 'units' defines the SI
1223 units and the other CGS system units in terms of the system you have
1224 selected.
1225 (Gaussian) You have: statA
1227 You want: abA
1228 * 3.335641e-11
1229 / 2.9979246e+10
1230 (Gaussian) You have: abA
1231 You want: sqrt(dyne)
1232 conformability error
1233 2.9979246e+10 sqrt_cm^3 sqrt_g / s^2
1234 1 sqrt_cm sqrt_g / s
1235 In the above example, 'units' converts between the current units statA
1237 and abA even though the abA, from the EMU system, has incompatible
1238 dimensions. This works because in Gaussian mode, the abA is defined in
1239 terms of the statA, so it does not have the correct definition for EMU;
1240 consequently, you cannot convert the abA to its EMU definition.
1241 One challenge of conversion is that because the CGS system has fewer
1243 base units, quantities that have different dimensions in SI may have
1244 the same dimension in a CGS system. And yet, they may not have the
1245 same conversion factor. For example, the unit for the E field and B
1246 fields are the same in the Gaussian system, but the conversion factors
1247 to SI are quite different. This means that correct conversion is only
1248 possible if you keep track of what quantity is being measured. You
1249 cannot convert statV/cm to SI without indicating which type of field
1250 the unit measures. To aid in dimensional analysis, 'units' defines
1251 various dimension units such as LENGTH, TIME, and CHARGE to be the
1252 appropriate dimension in SI. The electromagnetic dimensions such as
1253 B_FIELD or E_FIELD may be useful aids both for conversion and dimen‐
1254 sional analysis in CGS. You can convert them to or from CGS in order
1255 to perform SI conversions that in some cases will not work directly due
1256 to dimensional incompatibilities. This example shows how the Gaussian
1257 system uses the same units for all of the fields, but they all have
1258 different conversion factors with SI.
1259 (Gaussian) You have: statV/cm
1261 You want: E_FIELD
1262 * 29979.246
1263 / 3.335641e-05
1264 (Gaussian) You have: statV/cm
1265 You want: B_FIELD
1266 * 0.0001
1267 / 10000
1268 (Gaussian) You have: statV/cm
1269 You want: H_FIELD
1270 * 79.577472
1271 / 0.012566371
1272 (Gaussian) You have: statV/cm
1273 You want: D_FIELD
1274 * 2.6544187e-07
1275 / 3767303.1
1276 The next example shows that the oersted cannot be converted directly to
1278 the SI unit of magnetic field, A/m, because the dimensions conflict.
1279 We cannot redefine the ampere to make this work because then it would
1280 not convert with the statampere. But you can still do this conversion
1281 as shown below.
1282 (Gaussian) You have: oersted
1284 You want: A/m
1285 conformability error
1286 1 sqrt_g / s sqrt_cm
1287 29979246 sqrt_cm sqrt_g / s^2
1288 (Gaussian) You have: oersted
1289 You want: H_FIELD
1290 * 79.577472
1291 / 0.012566371
1292 Prompt Prefix
1294 If a unit system is specified with the '--units' option, the selected
1295 system's name is prepended to the 'You have:' prompt as a reminder,
1296 e.g.,
1297 (Gaussian) You have: stC
1299 You want:
1300 Definition: statcoulomb = sqrt(dyne) cm = 1 sqrt_cm^3 sqrt_g / s
1301 You can suppressed the prefix by including a line
1303 !prompt
1305 with no argument in a site or personal units data file. The prompt can
1307 be conditionally suppressed by including such a line within '!var'
1308 '!endvar' constructs, e.g.,
1309 !var UNITS_SYSTEM gaussian gauss
1311 !prompt
1312 !endvar
1313 This might be appropriate if you normally use Gaussian units and find
1315 the prefix distracting but want to be reminded when you have selected a
1316 different CGS system.
1317
1319 The '--log' option allows you to save the results of calculations in a
1320 file; this can be useful if you need a permanent record of your work.
1321 For example, the fluid-flow conversion in Complicated Unit Expressions,
1322 is lengthy, and if you were to use it in designing a piping system, you
1323 might want a record of it for the project file. If the interactive
1324 session
1325 # Conversion factor A1 for pressure drop
1327 # dP = A1 rho f L Q^2/d^5
1328 You have: (8/pi^2) (lbm/ft^3)ft(ft^3/s)^2(1/in^5) # Input units
1329 You want: psi
1330 * 43.533969
1331 / 0.022970568
1332 were logged, the log file would contain
1334 ### Log started Fri Oct 02 15:55:35 2015
1336 # Conversion factor A1 for pressure drop
1338 # dP = A1 rho f L Q^2/d^5
1339 From: (8/pi^2) (lbm/ft^3)ft(ft^3/s)^2(1/in^5) # Input units
1340 To: psi
1341 * 43.533969
1342 / 0.022970568
1343 The time is written to the log file when the file is opened.
1345 The use of comments can help clarify the meaning of calculations for
1347 the log. The log includes conformability errors between the units at
1348 the 'You have:' and 'You want:' prompts, but not other errors, includ‐
1349 ing lack of conformability of items in sums or differences or among
1350 items in a unit list. For example, a conversion between zenith angle
1351 and elevation angle could involve
1352 You have: 90 deg - (5 deg + 22 min + 9 sec)
1354 ^
1355 Illegal sum or difference of non-conformable units
1356 You have: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
1357 You want: dms
1358 84 deg + 37 arcmin + 51 arcsec
1359 You have: _
1360 You want: deg
1361 * 84.630833
1362 / 0.011816024
1363 You have:
1364 The log file would contain
1366 From: 90 deg - (5 deg + 22 arcmin + 9 arcsec)
1368 To: deg;arcmin;arcsec
1369 84 deg + 37 arcmin + 51 arcsec
1370 From: _
1371 To: deg
1372 * 84.630833
1373 / 0.011816024
1374 The initial entry error (forgetting that minutes have dimension of
1376 time, and that arcminutes must be used for dimensions of angle) does
1377 not appear in the output. When converting to a unit list alias,
1378 'units' expands the alias in the log file.
1379 The 'From:' and 'To:' tags are written to the log file even if the
1381 '--quiet' option is given. If the log file exists when 'units' is
1382 invoked, the new results are appended to the log file. The time is
1383 written to the log file each time the file is opened. The '--log'
1384 option is ignored when 'units' is used non-interactively.
1385
1387 You invoke 'units' like this:
1388 units [options] [from-unit [to-unit]]
1390 If the from-unit and to-unit are omitted, the program will use interac‐
1392 tive prompts to determine which conversions to perform. See Interac‐
1393 tive Use. If both from-unit and to-unit are given, 'units' will print
1394 the result of that single conversion and then exit. If only from-unit
1395 appears on the command line, 'units' will display the definition of
1396 that unit and exit. Units specified on the command line may need to be
1397 quoted to protect them from shell interpretation and to group them into
1398 two arguments. See Command Line Use.
1399 The default behavior of 'units' can be changed by various options given
1401 on the command line. In most cases, the options may be given in either
1402 short form (a single '-' followed by a single character) or long form
1403 ('--' followed by a word or hyphen-separated words). Short-form
1404 options are cryptic but require less typing; long-form options require
1405 more typing but are more explanatory and may be more mnemonic. With
1406 long-form options you need only enter sufficient characters to uniquely
1407 identify the option to the program. For example, '--out %f' works, but
1408 '--o %f' fails because 'units' has other long options beginning with
1409 'o'. However, '--q' works because '--quiet' is the only long option
1410 beginning with 'q'.
1411 Some options require arguments to specify a value (e.g., '-d 12' or
1413 '--digits 12'). Short-form options that do not take arguments may be
1414 concatenated (e.g., '-erS' is equivalent to '-e -r -S'); the last
1415 option in such a list may be one that takes an argument (e.g.,
1416 '-ed 12'). With short-form options, the space between an option and
1417 its argument is optional (e.g., '-d12' is equivalent to '-d 12').
1418 Long-form options may not be concatenated, and the space between a
1419 long-form option and its argument is required. Short-form and long-
1420 form options may be intermixed on the command line. Options may be
1421 given in any order, but when incompatible options (e.g., '--output-
1422 format' and '--exponential') are given in combination, behavior is con‐
1423 trolled by the last option given. For example, '-o%.12f -e' gives
1424 exponential format with the default eight significant digits).
1425 The following options are available:
1427 -c, --check
1429 Check that all units and prefixes defined in the units data file
1430 reduce to primitive units. Print a list of all units that can‐
1431 not be reduced. Also display some other diagnostics about sus‐
1432 picious definitions in the units data file. Only definitions
1433 active in the current locale are checked. You should always run
1434 'units' with this option after modifying a units data file.
1435 --check-verbose, --verbose-check
1437 Like the '--check' option, this option prints a list of units
1438 that cannot be reduced. But to help find unit definitions that
1439 cause endless loops, it lists the units as they are checked. If
1440 'units' hangs, then the last unit to be printed has a bad defi‐
1441 nition. Only definitions active in the current locale are
1442 checked.
1443 -d ndigits, --digits ndigits
1445 Set the number of significant digits in the output to the value
1446 specified (which must be greater than zero). For example,
1447 '-d 12' sets the number of significant digits to 12. With expo‐
1448 nential output 'units' displays one digit to the left of the
1449 decimal point and eleven digits to the right of the decimal
1450 point. On most systems, the maximum number of internally mean‐
1451 ingful digits is 15; if you specify a greater number than your
1452 system's maximum, 'units' will print a warning and set the num‐
1453 ber to the largest meaningful value. To directly set the maxi‐
1454 mum value, give an argument of 'max' (e.g., '-d max'). Be
1455 aware, of course, that ``significant'' here refers only to the
1456 display of numbers; if results depend on physical constants not
1457 known to this precision, the physically meaningful precision may
1458 be less than that shown. The '--digits' option conflicts with
1459 the '--output-format' option.
1460 -e, --exponential
1462 Set the numeric output format to exponential (i.e., scientific
1463 notation), like that used in the Unix 'units' program. The
1464 default precision is eight significant digits (seven digits to
1465 the right of the decimal point); this can be changed with the
1466 '--digits' option. The '--exponential' option conflicts with
1467 the '--output-format' option.
1468 -o format, --output-format format
1470 This option affords complete control over the numeric output
1471 format using the specified format. The format is a single float‐
1472 ing point numeric format for the 'printf()' function in the C
1473 programming language. All compilers support the format types
1474 'g' and 'G' to specify significant digits, 'e' and 'E' for sci‐
1475 entific notation, and 'f' for fixed-point decimal. The ISO C99
1476 standard introduced the 'F' type for fixed-point decimal and the
1477 'a' and 'A' types for hexadecimal floating point; these types
1478 are allowed with compilers that support them. The default for‐
1479 mat is '%.8g'; for greater precision, you could specify
1480 '-o %.15g'. See Numeric Output Format and the documentation for
1481 'printf()' for more detailed descriptions of the format specifi‐
1482 cation. The '--output-format' option affords the greatest con‐
1483 trol of the output appearance, but requires at least rudimentary
1484 knowledge of the 'printf()' format syntax. If you don't want to
1485 bother with the 'printf()' syntax, you can specify greater pre‐
1486 cision more simply with the '--digits' option or select exponen‐
1487 tial format with '--exponential'. The '--output-format' option
1488 is incompatible with the '--exponential' and '--digits' options.
1489 -f filename, --file filename
1491 Instruct 'units' to load the units file filename. You can spec‐
1492 ify up to 25 units files on the command line. When you use this
1493 option, 'units' will load only the files you list on the command
1494 line; it will not load the standard file or your personal units
1495 file unless you explicitly list them. If filename is the empty
1496 string ('-f ""'), the default units file (or that specified by
1497 'UNITSFILE') will be loaded in addition to any others specified
1498 with '-f'.
1499 -L logfile, --log logfile
1501 Save the results of calculations in the file logfile; this can
1502 be useful if it is important to have a record of unit conver‐
1503 sions or other calculations that are to be used extensively or
1504 in a critical activity such as a program or design project. If
1505 logfile exits, the new results are appended to the file. This
1506 option is ignored when 'units' is used non-interactively. See
1507 Logging Calculations for a more detailed description and some
1508 examples.
1509 -H filename, --history filename
1511 Instruct 'units' to save history to filename, so that a record
1512 of your commands is available for retrieval across different
1513 'units' invocations. To prevent the history from being saved
1514 set filename to the empty string ('-H ""'). This option has no
1515 effect if readline is not available.
1516 -h, --help
1518 Print out a summary of the options for 'units'.
1519 -m, --minus
1521 Causes '-' to be interpreted as a subtraction operator. This is
1522 the default behavior.
1523 -p, --product
1525 Causes '-' to be interpreted as a multiplication operator when
1526 it has two operands. It will act as a negation operator when it
1527 has only one operand: '(-3)'. By default '-' is treated as a
1528 subtraction operator.
1529 --oldstar
1531 Causes '*' to have the old-style precedence, higher than the
1532 precedence of division so that '1/2*3' will equal '1/6'.
1533 --newstar
1535 Forces '*' to have the new (default) precedence that follows the
1536 usual rules of algebra: the precedence of '*' is the same as the
1537 precedence of '/', so that '1/2*3' will equal '3/2'.
1538 --compact
1540 Give compact output featuring only the conversion factor. This
1541 turns off the '--verbose' option.
1542 -q, --quiet, --silent
1544 Suppress prompting of the user for units and the display of sta‐
1545 tistics about the number of units loaded.
1546 -n, --nolists
1548 Disable conversion to unit lists.
1549 -r, --round
1551 When converting to a combination of units given by a unit list,
1552 round the value of the last unit in the list to the nearest
1553 integer.
1554 -S, --show-factor
1556 When converting to a combination of units specified in a list,
1557 always show a non-unity factor before a unit that begins with a
1558 fraction with a unity denominator. By default, if the unit in a
1559 list begins with fraction of the form 1|x and its multiplier is
1560 an integer other than 1, the fraction is given as the product of
1561 the multiplier and the numerator (e.g., '3|8 in' rather than '3
1562 * 1|8 in'). In some cases, this is not what is wanted; for
1563 example, the results for a cooking recipe might show '3 *
1564 1|2 cup' as '3|2 cup'. With the '--show-factor' option, a
1565 result equivalent to 1.5 cups will display as '3 * 1|2 cup'
1566 rather than '3|2 cup'. A user-specified fractional unit with a
1567 numerator other than 1 is never overridden, however—if a unit
1568 list specifies '3|4 cup;1|2 cup', a result equivalent to 1 1/2
1569 cups will always be shown as '2 * 3|4 cup' whether or not the
1570 '--show-factor' option is given.
1571 -s, --strict
1573 Suppress conversion of units to their reciprocal units. For
1574 example, 'units' will normally convert hertz to seconds because
1575 these units are reciprocals of each other. The strict option
1576 requires that units be strictly conformable to perform a conver‐
1577 sion, and will give an error if you attempt to convert hertz to
1578 seconds.
1579 -1, --one-line
1581 Give only one line of output (the forward conversion). Do not
1582 print the reverse conversion. If a reciprocal conversion is
1583 performed then 'units' will still print the ``reciprocal conver‐
1584 sion'' line.
1585 -t, --terse
1587 Give terse output when converting units. This option can be
1588 used when calling 'units' from another program so that the out‐
1589 put is easy to parse. This option has the combined effect of
1590 these options: '--strict' '--quiet' '--one-line' '--compact'.
1591 When combined with '--version' it produces a display showing
1592 only the program name and version number.
1593 -v, --verbose
1595 Give slightly more verbose output when converting units. When
1596 combined with the '-c' option this gives the same effect as
1597 '--check-verbose'. When combined with '--version' produces a
1598 more detailed output, equivalent to the '--info' option.
1599 -V, --version
1601 Print the program version number, tell whether the 'readline'
1602 library has been included, tell whether UTF-8 support has been
1603 included; give the locale, the location of the default units
1604 data file, and the location of the personal units data file;
1605 indicate if the personal units data file does not exist.
1606 When given in combination with the '--terse' option, the program prints
1608 only the version number and exits.
1609 When given in combination with the '--verbose' option, the program, the
1611 '--version' option has the same effect as the '--info' option below.
1612 -I, --info
1614 Print the information given with the '--version' option, show
1615 the pathname of the units program, show the status of the
1616 'UNITSFILE' and 'MYUNITSFILE' environment variables, and addi‐
1617 tional information about how 'units' locates the related files.
1618 On systems running Microsoft Windows, the status of the
1619 'UNITSLOCALE' environment variable and information about the
1620 related locale map are also given. This option is usually of
1621 interest only to developers and administrators, but it can some‐
1622 times be useful for troubleshooting.
1623 Combining the '--version' and '--verbose' options has the same effect
1625 as giving '--info'.
1626 -U, --unitsfile
1628 Print the location of the default units data file and exit; if
1629 the file cannot be found, print ``Units data file not found''.
1630 -u (gauss[ian]|esu|emu), --units (gauss[ian]|esu|emu)
1632 Specify a CGS units system: Gaussian, ESU, or EMU.
1633 -l locale, --locale locale
1635 Print the information given with the '--version' option, show
1636 the Force a specified locale such as 'en_GB' to get British def‐
1637 initions by default. This overrides the locale determined from
1638 system settings or environment variables. See Locale for a
1639 description of locale format.
1640
1642 Units Data Files
1643 The units and prefixes that 'units' can convert are defined in the
1644 units data file, typically '/usr/share/units/definitions.units'. If
1645 you can't find this file, run 'units --version' to get information on
1646 the file locations for your installation. Although you can extend or
1647 modify this data file if you have appropriate user privileges, it's
1648 usually better to put extensions in separate files so that the defini‐
1649 tions will be preserved if you update 'units'.
1650 You can include additional data files in the units database using the
1652 '!include' command in the standard units data file. For example
1653 !include /usr/local/share/units/local.units
1655 might be appropriate for a site-wide supplemental data file. The loca‐
1657 tion of the '!include' statement in the standard units data file is
1658 important; later definitions replace earlier ones, so any definitions
1659 in an included file will override definitions before the '!include'
1660 statement in the standard units data file. With normal invocation, no
1661 warning is given about redefinitions; to ensure that you don't have an
1662 unintended redefinition, run 'units -c' after making changes to any
1663 units data file.
1664 If you want to add your own units in addition to or in place of stan‐
1666 dard or site-wide supplemental units data files, you can include them
1667 in the '.units' file in your home directory. If this file exists it is
1668 read after the standard units data file, so that any definitions in
1669 this file will replace definitions of the same units in the standard
1670 data file or in files included from the standard data file. This file
1671 will not be read if any units files are specified on the command line.
1672 (Under Windows the personal units file is named 'unitdef.units'.) Run‐
1673 ning 'units -V' will display the location and name of your personal
1674 units file.
1675 The 'units' program first tries to determine your home directory from
1677 the 'HOME' environment variable. On systems running Microsoft Windows,
1678 if 'HOME' does not exist, 'units' attempts to find your home directory
1679 from 'HOMEDRIVE', 'HOMEPATH' and 'USERPROFILE'. You can specify an
1680 arbitrary file as your personal units data file with the 'MYUNITSFILE'
1681 environment variable; if this variable exists, its value is used with‐
1682 out searching your home directory. The default units data files are
1683 described in more detail in Data Files.
1684 Defining New Units and Prefixes
1686 A unit is specified on a single line by giving its name and an equiva‐
1687 lence. Comments start with a '#' character, which can appear anywhere
1688 in a line. The backslash character ('\') acts as a continuation char‐
1689 acter if it appears as the last character on a line, making it possible
1690 to spread definitions out over several lines if desired. A file can be
1691 included by giving the command '!include' followed by the file's name.
1692 The '!' must be the first character on the line. The file will be
1693 sought in the same directory as the parent file unless you give a full
1694 path. The name of the file to be included cannot contain spaces or the
1695 comment character '#'.
1696 Unit names must not contain any of the operator characters '+', '-',
1698 '*', '/', '|', '^', ';', '~', the comment character '#', or parenthe‐
1699 ses. They cannot begin or end with an underscore ('_'), a comma (',')
1700 or a decimal point ('.'). The figure dash (U+2012), typographical
1701 minus (`-'; U+2212), and en dash (`-'; U+2013) are converted to the
1702 operator '-', so none of these characters can appear in unit names.
1703 Names cannot begin with a digit, and if a name ends in a digit other
1704 than zero, the digit must be preceded by a string beginning with an
1705 underscore, and afterwards consisting only of digits, decimal points,
1706 or commas. For example, 'foo_2', 'foo_2,1', or 'foo_3.14' are valid
1707 names but 'foo2' or 'foo_a2' are invalid. You could define nitrous
1708 oxide as
1709 N2O nitrogen 2 + oxygen
1711 but would need to define nitrogen dioxide as
1713 NO_2 nitrogen + oxygen 2
1715 Be careful to define new units in terms of old ones so that a reduction
1717 leads to the primitive units, which are marked with '!' characters.
1718 Dimensionless units are indicated by using the string '!dimensionless'
1719 for the unit definition.
1720 When adding new units, be sure to use the '-c' option to check that the
1722 new units reduce properly. If you create a loop in the units defini‐
1723 tions, then 'units' will hang when invoked with the '-c' option. You
1724 will need to use the '--check-verbose' option, which prints out each
1725 unit as it is checked. The program will still hang, but the last unit
1726 printed will be the unit that caused the infinite loop.
1727 If you define any units that contain '+' characters in their defini‐
1729 tions, carefully check them because the '-c' option will not catch non-
1730 conformable sums. Be careful with the '-' operator as well. When used
1731 as a binary operator, the '-' character can perform addition or multi‐
1732 plication depending on the options used to invoke 'units'. To ensure
1733 consistent behavior use '-' only as a unary negation operator when
1734 writing units definitions. To multiply two units leave a space or use
1735 the '*' operator with care, recalling that it has two possible prece‐
1736 dence values and may require parentheses to ensure consistent behavior.
1737 To compute the difference of 'foo' and 'bar' write 'foo+(-bar)' or even
1738 'foo+-bar'.
1739 You may wish to intentionally redefine a unit. When you do this, and
1741 use the '-c' option, 'units' displays a warning message about the
1742 redefinition. You can suppress these warnings by redefining a unit
1743 using a '+' at the beginning of the unit name. Do not include any
1744 white space between the '+' and the redefined unit name.
1745 Here is an example of a short data file that defines some basic units:
1747 m ! # The meter is a primitive unit
1749 sec ! # The second is a primitive unit
1750 rad !dimensionless # A dimensionless primitive unit
1751 micro- 1e-6 # Define a prefix
1752 minute 60 sec # A minute is 60 seconds
1753 hour 60 min # An hour is 60 minutes
1754 inch 72 m # Inch defined incorrectly terms of meters
1755 ft 12 inches # The foot defined in terms of inches
1756 mile 5280 ft # And the mile
1757 +inch 0.0254 m # Correct redefinition, warning suppressed
1758 A unit that ends with a '-' character is a prefix. If a prefix defini‐
1760 tion contains any '/' characters, be sure they are protected by paren‐
1761 theses. If you define 'half- 1/2' then 'halfmeter' would be equivalent
1762 to '1 / (2 meter)'.
1763 Defining Nonlinear Units
1765 Some unit conversions of interest are nonlinear; for example, tempera‐
1766 ture conversions between the Fahrenheit and Celsius scales cannot be
1767 done by simply multiplying by conversion factors.
1768 When you give a linear unit definition such as 'inch 2.54 cm' you are
1770 providing information that 'units' uses to convert values in inches
1771 into primitive units of meters. For nonlinear units, you give a func‐
1772 tional definition that provides the same information.
1773 Nonlinear units are represented using a functional notation. It is
1775 best to regard this notation not as a function call but as a way of
1776 adding units to a number, much the same way that writing a linear unit
1777 name after a number adds units to that number. Internally, nonlinear
1778 units are defined by a pair of functions that convert to and from lin‐
1779 ear units in the database, so that an eventual conversion to primitive
1780 units is possible.
1781 Here is an example nonlinear unit definition:
1783 tempF(x) units=[1;K] domain=[-459.67,) range=[0,) \
1785 (x+(-32)) degF + stdtemp ; (tempF+(-stdtemp))/degF + 32
1786 A nonlinear unit definition comprises a unit name, a formal parameter
1788 name, two functions, and optional specifications for units, the domain,
1789 and the range (the domain of the inverse function). The functions tell
1790 'units' how to convert to and from the new unit. To produce valid
1791 results, the arguments of these functions need to have the correct
1792 dimensions and be within the domains for which the functions are
1793 defined.
1794 The definition begins with the unit name followed immediately (with no
1796 spaces) by a '(' character. In the parentheses is the name of the for‐
1797 mal parameter. Next is an optional specification of the units required
1798 by the functions in the definition. In the example above, the
1799 'units=[1;K]' specification indicates that the 'tempF' function
1800 requires an input argument conformable with '1' (i.e., the argument is
1801 dimensionless), and that the inverse function requires an input argu‐
1802 ment conformable with 'K'. For normal nonlinear units definition, the
1803 forward function will always take a dimensionless argument; in general,
1804 the inverse function will need units that match the quantity measured
1805 by your nonlinear unit. Specifying the units enables 'units' to per‐
1806 form error checking on function arguments, and also to assign units to
1807 domain and range specifications, which are described later.
1808 Next the function definitions appear. In the example above, the
1810 'tempF' function is defined by
1811 tempF(x) = (x+(-32)) degF + stdtemp
1813 This gives a rule for converting 'x' in the units 'tempF' to linear
1815 units of absolute temperature, which makes it possible to convert from
1816 tempF to other units.
1817 To enable conversions to Fahrenheit, you must give a rule for the
1819 inverse conversions. The inverse will be 'x(tempF)' and its definition
1820 appears after a ';' character. In our example, the inverse is
1821 x(tempF) = (tempF+(-stdtemp))/degF + 32
1823 This inverse definition takes an absolute temperature as its argument
1825 and converts it to the Fahrenheit temperature. The inverse can be
1826 omitted by leaving out the ';' character and the inverse definition,
1827 but then conversions to the unit will not be possible. If the inverse
1828 definition is omitted, the '--check' option will display a warning. It
1829 is up to you to calculate and enter the correct inverse function to
1830 obtain proper conversions; the '--check' option tests the inverse at
1831 one point and prints an error if it is not valid there, but this is not
1832 a guarantee that your inverse is correct.
1833 With some definitions, the units may vary. For example, the definition
1835 square(x) x^2
1837 can have any arbitrary units, and can also take dimensionless argu‐
1839 ments. In such a case, you should not specify units. If a definition
1840 takes a root of its arguments, the definition is valid only for units
1841 that yield such a root. For example,
1842 squirt(x) sqrt(x)
1844 is valid for a dimensionless argument, and for arguments with even pow‐
1846 ers of units.
1847 Some definitions may not be valid for all real numbers. In such cases,
1849 'units' can handle errors better if you specify an appropriate domain
1850 and range. You specify the domain and range as shown below:
1851 baume(d) units=[1;g/cm^3] domain=[0,130.5] range=[1,10] \
1853 (145/(145-d)) g/cm^3 ; (baume+-g/cm^3) 145 / baume
1854 In this example the domain is specified after 'domain=' with the end‐
1856 points given in brackets. In accord with mathematical convention,
1857 square brackets indicate a closed interval (one that includes its end‐
1858 points), and parentheses indicate an open interval (one that does not
1859 include its endpoints). An interval can be open or closed on one or
1860 both ends; an interval that is unbounded on either end is indicated by
1861 omitting the limit on that end. For example, a quantity to which deci‐
1862 bel (dB) is applied may have any value greater than zero, so the range
1863 is indicated by '(0,)':
1864 decibel(x) units=[1;1] range=(0,) 10^(x/10); 10 log(decibel)
1866 If the domain or range is given, the second endpoint must be greater
1868 than the first.
1869 The domain and range specifications can appear independently and in any
1871 order along with the units specification. The values for the domain
1872 and range endpoints are attached to the units given in the units speci‐
1873 fication, and if necessary, the parameter value is adjusted for compar‐
1874 ison with the endpoints. For example, if a definition includes
1875 'units=[1;ft]' and 'range=[3,)', the range will be taken as 3 ft to
1876 infinity. If the function is passed a parameter of '900 mm', that
1877 value will be adjusted to 2.9527559 ft, which is outside the specified
1878 range. If you omit the units specification from the previous example,
1879 'units' can not tell whether you intend the lower endpoint to be 3 ft
1880 or 3 microfurlongs, and can not adjust the parameter value of 900 mm
1881 for comparison. Without units, numerical values other than zero or
1882 plus or minus infinity for domain or range endpoints are meaningless,
1883 and accordingly they are not allowed. If you give other values without
1884 units then the definition will be ignored and you will get an error
1885 message.
1886 Although the units, domain, and range specifications are optional, it's
1888 best to give them when they are applicable; doing so allows 'units' to
1889 perform better error checking and give more helpful error messages.
1890 Giving the domain and range also enables the '--check' option to find a
1891 point in the domain to use for its point check of your inverse defini‐
1892 tion.
1893 You can make synonyms for nonlinear units by providing both the forward
1895 and inverse functions; inverse functions can be obtained using the '~'
1896 operator. So to create a synonym for 'tempF' you could write
1897 fahrenheit(x) units=[1;K] tempF(x); ~tempF(fahrenheit)
1899 This is useful for creating a nonlinear unit definition that differs
1901 slightly from an existing definition without having to repeat the orig‐
1902 inal functions. For example,
1903 dBW(x) units=[1;W] range=[0,) dB(x) W ; ~dB(dBW/W)
1905 If you wish a synonym to refer to an existing nonlinear unit without
1907 modification, you can do so more simply by adding the synonym with
1908 appended parentheses as a new unit, with the existing nonlinear unit—
1909 without parentheses—as the definition. So to create a synonym for
1910 'tempF' you could write
1911 fahrenheit() tempF
1913 The definition must be a nonlinear unit; for example, the synonym
1915 fahrenheit() meter
1917 will result in an error message when 'units' starts.
1919 You may occasionally wish to define a function that operates on units.
1921 This can be done using a nonlinear unit definition. For example, the
1922 definition below provides conversion between radius and the area of a
1923 circle. This definition requires a length as input and produces an
1924 area as output, as indicated by the 'units=' specification. Specifying
1925 the range as the nonnegative numbers can prevent cryptic error mes‐
1926 sages.
1927 circlearea(r) units=[m;m^2] range=[0,) pi r^2 ; sqrt(circlearea/pi)
1929 Defining Piecewise Linear Units
1931 Sometimes you may be interested in a piecewise linear unit such as many
1932 wire gauges. Piecewise linear units can be defined by specifying con‐
1933 versions to linear units on a list of points. Conversion at other
1934 points will be done by linear interpolation. A partial definition of
1935 zinc gauge is
1936 zincgauge[in] 1 0.002, 10 0.02, 15 0.04, 19 0.06, 23 0.1
1938 In this example, 'zincgauge' is the name of the piecewise linear unit.
1940 The definition of such a unit is indicated by the embedded '[' charac‐
1941 ter. After the bracket, you should indicate the units to be attached
1942 to the numbers in the table. No spaces can appear before the ']' char‐
1943 acter, so a definition like 'foo[kg meters]' is invalid; instead write
1944 'foo[kg*meters]'. The definition of the unit consists of a list of
1945 pairs optionally separated by commas. This list defines a function for
1946 converting from the piecewise linear unit to linear units. The first
1947 item in each pair is the function argument; the second item is the
1948 value of the function at that argument (in the units specified in
1949 brackets). In this example, we define 'zincgauge' at five points. For
1950 example, we set 'zincgauge(1)' equal to '0.002 in'. Definitions like
1951 this may be more readable if written using continuation characters
1952 as
1953 zincgauge[in] \
1955 1 0.002 \
1956 10 0.02 \
1957 15 0.04 \
1958 19 0.06 \
1959 23 0.1
1960 With the preceding definition, the following conversion can be per‐
1962 formed:
1963 You have: zincgauge(10)
1965 You want: in
1966 * 0.02
1967 / 50
1968 You have: .01 inch
1969 You want: zincgauge
1970 5
1971 If you define a piecewise linear unit that is not strictly monotonic,
1973 then the inverse will not be well defined. If the inverse is requested
1974 for such a unit, 'units' will return the smallest inverse.
1975 After adding nonlinear units definitions, you should normally run
1977 'units --check' to check for errors. If the 'units' keyword is not
1978 given, the '--check' option checks a nonlinear unit definition using a
1979 dimensionless argument, and then checks using an arbitrary combination
1980 of units, as well as the square and cube of that combination; a warning
1981 is given if any of these tests fail. For example,
1982 Warning: function 'squirt(x)' defined as 'sqrt(x)'
1984 failed for some test inputs:
1985 squirt(7(kg K)^1): Unit not a root
1986 squirt(7(kg K)^3): Unit not a root
1987 Running 'units --check' will print a warning if a non-monotonic piece‐
1989 wise linear unit is encountered. For example, the relationship between
1990 ANSI coated abrasive designation and mean particle size is non-mono‐
1991 tonic in the vicinity of 800 grit:
1992 ansicoated[micron] \
1994 . . .
1995 600 10.55 \
1996 800 11.5 \
1997 1000 9.5 \
1998 Running 'units --check' would give the error message
2000 Table 'ansicoated' lacks unique inverse around entry 800
2002 Although the inverse is not well defined in this region, it's not
2004 really an error. Viewing such error messages can be tedious, and if
2005 there are enough of them, they can distract from true errors. Error
2006 checking for nonlinear unit definitions can be suppressed by giving the
2007 'noerror' keyword; for the examples above, this could be done as
2008 squirt(x) noerror domain=[0,) range=[0,) sqrt(x); squirt^2
2010 ansicoated[micron] noerror \
2011 . . .
2012 Use the 'noerror' keyword with caution. The safest approach after
2014 adding a nonlinear unit definition is to run 'units --check' and con‐
2015 firm that there are no actual errors before adding the 'noerror' key‐
2016 word.
2017 Defining Unit List Aliases
2019 Unit list aliases are treated differently from unit definitions,
2020 because they are a data entry shorthand rather than a true definition
2021 for a new unit. A unit list alias definition begins with '!unitlist'
2022 and includes the alias and the definition; for example, the aliases
2023 included in the standard units data file are
2024 !unitlist hms hr;min;sec
2026 !unitlist time year;day;hr;min;sec
2027 !unitlist dms deg;arcmin;arcsec
2028 !unitlist ftin ft;in;1|8 in
2029 !unitlist usvol cup;3|4 cup;2|3 cup;1|2 cup;1|3 cup;1|4 cup;\
2030 tbsp;tsp;1|2 tsp;1|4 tsp;1|8 tsp
2031 Unit list aliases are only for unit lists, so the definition must
2033 include a ';'. Unit list aliases can never be combined with units or
2034 other unit list aliases, so the definition of 'time' shown above could
2035 not have been shortened to 'year;day;hms'.
2036 As usual, be sure to run 'units --check' to ensure that the units
2038 listed in unit list aliases are conformable.
2039
2041 By default, 'units' shows results to eight significant digits. You can
2042 change this with the '--exponential', '--digits', and '--output-format'
2043 options. The first sets an exponential format (i.e., scientific nota‐
2044 tion) like that used in the original Unix 'units' program, the second
2045 allows you to specify a different number of significant digits, and the
2046 last allows you to control the output appearance using the format for
2047 the 'printf()' function in the C programming language. If you only
2048 want to change the number of significant digits or specify exponential
2049 format type, use the '--digits' and '--exponential' options. The
2050 '--output-format' option affords the greatest control of the output
2051 appearance, but requires at least rudimentary knowledge of the
2052 'printf()' format syntax. See Invoking Units for descriptions of these
2053 options.
2054 Format Specification
2056 The format specification recognized with the '--output-format' option
2057 is a subset of that for 'printf()'. The format specification has the
2058 form '%'[flags][width]['.'precision]type; it must begin with '%', and
2059 must end with a floating-point type specifier: 'g' or 'G' to specify
2060 the number of significant digits, 'e' or 'E' for scientific notation,
2061 and 'f' for fixed-point decimal. The ISO C99 standard added the 'F'
2062 type for fixed-point decimal and the 'a' and 'A' types for hexadecimal
2063 floating point; these types are allowed with compilers that support
2064 them. Type length modifiers (e.g., 'L' to indicate a long double) are
2065 inapplicable and are not allowed.
2066 The default format for 'units' is '%.8g'; for greater precision, you
2068 could specify '-o %.15g'. The 'g' and 'G' format types use exponential
2069 format whenever the exponent would be less than -4, so the value
2070 0.000013 displays as '1.3e-005'. These types also use exponential
2071 notation when the exponent is greater than or equal to the precision,
2072 so with the default format, the value 5e7 displays as '50000000' and
2073 the value 5e8 displays as '5e+008'. If you prefer fixed-point display,
2074 you might specify '-o %.8f'; however, small numbers will display very
2075 few significant digits, and values less than 0.5e-8 will show nothing
2076 but zeros.
2077 The format specification may include one or more optional flags: '+',
2079 ' ' (space), '#', '-', or '0' (the digit zero). The digit-grouping
2080 flag ''' is allowed with compilers that support it. Flags are followed
2081 by an optional value for the minimum field width, and an optional pre‐
2082 cision specification that begins with a period (e.g., '.6'). The field
2083 width includes the digits, decimal point, the exponent, thousands sepa‐
2084 rators (with the digit-grouping flag), and the sign if any of these are
2085 shown.
2086 Flags
2088 The '+' flag causes the output to have a sign ('+' or '-'). The space
2089 flag ' ' is similar to the '+' flag, except that when the value is pos‐
2090 itive, it is prefixed with a space rather than a plus sign; this flag
2091 is ignored if the '+' flag is also given. The '+' or ' ' flag could be
2092 useful if conversions might include positive and negative results, and
2093 you wanted to align the decimal points in exponential notation. The
2094 '#' flag causes the output value to contain a decimal point in all
2095 cases; by default, the output contains a decimal point only if there
2096 are digits (which can be trailing zeros) to the right of the point.
2097 With the 'g' or 'G' types, the '#' flag also prevents the suppression
2098 of trailing zeros. The digit-grouping flag ''' shows a thousands sepa‐
2099 rator in digits to the left of the decimal point. This can be useful
2100 when displaying large numbers in fixed-point decimal; for example, with
2101 the format '%f',
2102 You have: mile
2104 You want: microfurlong
2105 * 8000000.000000
2106 / 0.000000
2107 the magnitude of the first result may not be immediately obvious with‐
2109 out counting the digits to the left of the decimal point. If the thou‐
2110 sands separator is the comma (','), the output with the format '%'f'
2111 might be
2112 You have: mile
2114 You want: microfurlong
2115 * 8,000,000.000000
2116 / 0.000000
2117 making the magnitude readily apparent. Unfortunately, few compilers
2119 support the digit-grouping flag.
2120 With the '-' flag, the output value is left aligned within the
2122 specified field width. If a field width greater than needed to show
2123 the output value is specified, the '0' (zero) flag causes the output
2124 value to be left padded with zeros until the specified field width is
2125 reached; for example, with the format '%011.6f',
2126 You have: troypound
2128 You want: grain
2129 * 5760.000000
2130 / 0000.000174
2131 The '0' flag has no effect if the '-' (left align) flag is given.
2133 Field Width
2135 By default, the output value is left aligned and shown with the minimum
2136 width necessary for the specified (or default) precision. If a field
2137 width greater than this is specified, the value shown is right aligned,
2138 and padded on the left with enough spaces to provide the specified
2139 field width. A width specification is typically used with fixed-point
2140 decimal to have columns of numbers align at the decimal point; this
2141 arguably is less useful with 'units' than with long columnar output,
2142 but it may nonetheless assist in quickly assessing the relative magni‐
2143 tudes of results. For example, with the format '%12.6f',
2144 You have: km
2146 You want: in
2147 * 39370.078740
2148 / 0.000025
2149 You have: km
2150 You want: rod
2151 * 198.838782
2152 / 0.005029
2153 You have: km
2154 You want: furlong
2155 * 4.970970
2156 / 0.201168
2157 Precision
2159 The meaning of ``precision'' depends on the format type. With 'g' or
2160 'G', it specifies the number of significant digits (like the '--digits'
2161 option); with 'e', 'E', 'f', or 'F', it specifies the maximum number of
2162 digits to be shown after the decimal point.
2163 With the 'g' and 'G' format types, trailing zeros are suppressed, so
2165 the results may sometimes have fewer digits than the specified preci‐
2166 sion (as indicated above, the '#' flag causes trailing zeros to be dis‐
2167 played).
2168 The default precision is 6, so '%g' is equivalent to '%.6g', and would
2170 show the output to six significant digits. Similarly, '%e' or '%f'
2171 would show the output with six digits after the decimal point.
2172 The C 'printf()' function allows a precision of arbitrary size, whether
2174 or not all of the digits are meaningful. With most compilers, the max‐
2175 imum internal precision with 'units' is 15 decimal digits (or 13 hexa‐
2176 decimal digits). With the '--digits' option, you are limited to the
2177 maximum internal precision; with the '--output-format' option, you may
2178 specify a precision greater than this, but it may not be meaningful.
2179 In some cases, specifying excess precision can result in rounding arti‐
2180 facts. For example, a pound is exactly 7000 grains, but with the for‐
2181 mat '%.18g', the output might be
2182 You have: pound
2184 You want: grain
2185 * 6999.9999999999991
2186 / 0.00014285714285714287
2187 With the format '%.25g' you might get the following:
2189 You have: 1/3
2191 You want:
2192 Definition: 0.333333333333333314829616256247
2193 In this case the displayed value includes a series of digits that rep‐
2195 resent the underlying binary floating-point approximation to 1/3 but
2196 are not meaningful for the desired computation. In general, the result
2197 with excess precision is system dependent. The precision affects only
2198 the display of numbers; if a result relies on physical constants that
2199 are not known to the specified precision, the number of physically
2200 meaningful digits may be less than the number of digits shown.
2201 See the documentation for 'printf()' for more detailed descriptions of
2203 the format specification.
2204 The '--output-format' option is incompatible with the '--exponential'
2206 or '--digits' options; if the former is given in combination with
2207 either of the latter, the format is controlled by the last option
2208 given.
2209
2211 Some units have different values in different locations. The localiza‐
2212 tion feature accommodates this by allowing a units data file to specify
2213 definitions that depend on the user's locale.
2214 Locale
2216 A locale is a subset of a user's environment that indicates the user's
2217 language and country, and some attendant preferences, such as the for‐
2218 matting of dates. The 'units' program attempts to determine the locale
2219 from the POSIX setlocale function; if this cannot be done, 'units'
2220 examines the environment variables 'LC_CTYPE' and 'LANG'. On POSIX
2221 systems, a locale is of the form language'_'country, where language is
2222 the two-character code from ISO 639-1 and country is the two-character
2223 code from ISO 3166-1; language is lower case and country is upper case.
2224 For example, the POSIX locale for the United Kingdom is 'en_GB'.
2225 On systems running Microsoft Windows, the value returned by setlocale()
2227 is different from that on POSIX systems; 'units' attempts to map the
2228 Windows value to a POSIX value by means of a table in the file
2229 'locale_map.txt' in the same directory as the other data files. The
2230 file includes entries for many combinations of language and country,
2231 and can be extended to include other combinations. The
2232 'locale_map.txt' file comprises two tab-separated columns; each entry
2233 is of the form
2234 Windows-locale POSIX-locale
2236 where POSIX-locale is as described above, and Windows-locale typically
2238 spells out both the language and country. For example, the entry for
2239 the United States is
2240 English_United States en_US
2242 You can force 'units' to run in a desired locale by using the '-l'
2244 option.
2245 In order to create unit definitions for a particular locale you begin a
2247 block of definitions in a unit datafile with '!locale' followed by a
2248 locale name. The '!' must be the first character on the line. The
2249 'units' program reads the following definitions only if the current
2250 locale matches. You end the block of localized units with
2251 '!endlocale'. Here is an example, which defines the British gallon.
2252 !locale en_GB
2254 gallon 4.54609 liter
2255 !endlocale
2256 Additional Localization
2258 Sometimes the locale isn't sufficient to determine unit preferences.
2259 There could be regional preferences, or a company could have specific
2260 preferences. Though probably uncommon, such differences could arise
2261 with the choice of English customary units outside of English-speaking
2262 countries. To address this, 'units' allows specifying definitions that
2263 depend on environment variable settings. The environment variables can
2264 be controled based on the current locale, or the user can set them to
2265 force a particular group of definitions.
2266 A conditional block of definitions in a units data file begins with
2268 either '!var' or '!varnot' following by an environment variable name
2269 and then a space separated list of values. The leading '!' must
2270 appear in the first column of a units data file, and the conditional
2271 block is terminated by '!endvar'. Definitions in blocks beginning with
2272 '!var' are executed only if the environment variable is exactly equal
2273 to one of the listed values. Definitions in blocks beginning with
2274 '!varnot' are executed only if the environment variable does not equal
2275 any of the list values.
2276 The inch has long been a customary measure of length in many places.
2278 The word comes from the Latin uncia meaning ``one twelfth,'' referring
2279 to its relationship with the foot. By the 20th century, the inch was
2280 officially defined in English-speaking countries relative to the yard,
2281 but until 1959, the yard differed slightly among those countries. In
2282 France the customary inch, which was displaced in 1799 by the meter,
2283 had a different length based on a french foot. These customary defini‐
2284 tions could be accommodated as follows:
2285 !var INCH_UNIT usa
2287 yard 3600|3937 m
2288 !endvar
2289 !var INCH_UNIT canada
2290 yard 0.9144 meter
2291 !endvar
2292 !var INCH_UNIT uk
2293 yard 0.91439841 meter
2294 !endvar
2295 !var INCH_UNIT canada uk usa
2296 foot 1|3 yard
2297 inch 1|12 foot
2298 !endvar
2299 !var INCH_UNIT france
2300 foot 144|443.296 m
2301 inch 1|12 foot
2302 line 1|12 inch
2303 !endvar
2304 !varnot INCH_UNIT usa uk france canada
2305 !message Unknown value for INCH_UNIT
2306 !endvar
2307 When 'units' reads the above definitions it will check the environment
2309 variable 'INCH_UNIT' and load only the definitions for the appropriate
2310 section. If 'INCH_UNIT' is unset or is not set to one of the four val‐
2311 ues listed then 'units' will run the last block. In this case that
2312 block uses the '!message' command to display a warning message. Alter‐
2313 natively that block could set default values.
2314 In order to create default values that are overridden by user settings
2316 the data file can use the '!set' command, which sets an environment
2317 variable only if it is not already set; these settings are only for
2318 the current 'units' invocation and do not persist. So if the example
2319 above were preceded by '!set INCH_UNIT france' then this would make
2320 'france' the default value for 'INCH_UNIT'. If the user had set the
2321 variable in the environment before invoking 'units', then 'units' would
2322 use the user's value.
2323 To link these settings to the user's locale you combine the '!set' com‐
2325 mand with the '!locale' command. If you wanted to combine the above
2326 example with suitable locales you could do by preceding the above defi‐
2327 nition with the following:
2328 !locale en_US
2330 !set INCH_UNIT usa
2331 !endlocale
2332 !locale en_GB
2333 !set INCH_UNIT uk
2334 !endlocale
2335 !locale en_CA
2336 !set INCH_UNIT canada
2337 !endlocale
2338 !locale fr_FR
2339 !set INCH_UNIT france
2340 !endlocale
2341 !set INCH_UNIT france
2342 These definitions set the overall default for 'INCH_UNIT' to 'france'
2344 and set default values for four locales appropriately. The overall
2345 default setting comes last so that it only applies when 'INCH_UNIT' was
2346 not set by one of the other commands or by the user.
2347 If the variable given after '!var' or '!varnot' is undefined then
2349 'units' prints an error message and ignores the definitions that fol‐
2350 low. Use '!set' to create defaults to prevent this situation from
2351 arising. The '-c' option only checks the definitions that are active
2352 for the current environment and locale, so when adding new definitions
2353 take care to check that all cases give rise to a well defined set of
2354 definitions.
2355
2357 The 'units' program uses the following environment variables:
2358 HOME Specifies the location of your home directory; it is used by
2360 'units' to find a personal units data file '.units'. On systems
2361 running Microsoft Windows, the file is 'unitdef.units', and if
2362 'HOME' does not exist, 'units' tries to determine your home
2363 directory from the 'HOMEDRIVE' and 'HOMEPATH' environment vari‐
2364 ables; if these variables do not exist, units finally tries
2365 'USERPROFILE'—typically 'C:\Users\username' (Windows Vista and
2366 Windows 7) or 'C:\Documents and Settings\username' (Windows XP).
2367 LC_CTYPE, LANG
2369 Checked to determine the locale if 'units' cannot obtain it from
2370 the operating system. Sections of the standard units data file
2371 are specific to certain locales.
2372 MYUNITSFILE
2374 Specifies your personal units data file. If this variable
2375 exists, 'units' uses its value rather than searching your home
2376 directory for '.units'. The personal units file will not be
2377 loaded if any data files are given using the '-f' option.
2378 PAGER Specifies the pager to use for help and for displaying the con‐
2380 formable units. The help function browses the units database
2381 and calls the pager using the '+n'n syntax for specifying a line
2382 number. The default pager is 'more'; 'PAGER' can be used to
2383 specify alternatives such as 'less', 'pg', 'emacs', or 'vi'.
2384 UNITS_ENGLISH
2386 Set to either 'US' or 'GB' to choose United States or British
2387 volume definitions, overriding the default from your locale.
2388 UNITSFILE
2390 Specifies the units data file to use (instead of the default).
2391 You can only specify a single units data file using this envi‐
2392 ronment variable. If units data files are given using the '-f'
2393 option, the file specified by 'UNITSFILE' will be not be loaded
2394 unless the '-f' option is given with the empty string
2395 ('units -f ""').
2396 UNITSLOCALEMAP
2398 Windows only; this variable has no effect on Unix-like systems.
2399 Specifies the units locale map file to use (instead of the
2400 default). This variable seldom needs to be set, but you can use
2401 it to ensure that the locale map file will be found if you spec‐
2402 ify a location for the units data file using either the '-f'
2403 option or the 'UNITSFILE' environment variable, and that loca‐
2404 tion does not also contain the locale map file.
2405 UNITS_SYSTEM
2407 This environment variable is used in the standard data file to
2408 select CGS measurement systems. Currently supported systems are
2409 'esu', 'emu', 'gauss[ian]', and 'si'. The default is 'si'.
2410
2412 The 'units' program uses two default data files: 'definitions.units'
2413 and 'currency.units'. The program can also use an optional personal
2414 units data file '.units' ('unitdef.units' under Windows) located in the
2415 user's home directory. The personal units data file is described in
2416 more detail in Units Data Files.
2417 On Unix-like systems, the data files are typically located in
2419 '/usr/share/units' if 'units' is provided with the operating system, or
2420 in '/usr/local/share/units' if 'units' is compiled from the source dis‐
2421 tribution. Note that the currency file 'currency.units' is a symbolic
2422 link to another location.
2423 On systems running Microsoft Windows, the files may be in the same
2425 locations if Unix-like commands are available, a Unix-like file struc‐
2426 ture is present (e.g., 'C:/usr/local'), and 'units' is compiled from
2427 the source distribution. If Unix-like commands are not available, a
2428 more common location is 'C:\Program Files (x86)\GNU\units' (for 64-bit
2429 Windows installations) or 'C:\Program Files\GNU\units' (for 32-bit
2430 installations).
2431 If 'units' is obtained from the GNU Win32 Project
2433 (http://gnuwin32.sourceforge.net/), the files are commonly in
2434 'C:\Program Files\GnuWin32\share\units'.
2435 If the default units data file is not an absolute pathname, 'units'
2437 will look for the file in the directory that contains the 'units' pro‐
2438 gram; if the file is not found there, 'units' will look in a directory
2439 '../share/units' relative to the directory with the 'units' program.
2440 You can determine the location of the files by running
2442 'units --version'. Running 'units --info' will give you additional
2443 information about the files, how 'units' will attempt to find them, and
2444 the status of the related environment variables.
2445
2447 The standard units data file is in Unicode, using UTF-8 encoding. Most
2448 definitions use only ASCII characters (i.e., code points U+0000 through
2449 U+007F); definitions using non-ASCII characters appear in blocks begin‐
2450 ning with '!utf8' and ending with '!endutf8'.
2451 When 'units' starts, it checks the locale to determine the character
2453 set. If 'units' is compiled with Unicode support and definitions; oth‐
2454 erwise these definitions are ignored. When Unicode support is active,
2455 'units' will check every line of all of the units data files for
2456 invalid or non-printing UTF-8 sequences; if such sequences occur,
2457 'units' ignores the entire line. In addition to checking validity,
2458 'units' determines the display width of non-ASCII characters to ensure
2459 proper positioning of the pointer in some error messages and to align
2460 columns for the 'search' and '?' commands.
2461 At present, 'units' does not support Unicode under Microsoft Windows.
2463 The UTF-16 and UTF-32 encodings are not supported on any systems.
2464 If definitions that contain non-ASCII characters are added to a units
2466 data file, those definitions should be enclosed within '!utf8' ...
2467 '!endutf8' to ensure that they are only loaded when Unicode support is
2468 available. As usual, the '!' must appear as the first character on
2469 the line. As discussed in Units Data Files, it's usually best to put
2470 such definitions in supplemental data files linked by an '!include'
2471 command or in a personal units data file.
2472 When Unicode support is not active, 'units' makes no assumptions about
2474 character encoding, except that characters in the range 00-7F hexadeci‐
2475 mal correspond to ASCII encoding. Non-ASCII characters are simply
2476 sequences of bytes, and have no special meanings; for definitions in
2477 supplementary units data files, you can use any encoding consistent
2478 with this assumption. For example, if you wish to use non-ASCII char‐
2479 acters in definitions when running 'units' under Windows, you can use a
2480 character set such as Windows ``ANSI'' (code page 1252 in the US and
2481 Western Europe). You can even use UTF-8, though some messages may be
2482 improperly aligned, and 'units' will not detect invalid UTF-8
2483 sequences. If you use UTF-8 encoding when Unicode support is not
2484 active, you should place any definitions with non-ASCII characters out‐
2485 side '!utf8' ... '!endutf8' blocks—otherwise, they will be ignored.
2486 Typeset material other than code examples usually uses the Unicode
2488 minus (U+2212) rather than the ASCII hyphen-minus operator (U+002D)
2489 used in 'units'; the figure dash (U+2012) and en dash (U+2013) are also
2490 occasionally used. To allow such material to be copied and pasted for
2491 interactive use or in units data files, 'units' converts these charac‐
2492 ters to U+002D before further processing. Because of this, none of
2493 these characters can appear in unit names.
2494
2496 If the 'readline' package has been compiled in, then when 'units' is
2497 used interactively, numerous command line editing features are avail‐
2498 able. To check if your version of 'units' includes 'readline', invoke
2499 the program with the '--version' option.
2500 For complete information about 'readline', consult the documentation
2502 for the 'readline' package. Without any configuration, 'units' will
2503 allow editing in the style of emacs. Of particular use with 'units'
2504 are the completion commands.
2505 If you type a few characters and then hit ESC followed by '?' then
2507 'units' will display a list of all the units that start with the char‐
2508 acters typed. For example, if you type 'metr' and then request comple‐
2509 tion, you will see something like this:
2510 You have: metr
2512 metre metriccup metrichorsepower metrictenth
2513 metretes metricfifth metricounce metricton
2514 metriccarat metricgrain metricquart metricyarncount
2515 You have: metr
2516 If there is a unique way to complete a unit name, you can hit the TAB
2518 key and 'units' will provide the rest of the unit name. If 'units'
2519 beeps, it means that there is no unique completion. Pressing the TAB
2520 key a second time will print the list of all completions.
2521 The readline library also keeps a history of the values you enter. You
2523 can move through this history using the up and down arrows. The his‐
2524 tory is saved to the file '.units_history' in your home directory so
2525 that it will persist across multiple 'units' invocations. If you wish
2526 to keep work for a certain project separate you can change the history
2527 filename using the '--history' option. You could, for example, make an
2528 alias for 'units' to 'units --history .units_history' so that 'units'
2529 would save separate history in the current directory. The length of
2530 each history file is limited to 5000 lines. Note also that if you run
2531 several concurrent copies of 'units' each one will save its new history
2532 to the history file upon exit.
2533
2535 The units program database includes currency exchange rates and prices
2536 for some precious metals. Of course, these values change over time,
2537 sometimes very rapidly, and 'units' cannot provide real-time values.
2538 To update the exchange rates, run 'units_cur', which rewrites the file
2539 containing the currency rates, typically '/var/lib/units/
2540 currency.units' or '/usr/local/com/units/currency.units' on a Unix-like
2541 system or 'C:\Program Files (x86)\GNU\units\definitions.units' on a
2542 Windows system.
2543 This program requires Python (https://www.python.org); either version 2
2545 or 3 will work. The program must be run with suitable permissions to
2546 write the file. To keep the rates updated automatically, run it using
2547 a cron job on a Unix-like system, or a similar scheduling program on a
2548 different system.
2549 Reliable free sources of currency exchange rates have been annoyingly
2551 ephemeral. The program currently supports several sources:
2552 * FloatRates (https://www/floatrates.com). The US dollar ('USD') is
2554 the default base currency. You can change the base currency with
2555 the '-b' option described below. Allowable base currencies are
2556 listed on the FloatRates website. Exchange rates update daily.
2557 * The European Central Bank (https://www.ecb.europa.eu). The base
2559 currency is always the euro ('EUR'). Exchange rates update daily.
2560 This source offers a more limited list of currencies than the oth‐
2561 ers.
2562 * Fixer (https://fixer.io). Registration for a free API key is
2564 required. With a free API key, base currency is the euro; exchange
2565 rates are updated hourly, the service has a limit of 1,000 API
2566 calls per month, and SSL encryption (https protocol) is not avail‐
2567 able. Most of these restrictions are eliminated or reduced with
2568 paid plans.
2569 * open exchange rates (https://openexchangerates.org). Registration
2571 for a free API key is required. With a free API key, the base cur‐
2572 rency is the US dollar; exchange rates are updated hourly, and
2573 there is a limit of 1,000 API calls per month. Most of these
2574 restrictions are eliminated or reduced with paid plans.
2575 The default source is FloatRates; you can select a different one using
2577 '-s' option described below.
2578 Precious metals pricing is obtained from Packetizer (www.packe‐
2580 tizer.com). This site updates once per day.
2581 You invoke 'units_cur' like this:
2583 units_cur [options] [outfile]
2585 By default, the output is written to the default currency file
2587 described above; this is usually what you want, because this is where
2588 'units' looks for the file. If you wish, you can specify a different
2589 filename on the command line and 'units_cur' will write the data to
2590 that file. If you give '-' for the file it will write to standard out‐
2591 put.
2592 The following options are available:
2594 -h, --help
2596 Print a summary of the options for 'units_cur'.
2597 -V, --version
2599 Print the 'units_cur' version number.
2600 -v, --verbose
2602 Give slightly more verbose output when attempting to update cur‐
2603 rency exchange rates.
2604 -s source, --source source
2606 Specify the source for currency exchange rates; currently sup‐
2607 ported values are 'floatrates' (for FloatRates), 'eubank' (for
2608 the European Central Bank), 'fixer' (for Fixer), and
2609 'openexchangerates' (for open exchange rates); the last two
2610 require an API key to be given with the '-k' option.
2611 -b base, --base base
2613 Set the base currency (when allowed by the site providing the
2614 data). base should be a 3-letter ISO currency code, e.g.,
2615 'USD'. The specified currency will be the primitive currency
2616 unit used by 'units'. You may find it convenient to specify
2617 your local currency. Conversions may be more accurate and you
2618 will be able to convert to your currency by simply hitting Enter
2619 at the 'You want:' prompt. This option is ignored if the source
2620 does not allow specifying the base currency. (Currently only
2621 floatrates supports this option.)
2622 -k key, --key key
2624 Set the API key to key for sources that require it.
2625
2627 unit definition
2628 Define a regular unit.
2629 prefix- definition
2631 Define a prefix.
2632 funcname(var) noerror units=[in-units,out-units] domain=[x1,x2]
2634 range=[y1,y2] definition(var) ; inverse(funcname)
2635 Define a nonlinear unit or unit function. The four optional
2636 keywords 'noerror', 'units=', 'range=' and 'domain=' can appear
2637 in any order. The definition of the inverse is optional.
2638 tabname[out-units] noerror pair-list
2640 Define a piecewise linear unit. The pair list gives the points
2641 on the table listed in ascending order. The 'noerror' keyword
2642 is optional.
2643 !endlocale
2645 End a block of definitions beginning with '!locale'
2646 !endutf8
2648 End a block of definitions begun with '!utf8'
2649 !endvar
2651 End a block of definitions begun with '!var' or '!varnot'
2652 !include file
2654 Include the specified file.
2655 !locale value
2657 Load the following definitions only of the locale is set to
2658 value.
2659 !message text
2661 Display text when the database is read unless the quiet option
2662 ('-q') is enabled. If you omit text then units will display a
2663 blank line. Messages will also appear in the log file.
2664 !prompt text
2666 Prefix the 'You have:' prompt with the specified text. If you
2667 omit text then any existing prefix is canceled.
2668 !set variable value
2670 Sets the environment variable, variable, to the specified value
2671 only if it is not already set.
2672 !unitlist alias definition
2674 Define a unit list alias.
2675 !utf8 Load the following definitions only if 'units' is running with
2677 UTF-8 enabled.
2678 !var envar value-list
2680 Load the block of definitions that follows only if the environ‐
2681 ment variable envar is set to one of the values listed in the
2682 space-separated value list. If envar is not set, 'units' prints
2683 an error message and ignores the block of definitions.
2684 !varnot envar value-list
2686 Load the block of definitions that follows only if the environ‐
2687 ment variable envar is set to value that is not listed in the
2688 space-separated value list. If envar is not set, 'units' prints
2689 an error message and ignores the block of definitions.
2690
2693 /usr/share/units/definitions.units — the standard units data file
2694
2696 20 October 2018 UNITS(1)