1This manual is for GNU Units (version 2.00), which performs units
2conversions and units calculations. A copy of the license is in‐
3cluded in the section entitled ‘‘GNU Free Documentation Li‐
4UNITS(1) General Commands Manual UNITS(1)
5cense’’.
9
11 units — unit conversion and calculation program
12
14 'units' [options] [from-unit [to-unit]]
15
17 The 'units' program converts quantities expressed in various systems of
18 measurement to their equivalents in other systems of measurement. Like
19 many similar programs, it can handle multiplicative scale changes. It
20 can also handle nonlinear conversions such as Fahrenheit to Celsius.
21 See the examples below. The program can also perform conversions from
22 and to sums of units, such as converting between meters and feet plus
23 inches.
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.
32 The units are defined in an external data file. You can use the exten‐
34 sive data file that comes with this program, or you can provide your
35 own data file to suit your needs. You can also use your own data file
36 to supplement the standard data file.
37 Basic operation is simple: you enter the units that you want to convert
39 from and the units that you want to convert to. You can use the pro‐
40 gram interactively with prompts, or you can use it from the command
41 line.
42
44 To invoke units for interactive use, type 'units' at your shell prompt.
45 The program will print something like this:
46 Currency exchange rates from 04/23/12
48 2516 units, 85 prefixes, 65 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 the
57 tab key can be used to complete unit names. See Readline Support for
58 more information about 'readline'. To quit the program press Ctrl-C or
59 Ctrl-D under Unix. Under Windows press Ctrl-Z.
60 The answer 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 Named dimensionless units are not treated as dimensionless in other
157 contexts. They cannot be used as exponents so for example,
158 'meter^radian' is not allowed.
159 If you want a list of options you can type '?' at the 'You want:'
161 prompt. The program will display a list of named units that are con‐
162 formable with the unit that you entered at the 'You have:' prompt
163 above. Conformable unit combinations will not appear on this list.
164 Typing 'help' at either prompt displays a short help message. You can
166 also type 'help' followed by a unit name. This will invoke a pager on
167 the units data base at the point where that unit is defined. You can
168 read the definition and comments that may give more details or histori‐
169 cal information about the unit. (You can generally quit out of the
170 page by pressing 'q'.)
171 Typing 'search' text will display a list of all of the units whose
173 names contain text as a substring along with their definitions. This
174 may help in the case where you aren't sure of the right unit name.
175
177 The 'units' program can perform units conversions non-interactively
178 from the command line. To do this, type the command, type the original
179 unit expression, and type the new units you want. If a units expres‐
180 sion contains non-alphanumeric characters, you may need to protect it
181 from interpretation by the shell using single or double quote charac‐
182 ters.
183 If you type
185 units "2 liters" quarts
187 then 'units' will print
189 * 2.1133764
191 / 0.47317647
192 and then exit. The output tells you that 2 liters is about 2.1 quarts,
194 or alternatively that a quart is about 0.47 times 2 liters.
195 If the conversion is successful, then 'units' will return success
197 (zero) to the calling environment. If you enter non-conformable units
198 then 'units' will print a message giving the reduced form of each unit
199 and it will return failure (nonzero) to the calling environment.
200 When you invoke 'units' with only one argument, it will print out the
202 definition of the specified unit. It will return failure if the unit
203 is not defined and success if the unit is defined.
204
206 The conversion information is read from a units data file that is
207 called 'definitions.units' and is usually located in the
208 '/usr/share/units' directory. If you invoke 'units' with the '-V'
209 option, it will print the location of this file. The default file
210 includes definitions for all familiar units, abbreviations and metric
211 prefixes. It also includes many obscure or archaic units.
212 Many constants of nature are defined, including these:
214 pi ratio of circumference to diameter
216 c speed of light
217 e charge on an electron
218 force acceleration of gravity
219 mole Avogadro's number
220 water pressure per unit height of water
221 Hg pressure per unit height of mercury
222 au astronomical unit
223 k Boltzman's constant
224 mu0 permeability of vacuum
225 epsilon0 permittivity of vacuum
226 G Gravitational constant
227 mach speed of sound
228 The standard data file includes atomic masses for all of the elements
230 and numerous other constants. Also included are the densities of vari‐
231 ous ingredients used in baking so that '2 cups flour_sifted' can be
232 converted to 'grams'. This is not an exhaustive list. Consult the
233 units data file to see the complete list, or to see the definitions
234 that are used.
235 The 'pound' is a unit of mass. To get force, multiply by the force
237 conversion unit 'force' or use the shorthand 'lbf'. (Note that 'g' is
238 already taken as the standard abbreviation for the gram.) The unit
239 'ounce' is also a unit of mass. The fluid ounce is 'fluidounce' or
240 'floz'. British capacity units that differ from their US counterparts,
241 such as the British Imperial gallon, are prefixed with 'br'. Currency
242 is prefixed with its country name: 'belgiumfranc', 'britainpound'.
243 When searching for a unit, if the specified string does not appear
245 exactly as a unit name, then the 'units' program will try to remove a
246 trailing 's', 'es'. Next units will replace a trailing 'ies' with 'y'.
247 If that fails, 'units' will check for a prefix. The database includes
248 all of the standard metric prefixes. Only one prefix is permitted per
249 unit, so 'micromicrofarad' will fail. However, prefixes can appear
250 alone with no unit following them, so 'micro*microfarad' will work, as
251 will 'micro microfarad'.
252 To find out which units and prefixes are available, read the standard
254 units data file, which is extensively annotated.
255 English Customary Units
257 English customary units differ in various ways in different regions.
258 In Britain a complex system of volume measurements featured different
259 gallons for different materials such as a wine gallon and ale gallon
260 that different by twenty percent. This complexity was swept away in
261 1824 by a reform that created an entirely new gallon, the British Impe‐
262 rial gallon defined as the volume occupied by ten pounds of water.
263 Meanwhile in the USA the gallon is derived from the 1707 Winchester
264 wine gallon, which is 231 cubic inches. These gallons differ by about
265 twenty percent. By default if 'units' runs in the 'en_GB' locale you
266 will get the British volume measures. If it runs in the 'en_US' locale
267 you will get the US volume measures. In other locales the default val‐
268 ues are the US definitions. If you wish to force different definitions
269 then set the environment variable 'UNITS_ENGLISH' to either 'US' or
270 'GB' to set the desired definitions independent of the locale.
271 Before 1959, the value of a yard (and other units of measure defined in
273 terms of it) differed slightly among English-speaking countries. In
274 1959, Australia, Canada, New Zealand, the United Kingdom, the United
275 States, and South Africa adopted the Canadian value of 1 yard =
276 0.9144 m (exactly), which was approximately halfway between the values
277 used by the UK and the US; it had the additional advantage of making
278 1 inch = 2.54 cm (exactly). This new standard was termed the Interna‐
279 tional Yard. Australia, Canada, and the UK then defined all customary
280 lengths in terms of the International Yard (Australia did not define
281 the furlong or rod); because many US land surveys were in terms of the
282 pre-1959 units, the US continued to define customary surveyors' units
283 (furlong, chain, rod, and link) in terms of the previous value for the
284 foot, which was termed the US survey foot. The US defined a US survey
285 mile as 5280 US survey feet, and defined a statute mile as a US survey
286 mile. The US values for these units differ from the international val‐
287 ues by about 2 ppm.
288 The 'units' program uses the international values for these units; the
290 US values can be obtained by using either the 'US' or the 'survey' pre‐
291 fix. In either case, the simple familiar relationships among the units
292 are maintained, e.g., 1 'furlong' = 660 'ft', and 1 'USfurlong' = 660
293 'USft', though the metric equivalents differ slightly between the two
294 cases. The 'US' prefix or the 'survey' prefix can also be used to
295 obtain the US survey mile and the value of the US yard prior to 1959,
296 e.g., 'USmile' or 'surveymile' (but not 'USsurveymile'). To get the US
297 value of the statute mile, use either 'USstatutemile' or 'USmile'.
298 Except for distances that extend over hundreds of miles (such as in the
300 US State Plane Coordinate System), the differences in the miles are
301 usually insignificant:
302 You have: 100 surveymile - 100 mile
304 You want: inch
305 * 12.672025
306 / 0.078913984
307 The pre-1959 UK values for these units can be obtained with the prefix
309 'UK'.
310 In the US, the acre is officially defined in terms of the US survey
312 foot, but 'units' uses a definition based on the international foot.
313 If you want the official US acre use 'USacre' and similarly use
314 'USacrefoot' for the official US version of that unit. The difference
315 between these units is about 4 parts per million.
316
318 Operators
319 You can enter more complicated units by combining units with operations
320 such as powers, multiplication, division, addition, subtraction, and
321 parentheses for grouping. You can use the customary symbols for these
322 operators when 'units' is invoked with its default options. Addition‐
323 ally, 'units' supports some extensions, including high priority multi‐
324 plication using a space, and a high priority numerical
325 division operator ('|') that can simplify some expressions.
326 Powers of units can be specified using the '^' character as shown in
328 the following example, or by simple concatenation of a unit and its
329 exponent: 'cm3' is equivalent to 'cm^3'; if the exponent is more than
330 one digit, the '^' is required. An exponent like '2^3^2' is evaluated
331 right to left as usual. The '^' operator has the second highest prece‐
332 dence. You can also use '**' as an exponent operator.
333 You have: cm^3
335 You want: gallons
336 * 0.00026417205
337 / 3785.4118
338 You have: arabicfoot * arabictradepound * force
340 You want: ft lbf
341 * 0.7296
342 / 1.370614
343 You multiply units using a space or an asterisk ('*'). The example
345 above shows both forms. You can divide units using the slash ('/') or
346 with 'per'.
347 You have: furlongs per fortnight
349 You want: m/s
350 * 0.00016630986
351 / 6012.8727
352 When a unit includes a prefix, exponent operators apply to the combina‐
354 tion, so 'centimeter^3' gives cubic centimeters. If you separate the
355 prefix from the unit with any multiplication operator, such as 'centi
356 meter^3', then the prefix is treated as a separate unit, so the expo‐
357 nent does not apply. The second example would be a hundredth of a
358 cubic meter, not a centimeter.
359 Multiplication using a space has a higher precedence than division
361 using a slash and is evaluated left to right; in effect, the first '/'
362 character marks the beginning of the denominator of a unit expression.
363 This makes it simple to enter a quotient with several terms in the
364 denominator: 'W / m^2 Hz'. If you multiply with '*' then you must
365 group the terms in the denominator with parentheses: 'W / (m^2 * Hz)'.
366 The higher precedence of the space operator may not always be advanta‐
368 geous. For example, 'm/s s/day' is equivalent to 'm / s s day' and has
369 dimensions of length per time cubed. Similarly, '1/2 meter' refers to
370 a unit of reciprocal length equivalent to 0.5/meter, perhaps not what
371 you would intend if you entered that expression. The '*' operator is
372 convenient for multiplying a sequence of quotients. With the '*' oper‐
373 ator, the example above becomes 'm/s * s/day', which is equivalent to
374 'm/day'. Similarly, you could write '1/2 * meter' to get half a meter.
375 Alternatively, parentheses can be used for grouping: you could write
376 '(1/2) meter' to get half a meter. See Complicated Unit Expressions
377 for an illustration of the various options.
378 The 'units' program supports another option for numerical fractions.
380 You can indicate division of numbers with the vertical bar ('|'), so if
381 you wanted half a meter you could write '1|2 meter'. This operator has
382 the highest precedence, so you can write the square root of two thirds
383 '2|3^1|2'. You cannot use the vertical bar to indicate division of
384 non-numerical units (e.g., 'm|s' results in an error message).
385 You have: 1|2 inch
387 You want: cm
388 * 1.27
389 / 0.78740157
390 You can use parentheses for grouping:
392 You have: (1/2) kg / (kg/meter)
394 You want: league
395 * 0.00010356166
396 / 9656.0833
397 Sums and Differences of Units
399 Outside of the SI, it is sometimes desirable to add values of different
400 units. You may also wish to use 'units' as a calculator that keeps
401 track of units. Sums of conformable units are written with the '+'
402 character, and differences with the '-' character.
403 You have: 2 hours + 23 minutes + 32 seconds
405 You want: seconds
406 * 8612
407 / 0.00011611705
408 You have: 12 ft + 3 in
410 You want: cm
411 * 373.38
412 / 0.0026782366
413 You have: 2 btu + 450 ft lbf
415 You want: btu
416 * 2.5782804
417 / 0.38785542
418 The expressions that are added or subtracted must reduce to identical
420 expressions in primitive units, or an error message will be displayed:
421 You have: 12 printerspoint - 4 heredium
423 ^
424 Illegal sum of non-conformable units
425 As usual, the precedence for '+' and '-' is lower than that of the
427 other operators. A fractional quantity such as 2 1/2 cups can be given
428 as '(2+1|2) cups'; the parentheses are necessary because multiplication
429 has higher precedence than addition. If you omit the parentheses,
430 'units' attempts to add '2' and '1|2 cups', and you get an error mes‐
431 sage:
432 You have: 2+1|2 cups
434 ^
435 Illegal sum or difference of non-conformable units
436 The expression could also be correctly written as '(2+1/2) cups'. If
438 you write '2 1|2 cups' the space is interpreted as multiplication so
439 the result is the same as '1 cup'.
440 The '+' and '-' characters sometimes appears in exponents like
442 '3.43e+8'. This leads to an ambiguity in an expression like '3e+2 yC'.
443 The unit 'e' is a small unit of charge, so this can be regarded as
444 equivalent to '(3e+2) yC' or '(3 e)+(2 yC)'. This ambiguity is
445 resolved by always interpreting '+' and '-' as part of an exponent if
446 possible.
447 Numbers as Units
449 For 'units', numbers are just another kind of unit. They can appear as
450 many times as you like and in any order in a unit expression. For
451 example, to find the volume of a box that is 2 ft by 3 ft by 12 ft in
452 steres, you could do the following:
453 You have: 2 ft 3 ft 12 ft
455 You want: stere
456 * 2.038813
457 / 0.49048148
458 You have: $ 5 / yard
460 You want: cents / inch
461 * 13.888889
462 / 0.072
463 And the second example shows how the dollar sign in the units conver‐
465 sion can precede the five. Be careful: 'units' will interpret '$5'
466 with no space as equivalent to 'dollar^5'.
467 Built-in Functions
469 Several built-in functions are provided: 'sin', 'cos', 'tan', 'ln',
470 'log', 'log2', 'exp', 'acos', 'atan' and 'asin'. The 'sin', 'cos', and
471 'tan' functions require either a dimensionless argument or an argument
472 with dimensions of angle.
473 You have: sin(30 degrees)
475 You want:
476 Definition: 0.5
477 You have: sin(pi/2)
479 You want:
480 Definition: 1
481 You have: sin(3 kg)
483 ^
484 Unit not dimensionless
485 The other functions on the list require dimensionless arguments. The
487 inverse trigonometric functions return arguments with dimensions of
488 angle.
489 If you wish to take roots of units, you may use the 'sqrt' or
491 'cuberoot' functions. These functions require that the argument have
492 the appropriate root. You can obtain higher roots by using fractional
493 exponents:
494 You have: sqrt(acre)
496 You want: feet
497 * 208.71074
498 / 0.0047913202
499 You have: (400 W/m^2 / stefanboltzmann)^(1/4)
501 You have:
502 Definition: 289.80882 K
503 You have: cuberoot(hectare)
505 ^
506 Unit not a root
507 Complicated Unit Expressions
509 The 'units' program is especially helpful in ensuring accuracy and
510 dimensional consistency when converting lengthy unit expressions. For
511 example, one form of the Darcy-Weisbach fluid-flow equation is
512 Delta P = (8 / pi)^2 (rho fLQ^2) / d^5,
514 where Delta P is the pressure drop, rho is the mass density, f is the
516 (dimensionless) friction factor, L is the length of the pipe, Q is the
517 volumetric flow rate, and d is the pipe diameter. It might be desired
518 to have the equation in the form
519 Delta P = A1 rho fLQ^2 / d^5
521 that accepted the user's normal units; for typical units used in the
523 US, the required conversion could be something like
524 You have: (8/pi^2)(lbm/ft^3)ft(ft^3/s)^2(1/in^5)
526 You want: psi
527 * 43.533969
528 / 0.022970568
529 The parentheses allow individual terms in the expression to be entered
531 naturally, as they might be read from the formula. Alternatively, the
532 multiplication could be done with the '*' rather than a space; then
533 parentheses are needed only around 'ft^3/s' because of its exponent:
534 You have: 8/pi^2 * lbm/ft^3 * ft * (ft^3/s)^2 /in^5
536 You want: psi
537 * 43.533969
538 / 0.022970568
539 Without parentheses, and using spaces for multiplication, the previous
541 conversion would need to be entered as
542 You have: 8 lb ft ft^3 ft^3 / pi^2 ft^3 s^2 in^5
544 You want: psi
545 * 43.533969
546 / 0.022970568
547 Backwards Compatibility:
549 '*' and '-' The original 'units' assigned multiplication a higher
550 precedence than division using the slash. This differs from the usual
551 precedence rules, which give multiplication and division equal prece‐
552 dence, and can be confusing for people who think of units as a calcula‐
553 tor.
554 The star operator ('*') included in this 'units' program has, by
556 default, the same precedence as division, and hence follows the usual
557 precedence rules. For backwards compatibility you can invoke 'units'
558 with the '--oldstar' option. Then '*' has a higher precedence than
559 division, and the same precedence as multiplication using the space.
560 Historically, the hyphen ('-') has been used in technical publications
562 to indicate products of units, and the original 'units' program treated
563 it as a multiplication operator. Because 'units' provides several
564 other ways to obtain unit products, and because '-' is a subtraction
565 operator in general algebraic expressions, 'units' treats the binary
566 '-' as a subtraction operator by default. For backwards compatibility
567 use the '--product' option, which causes 'units' to treat the binary
568 '-' operator as a product operator. When '-' is a multiplication oper‐
569 ator it has the same precedence as multiplication with a space, giving
570 it a higher precedence than division.
571 When '-' is used as a unary operator it negates its operand. Regard‐
573 less of the 'units' options, if '-' appears after '(' or after '+' then
574 it will act as a negation operator. So you can always compute 20
575 degrees minus 12 minutes by entering '20 degrees + -12 arcmin'. You
576 must use this construction when you define new units because you cannot
577 know what options will be in force when your definition is processed.
578
580 Nonlinear units are represented using functional notation. They make
581 possible nonlinear unit conversions such as temperature.
582 Temperature Conversions
584 Conversions between temperatures are different from linear conversions
585 between temperature increments—see the example below. The absolute
586 temperature conversions are handled by units starting with 'temp', and
587 you must use functional notation. The temperature-increment conver‐
588 sions are done using units starting with 'deg' and they do not require
589 functional notation.
590 You have: tempF(45)
592 You want: tempC
593 7.2222222
594 You have: 45 degF
596 You want: degC
597 * 25
598 / 0.04
599 Think of 'tempF(x)' not as a function but as a notation that indicates
601 that x should have units of 'tempF' attached to it. See Defining Non‐
602 linear Units. The first conversion shows that if it's 45 degrees
603 Fahrenheit outside, it's 7.2 degrees Celsius. The second conversion
604 indicates that a change of 45 degrees Fahrenheit corresponds to a
605 change of 25 degrees Celsius. The conversion from 'tempF(x)' is to
606 absolute temperature, so that
607 You have: tempF(45)
609 You want: degR
610 * 504.67
611 / 0.0019814929
612 gives the same result as
614 You have: tempF(45)
616 You want: tempR
617 * 504.67
618 / 0.0019814929
619 But if you convert 'tempF(x)' to 'degC', the output is probably not
621 what you expect:
622 You have: tempF(45)
624 You want: degC
625 * 280.37222
626 / 0.0035666871
627 The result is the temperature in K, because 'degC' is defined as 'K',
629 the Kelvin. For consistent results, use the 'tempX' units when convert‐
630 ing to a temperature rather than converting a temperature increment.
631 Other Nonlinear Units
633 Some other examples of nonlinear units are numerous different ring
634 sizes and wire gauges, the grit sizes used for abrasives, the decibel
635 scale, shoe size, scales for the density of sugar (e.g. baume). The
636 standard data file also supplies units for computing the area of a cir‐
637 cle and the volume of a sphere. See the standard units data file for
638 more details. Wire gauges with multiple zeroes are signified using
639 negative numbers where two zeroes is '-1'. Alternatively, you can use
640 the synonyms 'g00', 'g000', and so on that are defined in the standard
641 units data file.
642 You have: wiregauge(11)
644 You want: inches
645 * 0.090742002
646 / 11.020255
647 You have: brwiregauge(g00)
649 You want: inches
650 * 0.348
651 / 2.8735632
652 You have: 1 mm
654 You want: wiregauge
655 18.201919
656 You have: grit_P(600)
658 You want: grit_ansicoated
659 342.76923
660 The last example shows the conversion from P graded sand paper, which
662 is the European standard and may be marked ``P600'' on the back, to the
663 USA standard.
664 You can compute the area of a circle using the nonlinear unit,
666 'circlearea'. You can also do this using the circularinch or cir‐
667 cleinch. The next example shows two ways to compute the area of a cir‐
668 cle with a five inch radius and one way to compute the volume of a
669 sphere with a radius of one meter.
670 You have: circlearea(5 in)
672 You want: in2
673 * 78.539816
674 / 0.012732395
675 You have: 10^2 circleinch
677 You want: in2
678 * 78.539816
679 / 0.012732395
680 You have: spherevol(meter)
682 You want: ft3
683 * 147.92573
684 / 0.0067601492
685
687 Outside of the SI, it is sometimes desirable to convert a single unit
688 to a sum of units—for example, feet to feet plus inches. The conver‐
689 sion from sums of units was described in Sums and Differences of Units
690 and is a simple matter of adding the units with the '+' sign:
691 You have: 12 ft + 3 in + 3|8 in
693 You want: ft
694 * 12.28125
695 / 0.081424936
696 Although you can similarly write a sum of units to convert to, the
698 result will not be the conversion to the units in the sum, but rather
699 the conversion to the particular sum that you have entered:
700 You have: 12.28125 ft
702 You want: ft + in + 1|8 in
703 * 11.228571
704 / 0.089058524
705 The unit expression given at the 'You want:' prompt is equivalent to
707 asking for conversion to multiples of '1 ft + 1 in + 1|8 in', which is
708 1.09375 ft, so the conversion in the previous example is equivalent to
709 You have: 12.28125 ft
711 You want: 1.09375 ft
712 * 11.228571
713 / 0.089058524
714 In converting to a sum of units like miles, feet and inches, you typi‐
716 cally want the largest integral value for the first unit, followed by
717 the largest integral value for the next, and the remainder converted to
718 the last unit. You can do this conversion easily with 'units' using a
719 special syntax for lists of units. You must list the desired units in
720 order from largest to smallest, separated by the semicolon (';') char‐
721 acter:
722 You have: 12.28125 ft
724 You want: ft;in;1|8 in
725 12 ft + 3 in + 3|8 in
726 The conversion always gives integer coefficients on the units in the
728 list, except possibly the last unit when the conversion is not exact:
729 You have: 12.28126 ft
731 You want: ft;in;1|8 in
732 12 ft + 3 in + 3.00096 * 1|8 in
733 The order in which you list the units is important:
735 You have: 3 kg
737 You want: oz;lb
738 105 oz + 0.051367866 lb
739 You have: 3 kg
741 You want: lb;oz
742 6 lb + 9.8218858 oz
743 Listing ounces before pounds produces a technically correct result, but
745 not a very useful one. You must list the units in descending order of
746 size in order to get the most useful result.
747 Ending a unit list with the separator ';' has the same effect as
749 repeating the last unit on the list, so 'ft;in;1|8 in;' is equivalent
750 to 'ft;in;1|8 in;1|8 in'. With the example above, this gives
751 You have: 12.28126 ft
753 You want: ft;in;1|8 in;
754 12 ft + 3 in + 3|8 in + 0.00096 * 1|8 in
755 in effect separating the integer and fractional parts of the coeffi‐
757 cient for the last unit. If you instead prefer to round the last coef‐
758 ficient to an integer you can do this with the '--round' ('-r') option.
759 With the previous example, the result is
760 You have: 12.28126 ft
762 You want: ft;in;1|8 in
763 12 ft + 3 in + 3|8 in (rounded down to nearest 1|8 in)
764 When you use the '-r' option, repeating the last unit on the list has
766 no effect (e.g., 'ft;in;1|8 in;1|8 in' is equivalent to 'ft;in;1|8
767 in'), and hence neither does ending a list with a ';'. With a single
768 unit and the '-r' option, a terminal ';' does have an effect: it causes
769 'units' to treat the single unit as a list and produce a rounded value
770 for the single unit. Without the extra ';', the '-r' option has no
771 effect on single unit conversions. This example shows the ouput using
772 the '-r' option:
773 You have: 12.28126 ft
775 You want: in
776 * 147.37512
777 / 0.0067854058
778 You have: 12.28126 ft
780 You want: in;
781 147 in (rounded down to nearest in)
782 Each unit that appears in the list must be conformable with the first
784 unit on the list, and of course the listed units must also be com‐
785 formable with the You have unit that you enter.
786 You have: meter
788 You want: ft;kg
789 ^
790 conformability error
791 ft = 0.3048 m
792 kg = 1 kg
793 You have: meter
795 You want: lb;oz
796 conformability error
797 1 m
798 0.45359237 kg
799 In the first case, 'units' reports the disagreement between units
801 appearing on the list. In the second case, 'units' reports disagree‐
802 ment between the unit you entered and the desired conversion. This
803 conformability error is based on the first unit on the unit list.
804 Other common candidates for conversion to sums of units are angles and
806 time:
807 You have: 23.437754 deg
809 You want; deg;arcmin;arcsec
810 23 deg + 26 arcmin + 15.9144 arcsec
811 You have: 7.2319 hr
813 You want: hr;min;sec
814 7 hr + 13 min + 54.84 sec
815 In North America, recipes for cooking typically measure ingredients by
817 volume, and use units that are not always convenient multiples of each
818 other. Suppose that you have a recipe for 6 and you wish to make a
819 portion for 1. If the recipe calls for 2 1/2 cups of an ingredient,
820 you might wish to know the measurements in terms of measuring devices
821 you have available, you could use 'units' and enter
822 You have: (2+1|2) cup / 6
824 You want: cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
825 1|3 cup + 1 tbsp + 1 tsp
826 By default, if a unit in a list begins with fraction of the form 1|x
828 and its multiplier is an integer, the fraction is given as the product
829 of the multiplier and the numerator; for example,
830 You have: 12.28125 ft
832 You want: ft;in;1|8 in;
833 12 ft + 3 in + 3|8 in
834 In many cases, such as the example above, this is what is wanted, but
836 sometimes it is not. For example, a cooking recipe for 6 might call
837 for 5 1/4 cup of an ingredient, but you want a portion for 2, and your
838 1-cup measure is not available; you might try
839 You have: (5+1|4) cup / 3
841 You want: 1|2 cup;1|3 cup;1|4 cup
842 3|2 cup + 1|4 cup
843 This result might be fine for a baker who has a 1 1/2-cup measure (and
845 recognizes the equivalence), but it may not be as useful to someone
846 with more limited set of measures, who does want to do additional cal‐
847 culations, and only wants to know ``How many 1/2-cup measures to I need
848 to add?'' After all, that's what was actually asked. With the
849 '--show-factor' option, the factor will not be combined with a unity
850 numerator, so that you get
851 You have: (5+1|4) cup / 3
853 You want: 1|2 cup;1|3 cup;1|4 cup
854 3 * 1|2 cup + 1|4 cup
855 A user-specified fractional unit with a numerator other than 1 is never
857 overridden, however—if a unit list specifies '3|4 cup;1|2 cup', a
858 result equivalent to 1 1/2 cups will always be shown as '2 * 3|4 cup'
859 whether or not the '--show-factor' option is given.
860 Some applications for unit lists may be less obvious. Suppose that you
862 have a postal scale and wish to ensure that it's accurate at 1 oz, but
863 have only metric calibration weights. You might try
864 You have: 1 oz
866 You want: 100 g;50 g; 20 g;10 g;5 g;2 g;1 g;
867 20 g + 5 g + 2 g + 1 g + 0.34952312 * 1 g
868 You might then place one each of the 20 g, 5 g, 2 g, and 1 g weights on
870 the scale and hope that it indicates close to
871 You have: 20 g + 5 g + 2 g + 1 g
873 You want: oz;
874 0.98767093 oz
875 Appending ';' to 'oz' forces a one-line display that includes the unit;
877 here the integer part of the result is zero, so it is not displayed.
878 A unit list such as
880 cup;1|2 cup;1|3 cup;1|4 cup;tbsp;tsp;1|2 tsp;1|4 tsp
882 can be tedious to enter. The 'units' program provides shorthand names
884 for some common combinations:
885 hms hours, minutes, seconds
887 dms angle: degrees, minutes, seconds
888 time years, days, hours, minutes and seconds
889 usvol US cooking volume: cups and smaller
890 Using these shorthands, or unit list aliases, you can do the following
892 conversions:
893 You have: anomalisticyear
895 You want: time
896 1 year + 25 min + 3.4653216 sec
897 You have: 1|6 cup
898 You want: usvol
899 2 tbsp + 2 tsp
900 You cannot combine a unit list alias with other units: it must appear
902 alone at the 'You want:' prompt.
903 You can display the definition of a unit list alias by entering it at
905 the 'You have:' prompt:
906 You have: dms
908 Definition: unit list, deg;arcmin;arcsec
909 When you specify compact output with '--compact', '--terse' or '-t' and
911 perform conversion to a unit list, 'units' lists the conversion factors
912 for each unit in the list, separated by semicolons.
913 You have: year
915 You want: day;min;sec
916 365;348;45.974678
917 Unlike the case of regular output, zeros are included in this output
919 list:
920 You have: liter
922 You want: cup;1|2 cup;1|4 cup;tbsp
923 4;0;0;3.6280454
924
926 You invoke 'units' like this:
927 units [options] [from-unit [to-unit]]
929 If the from-unit and to-unit are omitted, then the program will use
931 interactive prompts to determine which conversions to perform. See
932 Interactive Use. If both from-unit and to-unit are given, 'units' will
933 print the result of that single conversion and then exit. If only
934 from-unit appears on the command line, 'units' will display the defini‐
935 tion of that unit and exit. Units specified on the command line may
936 need to be quoted to protect them from shell interpretation and to
937 group them into two arguments. See Command Line Use.
938 The following options allow you to read in an alternative units file,
940 check your units file, or change the output format:
941 -c, --check
943 Check that all units and prefixes defined in the units data file
944 reduce to primitive units. Print a list of all units that can‐
945 not be reduced. Also display some other diagnostics about sus‐
946 picious definitions in the units data file. Only definitions
947 active in the current locale are checked. You should always run
948 'units' with this option after modifying a units data file.
949 --check-verbose, --verbose-check
951 Like the '--check' option, this option prints a list of units
952 that cannot be reduced. But to help find unit definitions that
953 cause endless loops, it lists the units as they are checked. If
954 'units' hangs, then the last unit to be printed has a bad defi‐
955 nition. Only definitions active in the current locale are
956 checked.
957 -o format, --output-format format
959 Use the specified format for numeric output; the format is a
960 subset of that for the printf function in the ANSI C standard.
961 Only a numeric format ('E' or 'e' for scientific notation, 'f'
962 for fixed-point decimal, or 'G' or 'g' to specify the number of
963 significant figures) is allowed. The default format is '%.8g';
964 for greater precision, you could specify '-o %.15g'. See
965 Numeric Output Format and the documentation for printf() for
966 more detailed descriptions of the format specification.
967 -e, --exponential
969 Set the numeric output format to exponential (i.e., scientific
970 notation), like that used in the Unix 'units' program.
971 -f filename, --file filename
973 Instruct 'units' to load the units file 'filename'. You can
974 specify up to 25 units files on the command line. When you use
975 this option, 'units' will load only the files you list on the
976 command line; it will not load the standard file or your per‐
977 sonal units file unless you explicitly list them. If filename
978 is the empty string ('-f ""'), the default units file (or that
979 specified by 'UNITSFILE') will be loaded in addition to any oth‐
980 ers specified with '-f'.
981 -h, --help
983 Print out a summary of the options for 'units'.
984 -m, --minus
986 Causes '-' to be interpreted as a subtraction operator. This is
987 the default behavior.
988 -p, --product
990 Causes '-' to be interpreted as a multiplication operator when
991 it has two operands. It will act as a negation operator when it
992 has only one operand: '(-3)'. By default '-' is treated as a
993 subtraction operator.
994 --oldstar
996 Causes '*' to have the old-style precedence, higher than the
997 precedence of division so that '1/2*3' will equal '1/6'.
998 --newstar
1000 Forces '*' to have the new (default) precedence that follows the
1001 usual rules of algebra: the precedence of '*' is the same as the
1002 precedence of '/', so that '1/2*3' will equal '3/2'.
1003 --compact
1005 Give compact output featuring only the conversion factor. This
1006 turns off the '--verbose' option.
1007 -q, --quiet, --silent
1009 Suppress prompting of the user for units and the display of sta‐
1010 tistics about the number of units loaded.
1011 -n, --nolists
1013 Disable conversion to unit lists.
1014 -r, --round
1016 When converting to a combination of units given by a unit list,
1017 round the value of the last unit in the list to the nearest
1018 integer.
1019 -S, --show-factor
1021 When converting to a combination of units specified in a list,
1022 always show a non-unity factor before a unit that begins with a
1023 fraction with a unity denominator. By default, if the unit in a
1024 list begins with fraction of the form 1|x and its multiplier is
1025 an integer other than 1, the fraction is given as the product of
1026 the multiplier and the numerator (e.g., '3|8 in' rather than '3
1027 * 1|8 in'). In some cases, this is not what is wanted; for
1028 example, the results for a cooking recipe might show '3 * 1|2
1029 cup' as '3|2 cup'. With the '--show-factor' option, a result
1030 equivalent to 1.5 cups will display as '3 * 1|2 cup' rather than
1031 '3|2 cup'. A user-specified fractional unit with a numerator
1032 other than 1 is never overridden, however—if a unit list speci‐
1033 fies '3|4 cup;1|2 cup', a result equivalent to 1 1/2 cups will
1034 always be shown as '2 * 3|4 cup' whether or not the '--show-
1035 factor' option is given.
1036 -s, --strict
1038 Suppress conversion of units to their reciprocal units. For
1039 example, 'units' will normally convert hertz to seconds because
1040 these units are reciprocals of each other. The strict option
1041 requires that units be strictly conformable to perform a conver‐
1042 sion, and will give an error if you attempt to convert hertz to
1043 seconds.
1044 -1, --one-line
1046 Give only one line of output (the forward conversion). Do not
1047 print the reverse conversion. If a reciprocal conversion is
1048 performed then 'units' will still print the ``reciprocal conver‐
1049 sion'' line.
1050 -t, --terse
1052 Give terse output when converting units. This option can be
1053 used when calling 'units' from another program so that the out‐
1054 put is easy to parse. This option has the combined effect of
1055 these options: '--strict' '--quiet' '--one-line' '--compact'.
1056 -v, --verbose
1058 Give slightly more verbose output when converting units. When
1059 combined with the '-c' option this gives the same effect as
1060 '--check-verbose'.
1061 -V, --version
1063 Print program version number, tell whether the 'readline'
1064 library has been included, and give the location of the default
1065 units data file.
1066 -l locale, --locale locale
1068 Force a specified locale such as 'en_GB' to get British defini‐
1069 tions by default. This overrides the locale determined from
1070 system settings or environment variables. See Locale for a
1071 description of locale format.
1072
1074 Units Data Files
1075 The units and prefixes that 'units' can convert are defined in the
1076 units data file, typically '/usr/share/units/definitions.units'.
1077 Although you can extend or modify this data file if you have appropri‐
1078 ate user privileges, it's usually better to put extensions in separate
1079 files so that the definitions will be preserved when you update
1080 'units'.
1081 You can include additional data files in the units database using the
1083 '!include' command in the standard units data file. For example
1084 !include /usr/local/share/units/local.units
1086 might be appropriate for a site-wide supplemental data file. The loca‐
1088 tion of the '!include' statement in the standard units data file is
1089 important; later definitions replace earlier ones, so any definitions
1090 in an included file will override definitions before the '!include'
1091 statement in the standard units data file. With normal invocation, no
1092 warning is given about redefinitions; to ensure that you don't have an
1093 unintended redefinition, run 'units -c' after making changes to any
1094 units data file.
1095 If you want to add your own units in addition to or in place of stan‐
1097 dard or site-wide supplemental units data files, you can include them
1098 in the '.units' file in your home directory. If this file exists it is
1099 read after the standard units data file, so that any definitions in
1100 this file will replace definitions of the same units in the standard
1101 data file or in files included from the standard data file. This file
1102 will not be read if any units files are specified on the command line.
1103 (Under Windows the personal units file is named 'unitdef.units'.)
1104 The 'units' program first tries to determine your home directory from
1106 the 'HOME' environment variable. On systems running Microsoft Windows,
1107 if 'HOME' does not exist, 'units' attempts to find your home directory
1108 from 'HOMEDRIVE' and 'HOMEPATH'. Running 'units -V' will display the
1109 location and name of your personal units file.
1110 You can specify an arbitrary file as your personal units data file with
1112 the 'MYUNITSFILE' environment variable; if this variable exists, its
1113 value is used without searching your home directory.
1114 Defining New Units and Prefixes
1116 A unit is specified on a single line by giving its name and an equiva‐
1117 lence. Comments start with a '#' character, which can appear anywhere
1118 in a line. The backslash character ('\') acts as a continuation char‐
1119 acter if it appears as the last character on a line, making it possible
1120 to spread definitions out over several lines if desired. A file can be
1121 included by giving the command '!include' followed by the file's name.
1122 The '!' must be the first character on the line. The file will be
1123 sought in the same directory as the parent file unless you give a full
1124 path. The name of the file to be included cannot contain the comment
1125 character '#'.
1126 Unit names must not contain any of the operator characters '+', '-',
1128 '*', '/', '|', '^', ';', '~', the comment character '#', or parenthe‐
1129 ses. They cannot begin or end with an underscore ('_'), a comma (',')
1130 or a decimal point ('.'). Names cannot begin with a digit, and if a
1131 name ends in a digit other than zero, the digit must be preceded by a
1132 string beginning with an underscore, and afterwards consisting only of
1133 digits, decimal points, or commas. For example, 'foo_2', 'foo_2,1', or
1134 'foo_3.14' would be valid names but 'foo2' or 'foo_a2' would be
1135 invalid. You could define nitrous oxide as
1136 N2O nitrogen 2 + oxygen
1138 but would need to define nitrogen dioxide as
1140 NO_2 nitrogen + oxygen 2
1142 Be careful to define new units in terms of old ones so that a reduction
1144 leads to the primitive units, which are marked with '!' characters.
1145 Dimensionless units are indicated by using the string '!dimensionless'
1146 for the unit definition.
1147 When adding new units, be sure to use the '-c' option to check that the
1149 new units reduce properly. If you create a loop in the units defini‐
1150 tions, then 'units' will hang when invoked with the '-c' option. You
1151 will need to use the '--check-verbose' option, which prints out each
1152 unit as it is checked. The program will still hang, but the last unit
1153 printed will be the unit that caused the infinite loop.
1154 If you define any units that contain '+' characters, carefully check
1156 them because the '-c' option will not catch non-conformable sums. Be
1157 careful with the '-' operator as well. When used as a binary operator,
1158 the '-' character can perform addition or multiplication depending on
1159 the options used to invoke 'units'. To ensure consistent behavior use
1160 '-' only as a unary negation operator when writing units definitions.
1161 To multiply two units leave a space or use the '*' operator with care,
1162 recalling that it has two possible precedence values and may require
1163 parentheses to ensure consistent behavior. To compute the difference
1164 of 'foo' and 'bar' write 'foo+(-bar)' or even 'foo+-bar'.
1165 Here is an example of a short data file that defines some basic units:
1167 m ! # The meter is a primitive unit
1169 sec ! # The second is a primitive unit
1170 rad !dimensionless # A dimensionless primitive unit
1171 micro- 1e-6 # Define a prefix
1172 minute 60 sec # A minute is 60 seconds
1173 hour 60 min # An hour is 60 minutes
1174 inch 0.0254 m # Inch defined in terms of meters
1175 ft 12 inches # The foot defined in terms of inches
1176 mile 5280 ft # And the mile
1177 A unit that ends with a '-' character is a prefix. If a prefix defini‐
1179 tion contains any '/' characters, be sure they are protected by paren‐
1180 theses. If you define 'half- 1/2' then 'halfmeter' would be equivalent
1181 to '1 / (2 meter)'.
1182 Defining Nonlinear Units
1184 Some unit conversions of interest are nonlinear; for example, tempera‐
1185 ture conversions between the Fahrenheit and Celsius scales cannot be
1186 done by simply multiplying by conversion factors.
1187 When you give a linear unit definition such as 'inch 2.54 cm' you are
1189 providing information that 'units' uses to convert values in inches
1190 into primitive units of meters. For nonlinear units, you give a func‐
1191 tional definition that provides the same information.
1192 Nonlinear units are represented using a functional notation. It is
1194 best to regard this notation not as a function call but as a way of
1195 adding units to a number, much the same way that writing a linear unit
1196 name after a number adds units to that number. Internally, nonlinear
1197 units are defined by a pair of functions that convert to and from lin‐
1198 ear units in the data file, so that an eventual conversion to primitive
1199 units is possible.
1200 Here is an example nonlinear unit definition:
1202 tempF(x) units=[1;K] (x+(-32)) degF + stdtemp ; \
1204 (tempF+(-stdtemp))/degF + 32
1205 A nonlinear unit definition comprises a unit name, a dummy parameter
1207 name, two functions, and two corresponding units. The functions tell
1208 'units' how to convert to and from the new unit. In order to produce
1209 valid results, the arguments of these functions need to have the cor‐
1210 rect dimensions. To facilitate error checking, you may optionally
1211 indicate units for these arguments.
1212 The definition begins with the unit name followed immediately (with no
1214 spaces) by a '(' character. In parentheses is the name of the parame‐
1215 ter. Next is an optional specification of the units required by the
1216 functions in this definition. In the example above, the 'tempF' func‐
1217 tion requires an input argument conformable with '1'. For normal non‐
1218 linear units definitions the forward function will always take a dimen‐
1219 sionless argument. The inverse function requires an input argument
1220 conformable with 'K'. In general the inverse function will need units
1221 that match the quantity measured by your nonlinear unit. The purpose
1222 of the expression in brackets to enable 'units' to perform error check‐
1223 ing on function arguments, and also to assign units to range and domain
1224 specifications, which are described later.
1225 Next the function definitions appear. In the example above, the
1227 'tempF' function is defined by
1228 tempF(x) = (x+(-32)) degF + stdtemp
1230 This gives a rule for converting 'x' in the units 'tempF' to linear
1232 units of absolute temperature, which makes it possible to convert from
1233 tempF to other units.
1234 In order to make conversions to Fahrenheit possible, you must give a
1236 rule for the inverse conversions. The inverse will be 'x(tempF)' and
1237 its definition appears after a ';' character. In our example, the
1238 inverse is
1239 x(tempF) = (tempF+(-stdtemp))/degF + 32
1241 This inverse definition takes an absolute temperature as its argument
1243 and converts it to the Fahrenheit temperature. The inverse can be
1244 omitted by leaving out the ';' character, but then conversions to the
1245 unit will be impossible. If the inverse is omitted then the '--check'
1246 option will display a warning. It is up to you to calculate and enter
1247 the correct inverse function to obtain proper conversions. The
1248 '--check' option tests the inverse at one point and prints an error if
1249 it is not valid there, but this is not a guarantee that your inverse is
1250 correct.
1251 If you wish to make synonyms for nonlinear units, you still need to
1253 define both the forward and inverse functions. Inverse functions can
1254 be obtained using the '~' operator. So to create a synonym for 'tempF'
1255 you could write
1256 fahrenheit(x) units=[1;K] tempF(x); ~tempF(fahrenheit)
1258 You may define a function whose range and domain do not cover all of
1260 the real numbers. In this case 'units' can handle errors better if you
1261 specify an appropriate range and domain. You specify the range and
1262 domain as shown below.
1263 baume(d) units=[1;g/cm^3] domain=[0,130.5] range=[1,10] \
1265 (145/(145-d)) g/cm^3 ; (baume+-g/cm^3) 145 / baume
1266 In this example the domain is specified after the 'domain=' with the
1268 endpoints given in brackets. One of the end points can be omitted to
1269 get an interval that goes to infinity. So the range could be specified
1270 as nonnegative by writing 'range=[0,]'. Both the range and domain are
1271 optional and can appear independently and in any order along with the
1272 'units' specification. The values in the range and domain are attached
1273 to the units given in the 'units' specification. If you don't specify
1274 the units then the parameter inputs are reduced to primitive units for
1275 the numeric comparison to the values you give in the range or domain.
1276 In this case you should only use 'range' or 'domain' if the endpoints
1277 are zero and infinity.
1278 Specifying the range and domain allows 'units' to perform better error
1280 checking and give more helpful error messages when you invoke nonlinear
1281 units conversions outside of their bounds. It also enables the '-c'
1282 option to find a point in the domain to use for its point check of your
1283 inverse definition.
1284 You may occasionally wish to define a function that operates on units.
1286 This can be done using a nonlinear unit definition. For example, the
1287 definition below provides conversion between radius and the area of a
1288 circle. This definition requires a length as input and produces an
1289 area as output, as indicated by the 'units=' specification. Specifying
1290 the range as the nonnegative numbers can prevent cryptic error mes‐
1291 sages.
1292 circlearea(r) units=[m;m^2] range=[0,] pi r^2 ; sqrt(circlearea/pi)
1294 Sometimes you may be interested in a piecewise linear unit such as many
1296 wire gauges. Piecewise linear units can be defined by specifying con‐
1297 versions to linear units on a list of points. Conversion at other
1298 points will be done by linear interpolation. A partial definition of
1299 zinc gauge is
1300 zincgauge[in] 1 0.002, 10 0.02, 15 0.04, 19 0.06, 23 0.1
1302 In this example, 'zincgauge' is the name of the piecewise linear unit.
1304 The definition of such a unit is indicated by the embedded '[' charac‐
1305 ter. After the bracket, you should indicate the units to be attached
1306 to the numbers in the table. No spaces can appear before the ']' char‐
1307 acter, so a definition like 'foo[kg meters]' is illegal; instead write
1308 'foo[kg*meters]'. The definition of the unit consists of a list of
1309 pairs optionally separated by commas. This list defines a function for
1310 converting from the piecewise linear unit to linear units. The first
1311 item in each pair is the function argument; the second item is the
1312 value of the function at that argument (in the units specified in
1313 brackets). In this example, we define 'zincgauge' at five points. For
1314 example, we set 'zincgauge(1)' equal to '0.002 in'. Definitions like
1315 this may be more readable if written using continuation characters
1316 as
1317 zincgauge[in] \
1319 1 0.002 \
1320 10 0.02 \
1321 15 0.04 \
1322 19 0.06 \
1323 23 0.1
1324 With the preceding definition, the following conversion can be per‐
1326 formed:
1327 You have: zincgauge(10)
1329 You want: in
1330 * 0.02
1331 / 50
1332 You have: .01 inch
1333 You want: zincgauge
1334 5
1335 If you define a piecewise linear unit that is not strictly monotonic,
1337 then the inverse will not be well defined. If the inverse is requested
1338 for such a unit, 'units' will return the smallest inverse. The
1339 '--check' option will print a warning if a non-monotonic piecewise lin‐
1340 ear unit is encountered.
1341 Defining Unit List Aliases
1343 Unit list aliases are treated differently from unit definitions,
1344 because they are a data entry shorthand rather than a true definition
1345 for a new unit. A unit list alias definition begins with '!unitlist'
1346 and includes the alias and the definition; for example, the aliases
1347 included in the standard units data file are
1348 !unitlist hms hr;min;sec
1350 !unitlist time year;day;hr;min;sec
1351 !unitlist dms deg;arcmin;arcsec
1352 !unitlist ftin ft;in;1|8 in
1353 !unitlist usvol cup;3|4 cup;2|3 cup;1|2 cup;1|3 cup;1|4 cup;\
1354 tbsp;tsp;1|2 tsp;1|4 tsp;1|8 tsp
1355 Unit list aliases are only for unit lists, so the definition must
1357 include a ';'. Unit list aliases can never be combined with units or
1358 other unit list aliases, so the definition of 'time' shown above could
1359 not have been shortened to 'year;day;hms'. As usual, be sure to run
1360 'units --check' to ensure that the units listed in unit list aliases
1361 are conformable.
1362
1364 By default, results of conversions are shown to eight significant fig‐
1365 ures; this can be changed with the '--exponential' and '--output-
1366 format' options. The former sets an exponential format (i.e., scien‐
1367 tific notation) like that used in the original Unix 'units' program;
1368 the latter allows the format to be given as that of the printf function
1369 in the ANSI C standard.
1370 The format recognized with the '--output-format' option is a subset of
1372 that for printf(). Only a floating-point format of the form
1373 '%'[flag][width]['.'precision]type is allowed: it must begin with '%',
1374 and must end with a floating-point type specifier ('E' or 'e' for sci‐
1375 entific notation, 'f' for fixed-point decimal, or 'G' or 'g' to specify
1376 the number of significant figures). The format specification may
1377 include one optional flag ('+', '-', '#', or a space), followed by an
1378 optional value for the minimum field width, and an optional precision
1379 specification that begins with a period (e.g., '.6'). In addition to
1380 the digits, the field width includes the decimal point, the exponent,
1381 and the sign if any of these are shown. A width specification is typi‐
1382 cally used with fixed-point decimal to have columns of numbers align at
1383 the decimal point; it normally is not useful with 'units'. Non-float‐
1384 ing-point type specifiers make no sense for 'units', and are forbidden.
1385 The default format is '%.8g'; for greater precision, you could specify
1387 '-o %.15g'. The 'G' and 'g' formats use exponential format whenever
1388 the exponent would be less than -5, so the value 0.000013 displays as
1389 '1.3e-005'. If you prefer fixed-point display, you might specify '-o
1390 %.8f'; however, very small numbers may display very few significant
1391 figures, and for very small numbers, may show nothing but zeros.
1392 See the documentation for printf() for more detailed descriptions of
1394 the format specification.
1395
1397 Some units have different values in different locations. The localiza‐
1398 tion feature accommodates this by allowing a units data file to specify
1399 definitions that depend on the user's locale.
1400 Locale
1402 A locale is a subset of a user's environment that indicates the user's
1403 language and country, and some attendant preferences, such as the for‐
1404 matting of dates. The 'units' program attempts to determine the locale
1405 from the POSIX setlocale function; if this cannot be done, 'units'
1406 examines the environment variables 'LC_CTYPE' and 'LANG'. On POSIX
1407 systems, a locale is of the form language'_'country, where language is
1408 the two-character code from ISO 639-1 and country is the two-character
1409 code from ISO 3166-1; language is lower case and country is upper case.
1410 For example, the POSIX locale for the United Kingdom is 'en_GB'.
1411 On systems running Microsoft Windows, the value returned by setlocale()
1413 is different from that on POSIX systems; 'units' attempts to map the
1414 Windows value to a POSIX value by means of a table in the file
1415 'locale.map' in the same directory, typically '/usr/local/share/units',
1416 as the default units data files. The file includes entries for many
1417 combinations of language and country, and can be extended to include
1418 other combinations. The 'locale.map' comprises two tab-separated col‐
1419 umns; each entry is of the form
1420 Windows-locale POSIX-locale
1422 where POSIX-locale is as described above, and Windows-locale typically
1424 spells out both the language and country. For example, the entry for
1425 the United States is
1426 English_United States en_US
1428 You can force 'units' to run in a desired locale by using the '-l'
1430 option.
1431 In order to create unit definitions for a particular locale you begin a
1433 block of definitions in a unit datafile with '!locale' followed by a
1434 locale name. The '!' must be the first character on the line. The
1435 'units' program reads the following definitions only if the current
1436 locale matches. You end the block of localized units with
1437 '!endlocale'. Here is an example, which defines the British gallon.
1438 !locale en_GB
1440 gallon 4.54609 liter
1441 !endlocale
1442 Additional Localization
1444 Sometimes the locale isn't sufficient to determine unit preferences.
1445 There could be regional preferences, or a company could have specific
1446 preferences. Though probably uncommon, such differences could arise
1447 with the choice of English customary units outside of English-speaking
1448 countries. To address this, 'units' allows specifying definitions that
1449 depend on environment variable settings. The environment variables can
1450 be controled based on the current locale, or the user can set them to
1451 force a particular group of definitions.
1452 A conditional block of definitions in a units data file begins with
1454 either '!var' or '!varnot' following by an environment variable name
1455 and then a space separated list of values. The leading '!' must
1456 appear in the first column of a units data file, and the conditional
1457 block is terminated by '!endvar'. Definitions in blocks beginning with
1458 '!var' are executed only if the environment variable is exactly equal
1459 to one of the listed values. Definitions in blocks beginning with
1460 '!varnot' are executed only if the environment variable does not equal
1461 any of the list values.
1462 The inch has long been a customary measure of length in many places.
1464 The word comes from the latin uncia meaning ``one twelfth,'' referring
1465 to its relationship with the foot. By the 20th century, the inch was
1466 officially defined in English-speaking countries relative to the yard,
1467 but until 1959, the yard differed slightly among those countries. In
1468 France the customary inch, which was displaced in 1799 by the meter,
1469 had a different length based on a french foot. These customary defini‐
1470 tions could be accomodated as follows:
1471 !var INCH_UNIT usa
1473 yard 3600|3937 m
1474 !endvar
1475 !var INCH_UNIT canada
1476 yard 0.9144 meter
1477 !endvar
1478 !var INCH_UNIT uk
1479 yard 0.91439841 meter
1480 !endvar
1481 !var INCH_UNIT canada uk usa
1482 foot 1|3 yard
1483 inch 1|12 foot
1484 !endvar
1485 !var INCH_UNIT france
1486 foot 144|443.296 m
1487 inch 1|12 foot
1488 line 1|12 inch
1489 !endvar
1490 !varnot INCH_UNIT usa uk france canada
1491 !message Unknown value for INCH_UNIT
1492 !endvar
1493 When 'units' reads the above definitions it will check the environment
1495 variable 'INCH_UNIT' and load only the definitions for the appropriate
1496 section. If 'INCH_UNIT' is unset or is not set to one of the four val‐
1497 ues listed then 'units' will run the last block. In this case that
1498 block uses the '!message' command to display a warning message. Alter‐
1499 natively that block could set default values.
1500 In order to create default values that are overridden by user settings
1502 the data file can use the '!set' command, which sets an environment
1503 variable only if it is not already set; these settings are only for
1504 the current 'units' invocation and do not persist. So if the example
1505 above were preceded by '!set INCH_UNIT france' then this would make
1506 'france' the default value for 'INCH_UNIT'. If the user had set the
1507 variable in the environment before invoking 'units', then 'units' would
1508 use the user's value.
1509 To link these settings to the user's locale you combine the '!set' com‐
1511 mand with the '!locale' command. If you wanted to combine the above
1512 example with suitable locales you could do by preceding the above defi‐
1513 nition with the following:
1514 !locale en_US
1516 !set INCH_UNIT usa
1517 !endlocale
1518 !locale en_GB
1519 !set INCH_UNIT uk
1520 !endlocale
1521 !locale en_CA
1522 !set INCH_UNIT canada
1523 !endlocale
1524 !locale fr_FR
1525 !set INCH_UNIT france
1526 !endlocale
1527 !set INCH_UNIT france
1528 These definitions set the overall default for 'INCH_UNIT' to 'france'
1530 and set default values for four locales appropriately. The overall
1531 default setting comes last so that it only applies when 'INCH_UNIT' was
1532 not set by one of the other commands or by the user.
1533 If the variable given after '!var' or '!varnot' is undefined then
1535 'units' prints an error message and ignores the definitions that
1536 follow. Use '!set' to create defaults to prevent this situation from
1537 arising. The '-c' option only checks the definitions that are active
1538 for the current environment and locale, so when adding new definitions
1539 take care to check that all cases give rise to a well defined set of
1540 definitions.
1541
1543 The 'units' program uses the following environment variables:
1544 HOME Specifies the location of your home directory; it is used by
1546 'units' to find a personal units data file '.units'. On systems
1547 running Microsoft Windows, 'units' tries to determine your home
1548 directory from the 'HOMEDRIVE' and 'HOMEPATH' environment vari‐
1549 ables if 'HOME' does not exist.
1550 LC_CTYPE, LANG
1552 Checked to determine the locale if 'units' cannot obtain it from
1553 the operating system. Sections of the standard units data file
1554 are specific to certain locales.
1555 MYUNITSFILE
1557 Specifies your personal units data file. If this variable
1558 exists, 'units' uses its value rather than searching your home
1559 directory for '.units'. The personal units file will not be
1560 loaded if any data files are given using the '-f' option.
1561 PAGER Specifies the pager to use for help and for displaying the con‐
1563 formable units. The help function browses the units database
1564 and calls the pager using the '+n'n syntax for specifying a line
1565 number. The default pager is 'more'; 'PAGER' can be used to
1566 specify alternatives such as 'less', 'pg', 'emacs', or 'vi'.
1567 UNITS_ENGLISH
1569 Set to either 'US' or 'GB' to choose United States or British
1570 volume definitions, overriding the default from your locale.
1571 UNITSFILE
1573 Specifies the units data file to use (instead of the default).
1574 You can only specify a single units data file using this envi‐
1575 ronment variable. If units data files are given using the '-f'
1576 option, the file specified by 'UNITSFILE' will be not be loaded
1577 unless the '-f' option is given with the empty string
1578 ('units -f ""').
1579
1581 The standard units data file is written in Unicode using the UTF-8
1582 encoding. Portions of the file that are not plain ASCII begin with
1583 '!utf8' and end with '!endutf8'. As usual, the '!' must appear as the
1584 first character on the line. If a line of a data file contains byte
1585 sequences that are invalid UTF-8 or non-printing UTF-8 then 'units'
1586 ignores the entire line.
1587 When 'units' runs it checks the locale to determine the character set.
1589 If UTF-8 is listed, then 'units' reads the utf8 definitions. If any
1590 other character set is in use, then 'units' works in plain ASCII with‐
1591 out support for extended characters.
1592
1594 If the 'readline' package has been compiled in, then when 'units' is
1595 used interactively, numerous command line editing features are avail‐
1596 able. To check if your version of 'units' includes 'readline', invoke
1597 the program with the '--version' option.
1598 For complete information about 'readline', consult the documentation
1600 for the 'readline' package. Without any configuration, 'units' will
1601 allow editing in the style of emacs. Of particular use with 'units'
1602 are the completion commands.
1603 If you type a few characters and then hit ESC followed by '?' then
1605 'units' will display a list of all the units that start with the char‐
1606 acters typed. For example, if you type 'metr' and then request comple‐
1607 tion, you will see something like this:
1608 You have: metr
1610 metre metriccup metrichorsepower metrictenth
1611 metretes metricfifth metricounce metricton
1612 metriccarat metricgrain metricquart metricyarncount
1613 You have: metr
1614 If there is a unique way to complete a unitname, you can hit the TAB
1616 key and 'units' will provide the rest of the unit name. If 'units'
1617 beeps, it means that there is no unique completion. Pressing the TAB
1618 key a second time will print the list of all completions.
1619
1621 The units program includes currency exchange rates and prices for some
1622 precious metals in the database. Of course, these values change over
1623 time, sometimes very rapidly, and 'units' cannot provide real time val‐
1624 ues. To update the exchange rates run the 'units_cur', which rewrites
1625 the files containing the currency rates, typically
1626 '/usr/local/share/units/currency.units'. This program must be run with
1627 suitable permissions to write the file. To keep the rates updated
1628 automatically, it could be run by a cron job on a Unix-like system, or
1629 a similar scheduling program on a different system. Currency exchange
1630 rates are taken from Time Genie (http://www.timegenie.com) and precious
1631 metals pricing from Packetizer (www.packetizer.com). These sites
1632 update once per day, so there is no benefit in running the update
1633 script more often than daily. You can run 'units_cur' with a filename
1634 specified on the command line and it will write the data to that file.
1635 If you give '-' for the file it will write to standard output.
1636
1638 unit definition
1639 Define a regular unit.
1640 prefix- definition
1642 Define a prefix.
1643 funcname(var) units=[in-units,out-units] domain=[x1,x2] range=[y1,y2]
1645 definition(var) ; inverse(funcname)
1646 Define a nonlinear unit or unit function. The three optional
1647 keywords 'units=', 'range=' and 'domain=' can appear in any
1648 order. The definition of the inverse is optional.
1649 tabname[out-units] pair-list
1651 Define a piecewise linear unit. The pair list gives the points
1652 on the table listed in ascending order.
1653 !endlocale
1655 End a block of definitions beginning with '!locale'
1656 !endutf8
1658 End a block of definitions begun with '!utf8'
1659 !endvar
1661 End a block of definitions begun with '!var' or '!varnot'
1662 !include file
1664 Include the specified file.
1665 !locale value
1667 Load the following definitions only of the locale is set to
1668 value.
1669 !message text
1671 Display text when the database is read unless the quiet option
1672 ('-q') is enabled.
1673 !set variable value
1675 Sets the environment variable, variable, to the specified value
1676 only if it is not already set.
1677 !unitlist alias definition
1679 Define a unit list alias.
1680 !utf8 Load the following definitions only if 'units' is running with
1682 UTF-8 enabled.
1683 !var variable value-list
1685 Load the following definitions only if the environment variable,
1686 variable is set to one of the values listed on the space sepa‐
1687 rated value list. If variable is not set then 'units' prints an
1688 error message and ignores the following definitions.
1689 !varnot variable value-list
1691 Load the following definitions only if the environment variable,
1692 variable is not set to one of the values listed on the space
1693 separated value list. If variable is not set then 'units'
1694 prints an error message and ignores the following definitions.
1695
1698 /usr/share/units/definitions.units — the standard units data file
1699
1701 27 April 2012 UNITS(1)