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