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