7 .Nd conversion calculator
17 program converts quantities expressed in various scales to
18 their equivalents in other scales.
20 handle multiplicative or affine scale changes.
23 can work interactively by prompting
26 or non-interactively, providing a conversion for given arguments
31 The following options are available:
32 .Bl -tag -width "from to"
33 .It Fl e , Fl -exponential
37 (see the description of the
40 .It Fl f Ar unitsfile , Fl -file Ar unitsfile
41 Specify the name of the units data file to load.
42 This option may be specified multiple times.
43 .It Fl H Ar historyfile , Fl -history Ar historyfile
44 Ignored, for compatibility with GNU units.
46 Show an overview of options.
47 .It Fl o Ar format , Fl -output-format Ar format
48 Select the output format string by which numbers are printed.
52 Suppress prompting of the user for units and the display of statistics
53 about the number of units loaded.
55 Only print the result.
56 This is used when calling
58 from other programs for easy to parse results.
59 .It Fl U , Fl -unitsfile
60 Print the location of the default unit file if it exists.
62 .Dq Units data file not found .
63 .It Fl V , Fl -version
64 Print the version number
65 .Pq which is fixed at Dq Fx units ,
66 the path to the units data file and exit.
67 .It Fl v , Fl -verbose
68 Print the units in the conversion output.
69 Be more verbose in general.
71 Allow a single unit conversion to be done directly from the command
73 The program will not print prompts.
74 It will print out the result of the single specified conversion.
83 or a quantity with a unit
86 .Ss Mathematical operators
89 Powers of units can be specified using the
91 character as shown in the example, or by simple concatenation:
99 for details on the limitations of exponent values.
101 Multiplication of units can be specified by using spaces
108 Division of units is indicated by the slash
112 must be indicated using the vertical bar
116 Note that multiplication has a higher precedence than division,
124 The conversion information is read from a units data file.
126 file includes definitions for most familiar units, abbreviations and
128 Some constants of nature included are:
130 .Bl -column -offset indent -compact "mercury"
131 .It "pi ratio of circumference to diameter"
132 .It "c speed of light"
133 .It "e charge on an electron"
134 .It "g acceleration of gravity"
135 .It "force same as g"
136 .It "mole Avogadro's number"
137 .It "water pressure per unit height of water"
138 .It "mercury pressure per unit height of mercury"
139 .It "au astronomical unit"
145 Compound names are run together
151 is also a unit of mass.
154 British units that differ from
155 their US counterparts are prefixed with
157 and currency is prefixed with its country name:
158 .Dq Ic belgiumfranc ,
159 .Dq Ic britainpound .
161 for a unit, if the specified string does not appear exactly as a unit
164 will try to remove a trailing
168 and check again for a match.
169 .Ss Units file format
170 To find out what units are available read the standard units file.
171 If you want to add your own units you can supply your own file.
172 A unit is specified on a single line by
173 giving its name and an equivalence.
175 new units in terms of old ones so that a reduction leads to the
176 primitive units which are marked with
181 program will not detect infinite loops that could be caused
182 by careless unit definitions.
183 Comments in the unit definition file
188 character at the beginning of a line.
190 Prefixes are defined in the same way as standard units, but with
193 at the end of the prefix name.
194 If a unit is not found
195 even after removing trailing
199 then it will be checked against the list of prefixes.
200 Prefixes will be removed until a legal
201 base unit is identified.
205 The colon-separated list of root directories at which
208 .Pa /usr/share/misc/definitions.units .
213 .Dq Li /tmp:/:/usr/local ,
216 flags are provided, and
217 .Pa /usr/share/misc/definitions.units
220 tries to open the following files as the default units file:
221 .Pa /tmp/usr/share/misc/definitions.units ,
222 .Pa /usr/share/misc/definitions.units ,
224 .Pa /usr/local/usr/share/misc/definitions.units .
227 .Bl -tag -width /usr/share/misc/definitions.units -compact
228 .It Pa /usr/share/misc/definitions.units
229 The standard units file.
235 .It Sy Example 1 : No Simple conversion of units
237 This example shows how to do simple conversions, for example from gigabytes
239 .Bd -literal -offset 2n
240 .Li $ Ic units -o %0.f -t '4 gigabytes' bytes
246 part of the command is required to print the result in a non-scientific
247 notation (e.g, 4294967296 instead of 4.29497e+09).
248 .It Sy Example 2 : No Interactive usage
250 Here is an example of an interactive session where the user is prompted for
252 .Bd -literal -offset 2n
253 .Li You have : Ic meters
254 .Li You want : Ic feet
258 .Li You have : Ic cm^3
259 .Li You want : Ic gallons
263 .Li You have : Ic meters/s
264 .Li You want : Ic furlongs/fortnight
268 .Li You have : Ic 1|2 inch
273 .Li You have : Ic 85 degF
274 .Li You want : Ic degC
277 .It Sy Example 3 : No Difference between Do Ic \&| Dc No and Do Ic / Dc No division
279 The following command shows how to convert half a meter to centimeters.
280 .Bd -literal -offset 2n
281 .Li $ Ic units '1|2 meter' cm
287 prints the expected result because the division operator for numbers
291 Using the division operator for units
293 would result in an error:
294 .Bd -literal -offset 2n
295 .Li $ Ic units '1/2 meter' cm
307 which is not conformable to
309 .It Sy Example 4 : No Simple units file
310 Here is an example of a short units file that defines some basic
313 .Bl -column -offset 2n -compact "minute"
323 .It Sy Example 5 : No Viewing units and conversions of the default units file
324 The following shell one-liner allows the user to view the contents of the
326 .Bd -literal -offset 2n
327 .Li $ Ic less \&"$(units -U)"
332 .It can't find units file '%s'
333 The default units file is not in its default location
335 and it is not present in any file tree starting with their roots at directories from
337 .Pq see Sx ENVIRONMENT .
338 .It cap_rights_limit\&() failed
341 .It conformability error
342 It is not possible to reduce the given units to one common unit:
343 they are not conformable.
344 Instead of a conversion,
346 will display the reduced form for each provided unit:
347 .Bd -literal -offset 2n
348 .Li You have : Ic ergs/hour
349 .Li You want : Ic fathoms kg^2 / day
351 2.7777778e-11 kg m^2 / sec^3
352 2.1166667e-05 kg^2 m / sec
354 .It Could not initialize history
360 .It memory for prefixes exceeded in line %d
361 Over 100 prefixes were defined.
362 .It memory for units exceeded in line %d
363 Over 1000 prefixes were defined.
364 .It memory overflow in unit reduction
365 The requested conversion involves too many units
367 .It redefinition of prefix '%s' on line %d ignored
369 .It redefinition of unit '%s' on line %d ignored
371 .It unexpected end of prefix on line %d
373 .It unexpected end of unit on line %d
375 .It Units data file not found
376 The default units file is missing.
377 .It unable to enter capability mode
380 .It unable to open units file '%s'
381 One of the user-specified units files cannot be opened.
382 .It unit reduces to zero
384 .It unknown unit '%s'
385 The provided unit cannot be found in the units file.
386 .It WARNING: conversion of non-proportional quantities.
392 because the units are not proportional.
393 The warning is printed when a quantity is a part of the
396 It can be illustrated on an example of conversion from Fahrenheit to Celsius:
397 .Bd -literal -offset 2n
398 .Li $ Ic units \&"degF" \&"degC"
399 (-> x*0.55555556g -17.777778g)
401 .Li $ Ic units \&"degF" \&"1 degC"
402 WARNING: conversion of non-proportional quantities.
403 (-> x*0.55555556g -17.777778g)
405 .Li $ Ic units \&"1 degF" \&"1 degC"
406 WARNING: conversion of non-proportional quantities.
420 The manual page was significantly rewritten in
423 .An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .
425 .An Adrian Mariano Aq Mt adrian@cam.cornell.edu
427 The effect of including a
429 in a prefix is surprising.
431 Exponents entered by the user can be only one digit.
432 You can work around this by multiplying several terms.
436 to indicate division of numbers and
438 to indicate division of symbols.
439 This distinction should not
442 The program contains various arbitrary limits on the length
443 of the units converted and on the length of the data file.
445 The program should use a hash table to store units so that
446 it does not take so long to load the units list and check
449 It is not possible to convert a negative value.
454 does not handle reductions of long lists of units very well:
455 .Bd -literal -offset 2n
456 .Li $ Ic units \&"$(yes m | head -n 154)" \&"$(yes cm | head -n 154)"
459 .Li $ Ic units \&"$(yes m | head -n 333)" \&"$(yes cm | head -n 333)"
462 .Li $ Ic units \&"$(yes m | head -n 500)" \&"$(yes cm | head -n 500)"
463 units: memory overflow in unit reduction
467 .Li $ Ic units \&"$(yes m | head -n 501)" \&"$(yes cm | head -n 501)"
468 units: memory overflow in unit reduction
469 units: memory overflow in unit reduction
470 units: memory overflow in unit reduction