usr.bin/units/units.1

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