usr.bin/units/units.1

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