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