1.\" $NetBSD: units.1,v 1.17 2011/04/03 19:44:15 dholland Exp $ 2.Dd April 3, 2011 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.Oo 13.Op Ar count 14.Ar from-unit to-unit 15.Oc 16.Sh DESCRIPTION 17.Nm 18converts quantities expression in various scales to 19their equivalents in other scales. 20.Nm 21can only handle multiplicative scale changes. 22It cannot convert Centigrade to Fahrenheit, for example. 23.Pp 24The following options are supported: 25.Bl -tag -width "from-unit to-unit" -offset indent 26.It Fl f Ar filename 27Specifies the name of the units data file to load. 28.It Fl q 29Suppresses prompting of the user for units and the display of statistics 30about the number of units loaded. 31.It Fl v 32Prints the version number. 33.It Ar from-unit Ar to-unit 34Allows a single unit conversion to be done directly from the command 35line. 36No prompting will occur. 37.Nm 38will print out only the result of this single conversion. 39The 40.Ar count 41argument can be prepended to the 42.Ar from-unit 43or it can be separate. 44.El 45.Pp 46.Nm 47works interactively by prompting the user for input: 48.Bd -literal 49 You have: meters 50 You want: feet 51 * 3.2808399 52 / 0.3048 53 54 You have: cm^3 55 You want: gallons 56 * 0.00026417205 57 / 3785.4118 58.Ed 59.Pp 60Powers of units can be specified using the 61.Dq \&^ 62character as shown in the example, or by simple concatenation: 63.Dq cm3 64is equivalent to 65.Dq cm^3 . 66Multiplication of units can be specified by using spaces, a dash or 67an asterisk. 68Division of units is indicated by the slash 69.Pq Sq \&/ . 70Note that multiplication has a higher precedence than division, 71so 72.Dq m/s/s 73is the same as 74.Dq m/s^2 75or 76.Dq "m/s s" . 77If the user enters incompatible unit types, the 78.Nm 79program will print a message indicating that the units are not 80conformable and it will display the reduced form for each unit: 81.Bd -literal 82 You have: ergs/hour 83 You want: fathoms kg^2 / day 84 conformability error 85 2.7777778e-11 kg m^2 / sec^3 86 2.1166667e-05 kg^2 m / sec 87.Ed 88.Pp 89The conversion information is read from a units data file. 90The default 91file includes definitions for most familiar units, abbreviations and 92metric prefixes. 93Some constants of nature included are: 94.Bl -tag -width mercury -compact -offset indent 95.It pi 96ratio of circumference to diameter 97.It c 98speed of light 99.It e 100charge on an electron 101.It g 102acceleration of gravity 103.It force 104same as g 105.It mole 106Avogadro's number 107.It water 108pressure per unit height of water 109.It mercury 110pressure per unit height of mercury 111.It au 112astronomical unit 113.El 114.Pp 115.Dq pound 116is a unit of mass. 117Compound names are run together 118so 119.Dq poundforce 120is a unit of force. 121British units that differ from their 122US counterparts are prefixed with 123.Dq br , 124and currency is prefixed with 125its country name: 126.Dq belgiumfranc , 127.Dq britainpound . 128When searching for 129a unit, if the specified string does not appear exactly as a unit 130name, then the 131.Nm 132program will try to remove a trailing 133.Dq s 134or a trailing 135.Dq es 136and check again for a match. 137.Pp 138All of these definitions can be read in the standard units file, or you 139can supply your own file. 140A unit is specified on a single line by 141giving its name and an equivalence. 142One should be careful to define 143new units in terms of old ones so that a reduction leads to the 144primitive units which are marked with 145.Sq \&! 146characters. 147.Nm 148will not detect infinite loops that could be caused 149by careless unit definitions. 150.Pp 151Prefixes are defined in the same way as standard units, but with 152a trailing dash at the end of the prefix name. 153.Sh FILES 154.Bl -tag -width /usr/share/misc/units.lib -compact 155.It Pa /usr/share/misc/units.lib 156the standard units library 157.El 158.Sh AUTHORS 159.An Adrian Mariano Aq adrian@cam.cornell.edu 160or 161.Aq mariano@geom.umn.edu 162.Sh CAVEATS 163While 164.Nm 165can be used as a calculator for many unit-related computations, 166caution is required: many computations require additional constant 167factors deriving from the physics (or chemistry or whatever) of the 168situation. 169As these factors are dimensionless, 170.Nm 171cannot itself either provide them or warn the user when they have been 172forgotten. 173For example, one joule is one kilogram meter squared per second 174squared, by definition; however, the kinetic energy of a one-kilogram 175object moving at one meter per second is half a joule, not one joule, 176because of a dimensionless factor that arises from integration. 177.Pp 178Also, some pairs of units that have the same dimensionality are 179nonetheless used to measure different things and attempting to convert 180between them may require additional fudge factors or be entirely 181meaningless. 182For example, torque and energy have the same dimensionality, but 183attempting to convert torque in newton-meters to energy in joules is 184nonsensical. 185There is no practical way for 186.Nm 187to warn about these issues either. 188.Sh BUGS 189The effect of including a 190.Sq \&/ 191in a prefix is surprising. 192.Pp 193Exponents entered by the user can be only one digit. 194You can work around this by multiplying several terms. 195.Pp 196The user must use 197.Sq \&| 198to indicate division of numbers and 199.Sq \&/ 200to indicate division of symbols. 201This distinction should not be necessary. 202.Pp 203The program contains various arbitrary limits on the length 204of the units converted and on the length of the data file. 205.Pp 206The program should use a hash table to store units so that 207it doesn't take so long to load the units list and check 208for duplication. 209