/usr.bin/units/units.1

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