usr.bin/units/units.1

   1 .\" $FreeBSD$
   2 .Dd July 14, 1993
   3 .Dt UNITS 1
   4 .Os
   5 .Sh NAME
   6 .Nm units
   7 .Nd conversion program
   8 .Sh SYNOPSIS
   9 .Nm
  10 .Op Fl f Ar filename
  11 .Op Fl qv
  12 .Op Ar from-unit to-unit
  13 .Sh OPTIONS
  14 The following options are available:
  15 .Bl -tag -width indent
  16 .It Fl f Ar filename
  17 Specify the name of the units data file to load.
  18 .It Fl q
  19 Suppress prompting of the user for units and the display of statistics
  20 about the number of units loaded.
  21 .It Fl v
  22 Print the version number.
  23 .It Ar from-unit to-unit
  24 Allow a single unit conversion to be done directly from the command
  25 line.
  26 The program will not print prompts.
  27 It will print out the
  28 result of the single specified conversion.
  29 .El
  30 .Sh DESCRIPTION
  31 The
  32 .Nm
  33 program converts quantities expressed in various scales to
  34 their equivalents in other scales.
  35 The
  36 .Nm
  37 program can only
  38 handle multiplicative or affine scale changes.
  39 It works interactively by prompting
  40 the user for input:
  41 .Bd -literal
  42     You have: meters
  43     You want: feet
  44             * 3.2808399
  45             / 0.3048
  46
  47     You have: cm^3
  48     You want: gallons
  49             * 0.00026417205
  50             / 3785.4118
  51
  52     You have: meters/s
  53     You want: furlongs/fortnight
  54             * 6012.8848
  55             / 0.00016630952
  56
  57     You have: 1|2 inch
  58     You want: cm
  59             * 1.27
  60             / 0.78740157
  61
  62     You have: 85 degF
  63     You want: degC
  64         29.444444
  65 .Ed
  66 .Pp
  67 Powers of units can be specified using the '^' character as shown in
  68 the example, or by simple concatenation: 'cm3' is equivalent to 'cm^3'.
  69 Multiplication of units can be specified by using spaces, a dash or
  70 an asterisk.
  71 Division of units is indicated by the slash ('/').
  72 Note that multiplication has a higher precedence than division,
  73 so 'm/s/s' is the same as 'm/s^2' or 'm/s s'.
  74 Division of numbers
  75 must be indicated using the vertical bar ('|').
  76 To convert half a
  77 meter, you would write '1|2 meter'.
  78 If you write '1/2 meter' then the
  79 units program would interpret that as equivalent to '0.5/meter'.
  80 If you enter incompatible unit types, the units program will
  81 print a message indicating that the units are not conformable and
  82 it will display the reduced form for each unit:
  83 .Bd -literal
  84     You have: ergs/hour
  85     You want: fathoms kg^2 / day
  86     conformability error
  87             2.7777778e-11 kg m^2 / sec^3
  88             2.1166667e-05 kg^2 m / sec
  89 .Ed
  90 .Pp
  91 The conversion information is read from a units data file.
  92 The default
  93 file includes definitions for most familiar units, abbreviations and
  94 metric prefixes.
  95 Some constants of nature included are:
  96 .Pp
  97 .Bl -column -offset indent -compact "mercury"
  98 .It "pi ratio of circumference to diameter
  99 .It "c  speed of light
 100 .It "e  charge on an electron
 101 .It "g  acceleration of gravity
 102 .It "force      same as g
 103 .It "mole       Avogadro's number
 104 .It "water      pressure per unit height of water
 105 .It "mercury    pressure per unit height of mercury
 106 .It "au astronomical unit
 107 .El
 108 .Pp
 109 The unit 'pound' is a unit of mass.
 110 Compound names are run together
 111 so 'pound force' is a unit of force.
 112 The unit 'ounce' is also a unit
 113 of mass.
 114 The fluid ounce is 'floz'.
 115 British units that differ from
 116 their US counterparts are prefixed with 'br', and currency is prefixed
 117 with its country name: 'belgiumfranc', 'britainpound'.
 118 When searching
 119 for a unit, if the specified string does not appear exactly as a unit
 120 name, then
 121 .Nm
 122 will try to remove a trailing 's' or a
 123 trailing 'es' and check again for a match.
 124 .Pp
 125 To find out what units are available read the standard units file.
 126 If you want to add your own units you can supply your own file.
 127 A unit is specified on a single line by
 128 giving its name and an equivalence.
 129 Be careful to define
 130 new units in terms of old ones so that a reduction leads to the
 131 primitive units which are marked with '!' characters.
 132 The
 133 .Nm
 134 program will not detect infinite loops that could be caused
 135 by careless unit definitions.
 136 Comments in the unit definition file
 137 begin with a '/' character at the beginning of a line.
 138 .Pp
 139 Prefixes are defined in the same was as standard units, but with
 140 a trailing dash at the end of the prefix name.
 141 If a unit is not found
 142 even after removing trailing 's' or 'es', then it will be checked
 143 against the list of prefixes.
 144 Prefixes will be removed until a legal
 145 base unit is identified.
 146 .Pp
 147 Here is an example of a short units file that defines some basic
 148 units.
 149 .Pp
 150 .Bl -column -offset indent -compact "minute"
 151 .It "m  !a!
 152 .It "sec        !b!
 153 .It "micro-     1e-6
 154 .It "minute     60 sec
 155 .It "hour       60 min
 156 .It "inch       0.0254 m
 157 .It "ft 12 inches
 158 .It "mile       5280 ft
 159 .El
 160 .Sh FILES
 161 .Bl -tag -width /usr/share/misc/units.lib -compact
 162 .It Pa /usr/share/misc/units.lib
 163 the standard units library
 164 .El
 165 .Sh AUTHORS
 166 .An Adrian Mariano Aq adrian@cam.cornell.edu
 167 .Sh BUGS
 168 The effect of including a '/' in a prefix is surprising.
 169 .Pp
 170 Exponents entered by the user can be only one digit.
 171 You can work around this by multiplying several terms.
 172 .Pp
 173 The user must use | to indicate division of numbers and / to
 174 indicate division of symbols.
 175 This distinction should not
 176 be necessary.
 177 .Pp
 178 The program contains various arbitrary limits on the length
 179 of the units converted and on the length of the data file.
 180 .Pp
 181 The program should use a hash table to store units so that
 182 it does not take so long to load the units list and check
 183 for duplication.