| blob | 8232e99f9cd21d848f178d21a639dddec2b30e3a |
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
15 The following options are available:
16 .Bl -tag -width indent
17 .It Fl f Ar filename
18 Specify the name of the units data file to load.
19 .It Fl q
20 Suppress prompting of the user for units and the display of statistics
21 about the number of units loaded.
22 .It Fl v
23 Print the version number.
24 .It Ar from-unit to-unit
25 Allow a single unit conversion to be done directly from the command
26 line.
27 The program will not print prompts.
28 It will print out the
29 result of the single specified conversion.
30 .El
31 .Sh DESCRIPTION
32 The
33 .Nm
34 program converts quantities expressed in various scales to
35 their equivalents in other scales.
36 The
37 .Nm
38 program can only
39 handle multiplicative scale changes.
40 Experimental support is available to convert Celsius to Fahrenheit.
41 It works interactively by prompting
42 the user for input:
43 .Bd -literal
44 You have: meters
45 You want: feet
46 * 3.2808399
47 / 0.3048
49 You have: cm^3
50 You want: gallons
51 * 0.00026417205
52 / 3785.4118
54 You have: meters/s
55 You want: furlongs/fortnight
56 * 6012.8848
57 / 0.00016630952
59 You have: 1|2 inch
60 You want: cm
61 * 1.27
62 / 0.78740157
64 You have: 20 degC
65 You want: degF
66 68
67 .Ed
68 .Pp
69 Powers of units can be specified using the '^' character as shown in
70 the example, or by simple concatenation: 'cm3' is equivalent to 'cm^3'.
71 Multiplication of units can be specified by using spaces, a dash or
72 an asterisk.
73 Division of units is indicated by the slash ('/').
74 Note that multiplication has a higher precedence than division,
75 so 'm/s/s' is the same as 'm/s^2' or 'm/s s'.
76 Division of numbers
77 must be indicated using the vertical bar ('|').
78 To convert half a
79 meter, you would write '1|2 meter'.
80 If you write '1/2 meter' then the
81 units program would interpret that as equivalent to '0.5/meter'.
82 If you enter incompatible unit types, the units program will
83 print a message indicating that the units are not conformable and
84 it 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
93 The conversion information is read from a units data file.
94 The default
95 file includes definitions for most familiar units, abbreviations and
96 metric prefixes.
97 Some 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
111 The unit 'pound' is a unit of mass.
112 Compound names are run together
113 so 'pound force' is a unit of force.
114 The unit 'ounce' is also a unit
115 of mass.
116 The fluid ounce is 'floz'.
117 British units that differ from
118 their US counterparts are prefixed with 'br', and currency is prefixed
119 with its country name: 'belgiumfranc', 'britainpound'.
120 When searching
121 for a unit, if the specified string does not appear exactly as a unit
122 name, then
123 .Nm
124 will try to remove a trailing 's' or a
125 trailing 'es' and check again for a match.
126 .Pp
127 To find out what units are available read the standard units file.
128 If you want to add your own units you can supply your own file.
129 A unit is specified on a single line by
130 giving its name and an equivalence.
131 Be careful to define
132 new units in terms of old ones so that a reduction leads to the
133 primitive units which are marked with '!' characters.
134 The
135 .Nm
136 program will not detect infinite loops that could be caused
137 by careless unit definitions.
138 Comments in the unit definition file
139 begin with a '/' character at the beginning of a line.
140 .Pp
141 Prefixes are defined in the same was as standard units, but with
142 a trailing dash at the end of the prefix name.
143 If a unit is not found
144 even after removing trailing 's' or 'es', then it will be checked
145 against the list of prefixes.
146 Prefixes will be removed until a legal
147 base unit is identified.
148 .Pp
149 Here is an example of a short units file that defines some basic
150 units.
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
165 the standard units library
166 .El
167 .Sh AUTHORS
168 .An Adrian Mariano Aq adrian@cam.cornell.edu
169 .Sh BUGS
170 The effect of including a '/' in a prefix is surprising.
171 .Pp
172 Exponents entered by the user can be only one digit.
173 You can work around this by multiplying several terms.
174 .Pp
175 The user must use | to indicate division of numbers and / to
176 indicate division of symbols.
177 This distinction should not
178 be necessary.
179 .Pp
180 The program contains various arbitrary limits on the length
181 of the units converted and on the length of the data file.
182 .Pp
183 The program should use a hash table to store units so that
184 it does not take so long to load the units list and check
185 for duplication.