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