usr.bin/units/units.1

   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
  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 Interactive usage
 236 .Pp
 237 Here is an example of an interactive session where the user is prompted for
 238 units:
 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
 266 The 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
 274 prints the expected result because the division operator for numbers
 275 .Pq Dq Li \&|
 276 was used.
 277 .Pp
 278 Using the division operator for units
 279 .Pq Dq Li /
 280 would result in an error:
 281 .Bd -literal -offset 2n
 282 .Li $ Ic units '1/2 meter' cm
 283 conformability error
 284         0.5 / m
 285         0.01 m
 286 .Ed
 287 .Pp
 288 It is because
 289 .Nm
 290 interprets
 291 .Dq Ic 1/2 meter
 292 as
 293 .Dq Ic 0.5/meter ,
 294 which is not conformable to
 295 .Dq Ic cm .
 296 .It Sy Example 3 : No Simple units file
 297 Here is an example of a short units file that defines some basic
 298 units:
 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
 311 The following shell one-liner allows the user to view the contents of the
 312 default 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'
 320 The default units file is not in its default location
 321 .Pq see Sx FILES
 322 and 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
 326 See
 327 .Xr capsicum  4 .
 328 .It conformability error
 329 It is not possible to reduce the given units to one common unit:
 330 they are not conformable.
 331 Instead of a conversion,
 332 .Nm
 333 will 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
 337 conformability 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
 342 See
 343 .Xr editline 3 .
 344 .It dupstr
 345 .Xr strdup 3
 346 failed.
 347 .It memory for prefixes exceeded in line %d
 348 Over 100 prefixes were defined.
 349 .It memory for units exceeded in line %d
 350 Over 1000 prefixes were defined.
 351 .It memory overflow in unit reduction
 352 The 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
 363 The default units file is missing.
 364 .It unable to enter capability mode
 365 See
 366 .Xr capsicum  4 .
 367 .It unable to open units file '%s'
 368 One of the user-specified units files cannot be opened.
 369 .It unit reduces to zero
 370 .No ""
 371 .It unknown unit '%s'
 372 The provided unit cannot be found in the units file.
 373 .It WARNING: conversion of non-proportional quantities.
 374 .Nm
 375 may fail to convert
 376 .Ar from
 377 to
 378 .Ar to
 379 because the units are not proportional.
 380 The warning is printed when a quantity is a part of the
 381 .Ar to
 382 argument.
 383 It 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"
 389 WARNING: conversion of non-proportional quantities.
 390          (-> x*0.55555556g -17.777778g)
 391          (<- y*1.8g 32g)
 392 .Li $ Ic units \&"1 degF" \&"1 degC"
 393 WARNING: conversion of non-proportional quantities.
 394         -17.222222
 395 .Ed
 396 .El
 397 .Sh SEE ALSO
 398 .Xr bc 1
 399 .Sh HISTORY
 400 The
 401 .Nm
 402 first appeared in
 403 .Nx
 404 and was ported to
 405 .Fx 2.2.0 .
 406 .Pp
 407 The manual page was significantly rewritten in
 408 .Fx 13.0
 409 by
 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
 414 The effect of including a
 415 .Dq /
 416 in a prefix is surprising.
 417 .Pp
 418 Exponents entered by the user can be only one digit.
 419 You can work around this by multiplying several terms.
 420 .Pp
 421 The user must use
 422 .Dq Ic \&|
 423 to indicate division of numbers and
 424 .Dq Ic /
 425 to indicate division of symbols.
 426 This distinction should not
 427 be necessary.
 428 .Pp
 429 The program contains various arbitrary limits on the length
 430 of the units converted and on the length of the data file.
 431 .Pp
 432 The program should use a hash table to store units so that
 433 it does not take so long to load the units list and check
 434 for duplication.
 435 .Pp
 436 It is not possible to convert a negative value.
 437 .Pp
 438 The
 439 .Nm
 440 program
 441 does 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)"
 450 units: memory overflow in unit reduction
 451 conformability error
 452         1 m^500
 453         1 centi cm^499
 454 .Li $ Ic units \&"$(yes m | head -n 501)" \&"$(yes cm | head -n 501)"
 455 units: memory overflow in unit reduction
 456 units: memory overflow in unit reduction
 457 units: memory overflow in unit reduction
 458 conformability error
 459         1 m^500
 460         1 centi cm^499
 461 .Ed