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