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