1.\" $FreeBSD$ 2.Dd February 3, 2020 3.Dt UNITS 1 4.Os 5.Sh NAME 6.Nm units 7.Nd conversion calculator 8.Sh SYNOPSIS 9.Nm 10.Op Fl ehqtUVv 11.Op Fl f Ar unitsfile 12.Op Fl o Ar format 13.Op Ar from to 14.Sh DESCRIPTION 15The 16.Nm 17program converts quantities expressed in various scales to 18their equivalents in other scales. 19It can only 20handle multiplicative or affine scale changes. 21.Pp 22.Nm 23can work interactively by prompting 24the user for input 25.Pq see Sx EXAMPLES 26or non-interactively, providing a conversion for given arguments 27.Ar from 28and 29.Ar to . 30.Pp 31The following options are available: 32.Bl -tag -width "from to" 33.It Fl e , Fl -exponential 34Same as 35.Fl o 36.Cm %6e 37(see the description of the 38.Fl o 39flag). 40.It Fl f Ar unitsfile , Fl -file Ar unitsfile 41Specify the name of the units data file to load. 42This option may be specified multiple times. 43.It Fl H Ar historyfile , Fl -history Ar historyfile 44Ignored, for compatibility with GNU units. 45.It Fl h , Fl -help 46Show an overview of options. 47.It Fl o Ar format , Fl -output-format Ar format 48Select the output format string by which numbers are printed. 49Defaults to 50.Dq Li %.8g . 51.It Fl q , Fl -quiet 52Suppress prompting of the user for units and the display of statistics 53about the number of units loaded. 54.It Fl t , Fl -terse 55Only print the result. 56This is used when calling 57.Nm 58from other programs for easy to parse results. 59.It Fl U , Fl -unitsfile 60Print the location of the default unit file if it exists. 61Otherwise, print 62.Dq Units data file not found . 63.It Fl V , Fl -version 64Print the version number 65.Pq which is fixed at Dq Fx units , 66the path to the units data file and exit. 67.It Fl v , Fl -verbose 68Print the units in the conversion output. 69Be more verbose in general. 70.It Ar from to 71Allow a single unit conversion to be done directly from the command 72line. 73The program will not print prompts. 74It will print out the result of the single specified conversion. 75Both arguments, i.e., 76.Ar from 77and 78.Ar to , 79can be just a unit 80.Pq e.g., Dq Cm cm , 81a quantity 82.Pq e.g., Dq Cm 42 , 83or a quantity with a unit 84.Pq e.g., Dq Cm 42 cm 85.El 86.Ss Mathematical operators 87.Bl -dash -compact 88.It 89Powers of units can be specified using the 90.Dq Ic ^ 91character as shown in the example, or by simple concatenation: 92.Dq Ic cm3 93is 94equivalent to 95.Dq Ic cm^3 . 96See the 97.Sx BUGS 98section 99for details on the limitations of exponent values. 100.It 101Multiplication of units can be specified by using spaces 102.Pq Dq " " , 103a dash 104.Pq Dq - 105or an asterisk 106.Pq Dq * . 107.It 108Division of units is indicated by the slash 109.Pq Dq Ic / . 110.It 111Division of numbers 112must be indicated using the vertical bar 113.Pq Dq Ic \&| Ns . 114.El 115.Pp 116Note that multiplication has a higher precedence than division, 117so 118.Dq Ic m/s/s 119is the same as 120.Dq Ic m/s^2 121or 122.Dq Ic m/s s . 123.Ss Units 124The conversion information is read from a units data file. 125The default 126file includes definitions for most familiar units, abbreviations and 127metric prefixes. 128Some constants of nature included are: 129.Pp 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" 140.El 141.Pp 142The unit 143.Dq Ic pound 144is a unit of mass. 145Compound names are run together 146so 147.Dq Ic pound force 148is a unit of force. 149The unit 150.Dq Ic ounce 151is also a unit of mass. 152The fluid ounce is 153.Dq Ic floz . 154British units that differ from 155their US counterparts are prefixed with 156.Dq br , 157and currency is prefixed with its country name: 158.Dq Ic belgiumfranc , 159.Dq Ic britainpound . 160When searching 161for a unit, if the specified string does not appear exactly as a unit 162name, then 163.Nm 164will try to remove a trailing 165.Dq s 166or a trailing 167.Dq es 168and check again for a match. 169.Ss Units file format 170To find out what units are available read the standard units file. 171If you want to add your own units you can supply your own file. 172A unit is specified on a single line by 173giving its name and an equivalence. 174Be careful to define 175new units in terms of old ones so that a reduction leads to the 176primitive units which are marked with 177.Dq \&! 178characters. 179The 180.Nm 181program will not detect infinite loops that could be caused 182by careless unit definitions. 183Comments in the unit definition file 184begin with a 185.Dq # 186or 187.Dq / 188character at the beginning of a line. 189.Pp 190Prefixes are defined in the same way as standard units, but with 191a trailing dash 192.Pq Dq - 193at the end of the prefix name. 194If a unit is not found 195even after removing trailing 196.Dq s 197or 198.Dq es , 199then it will be checked against the list of prefixes. 200Prefixes will be removed until a legal 201base unit is identified. 202.Sh ENVIRONMENT 203.Bl -tag -width PATH 204.It Ev PATH 205The colon-separated list of root directories at which 206.Nm 207tries to find 208.Pa /usr/share/misc/definitions.units . 209.Pp 210For example if 211.Ev PATH 212is set to 213.Dq Li /tmp:/:/usr/local , 214no 215.Fl f 216flags are provided, and 217.Pa /usr/share/misc/definitions.units 218is missing then 219.Nm 220tries 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 , 223and 224.Pa /usr/local/usr/share/misc/definitions.units . 225.El 226.Sh FILES 227.Bl -tag -width /usr/share/misc/definitions.units -compact 228.It Pa /usr/share/misc/definitions.units 229The standard units file. 230.El 231.Sh EXIT STATUS 232.Ex -std 233.Sh EXAMPLES 234.Bl -tag -width 0n 235.It Sy Example 1 : No Interactive usage 236.Pp 237Here is an example of an interactive session where the user is prompted for 238units: 239.Bd -literal -offset 2n 240.Li You have : Ic meters 241.Li You want : Ic feet 242 * 3.2808399 243 / 0.3048 244 245.Li You have : Ic cm^3 246.Li You want : Ic gallons 247 * 0.00026417205 248 / 3785.4118 249 250.Li You have : Ic meters/s 251.Li You want : Ic furlongs/fortnight 252 * 6012.8848 253 / 0.00016630952 254 255.Li You have : Ic 1|2 inch 256.Li You want : Ic cm 257 * 1.27 258 / 0.78740157 259 260.Li You have : Ic 85 degF 261.Li You want : Ic degC 262 29.444444 263.Ed 264.It Sy Example 2 : No Difference between Do Ic \&| Dc No and Do Ic / Dc No division 265.Pp 266The following command shows how to convert half a meter to centimeters. 267.Bd -literal -offset 2n 268.Li $ Ic units '1|2 meter' cm 269 * 50 270 / 0.02 271.Ed 272.Pp 273.Nm 274prints the expected result because the division operator for numbers 275.Pq Dq Li \&| 276was used. 277.Pp 278Using the division operator for units 279.Pq Dq Li / 280would result in an error: 281.Bd -literal -offset 2n 282.Li $ Ic units '1/2 meter' cm 283conformability error 284 0.5 / m 285 0.01 m 286.Ed 287.Pp 288It is because 289.Nm 290interprets 291.Dq Ic 1/2 meter 292as 293.Dq Ic 0.5/meter , 294which is not conformable to 295.Dq Ic cm . 296.It Sy Example 3 : No Simple units file 297Here is an example of a short units file that defines some basic 298units: 299.Pp 300.Bl -column -offset 2n -compact "minute" 301.It "m !a!" 302.It "sec !b!" 303.It "micro- 1e-6" 304.It "minute 60 sec" 305.It "hour 60 min" 306.It "inch 0.0254 m" 307.It "ft 12 inches" 308.It "mile 5280 ft" 309.El 310.It Sy Example 4 : No Viewing units and conversions of the default units file 311The following shell one-liner allows the user to view the contents of the 312default units file: 313.Bd -literal -offset 2n 314.Li $ Ic less \&"$(units -U)" 315.Ed 316.El 317.Sh DIAGNOSTICS 318.Bl -diag 319.It can't find units file '%s' 320The default units file is not in its default location 321.Pq see Sx FILES 322and it is not present in any file tree starting with their roots at directories from 323.Ev PATH 324.Pq see Sx ENVIRONMENT . 325.It cap_rights_limit\&() failed 326See 327.Xr capsicum 4 . 328.It conformability error 329It is not possible to reduce the given units to one common unit: 330they are not conformable. 331Instead of a conversion, 332.Nm 333will display the reduced form for each provided unit: 334.Bd -literal -offset 2n 335.Li You have : Ic ergs/hour 336.Li You want : Ic fathoms kg^2 / day 337conformability error 338 2.7777778e-11 kg m^2 / sec^3 339 2.1166667e-05 kg^2 m / sec 340.Ed 341.It Could not initialize history 342See 343.Xr editline 3 . 344.It dupstr 345.Xr strdup 3 346failed. 347.It memory for prefixes exceeded in line %d 348Over 100 prefixes were defined. 349.It memory for units exceeded in line %d 350Over 1000 prefixes were defined. 351.It memory overflow in unit reduction 352The requested conversion involves too many units 353.Pq see Sx BUGS . 354.It redefinition of prefix '%s' on line %d ignored 355.No "" 356.It redefinition of unit '%s' on line %d ignored 357.No "" 358.It unexpected end of prefix on line %d 359.No "" 360.It unexpected end of unit on line %d 361.No "" 362.It Units data file not found 363The default units file is missing. 364.It unable to enter capability mode 365See 366.Xr capsicum 4 . 367.It unable to open units file '%s' 368One of the user-specified units files cannot be opened. 369.It unit reduces to zero 370.No "" 371.It unknown unit '%s' 372The provided unit cannot be found in the units file. 373.It WARNING: conversion of non-proportional quantities. 374.Nm 375may fail to convert 376.Ar from 377to 378.Ar to 379because the units are not proportional. 380The warning is printed when a quantity is a part of the 381.Ar to 382argument. 383It can be illustrated on an example of conversion from Fahrenheit to Celsius: 384.Bd -literal -offset 2n 385.Li $ Ic units \&"degF" \&"degC" 386 (-> x*0.55555556g -17.777778g) 387 (<- y*1.8g 32g) 388.Li $ Ic units \&"degF" \&"1 degC" 389WARNING: conversion of non-proportional quantities. 390 (-> x*0.55555556g -17.777778g) 391 (<- y*1.8g 32g) 392.Li $ Ic units \&"1 degF" \&"1 degC" 393WARNING: conversion of non-proportional quantities. 394 -17.222222 395.Ed 396.El 397.Sh SEE ALSO 398.Xr bc 1 399.Sh HISTORY 400The 401.Nm 402first appeared in 403.Nx 404and was ported to 405.Fx 2.2.0 . 406.Pp 407The manual page was significantly rewritten in 408.Fx 13.0 409by 410.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . 411.Sh AUTHORS 412.An Adrian Mariano Aq Mt adrian@cam.cornell.edu 413.Sh BUGS 414The effect of including a 415.Dq / 416in a prefix is surprising. 417.Pp 418Exponents entered by the user can be only one digit. 419You can work around this by multiplying several terms. 420.Pp 421The user must use 422.Dq Ic \&| 423to indicate division of numbers and 424.Dq Ic / 425to indicate division of symbols. 426This distinction should not 427be necessary. 428.Pp 429The program contains various arbitrary limits on the length 430of the units converted and on the length of the data file. 431.Pp 432The program should use a hash table to store units so that 433it does not take so long to load the units list and check 434for duplication. 435.Pp 436It is not possible to convert a negative value. 437.Pp 438The 439.Nm 440program 441does not handle reductions of long lists of units very well: 442.Bd -literal -offset 2n 443.Li $ Ic units \&"$(yes m | head -n 154)" \&"$(yes cm | head -n 154)" 444 * 1e+308 445 / 1e-308 446.Li $ Ic units \&"$(yes m | head -n 333)" \&"$(yes cm | head -n 333)" 447 * inf 448 / 0 449.Li $ Ic units \&"$(yes m | head -n 500)" \&"$(yes cm | head -n 500)" 450units: memory overflow in unit reduction 451conformability error 452 1 m^500 453 1 centi cm^499 454.Li $ Ic units \&"$(yes m | head -n 501)" \&"$(yes cm | head -n 501)" 455units: memory overflow in unit reduction 456units: memory overflow in unit reduction 457units: memory overflow in unit reduction 458conformability error 459 1 m^500 460 1 centi cm^499 461.Ed 462