Annotation of src/usr.bin/units/units.1, Revision 1.23
1.23 ! jmc 1: .\" $OpenBSD: units.1,v 1.22 2011/10/06 19:52:09 jmc Exp $
1.4 deraadt 2: .\" converted to new format by deraadt@openbsd.org
1.14 jmc 3: .\"
4: .\" Copyright (c) 1993 by Adrian Mariano (adrian@cam.cornell.edu)
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. The name of the author may not be used to endorse or promote products
12: .\" derived from this software without specific prior written permission.
13: .\" Disclaimer: This software is provided by the author "as is". The author
14: .\" shall not be liable for any damages caused in any way by this software.
15: .\"
16: .\" I would appreciate (though I do not require) receiving a copy of any
17: .\" improvements you might make to this program.
1.15 jmc 18: .\"
1.23 ! jmc 19: .Dd $Mdocdate: October 6 2011 $
1.4 deraadt 20: .Dt UNITS 1
21: .Os
22: .Sh NAME
1.5 deraadt 23: .Nm units
1.4 deraadt 24: .Nd conversion program
25: .Sh SYNOPSIS
1.7 aaron 26: .Nm units
1.19 jmc 27: .Op Fl qv
1.4 deraadt 28: .Op Fl f Ar filename
1.19 jmc 29: .Op Ar from-unit to-unit
1.4 deraadt 30: .Sh DESCRIPTION
1.10 aaron 31: The
32: .Nm
1.11 pjanzen 33: program converts quantities expressed in various scales to
1.10 aaron 34: their equivalents in other scales.
35: The
36: .Nm
37: program can only handle multiplicative scale changes.
38: It cannot convert Celsius
39: to Fahrenheit, for example.
1.11 pjanzen 40: It also does not handle logarithmic units such as bels.
1.10 aaron 41: It works interactively by prompting the user for input:
1.15 jmc 42: .Bd -literal -offset indent
43: You have: meters
44: You want: feet
45: * 3.2808399
46: / 0.3048
1.1 deraadt 47:
1.15 jmc 48: You have: cm^3
49: You want: gallons
50: * 0.00026417205
51: / 3785.4118
52: .Ed
1.13 pjanzen 53: .Pp
54: The
55: .Nm
56: program can handle numbers as well:
1.15 jmc 57: .Bd -literal -offset indent
58: You have: 60 miles/hr
59: You want: km/hr
60: * 96.56064
61: / 0.010356187
1.13 pjanzen 62:
1.15 jmc 63: You have: 5 austriaschilling
64: You want: 100 italylira
65: * 7.0357114
66: / 0.14213204
67: .Ed
1.13 pjanzen 68: .Pp
69: In other words, 60 miles per hour is about 96.6 km/hr, and 5 Austrian
70: Schillings will get you seven 100-Lira coins.
1.4 deraadt 71: .Pp
1.10 aaron 72: The options are as follows:
73: .Bl -tag -width Ds
74: .It Fl f Ar filename
75: Specifies the name of the units data file to load.
76: .It Fl q
77: Suppresses prompting of the user for units and the display of statistics
78: about the number of units loaded.
79: .It Fl v
80: Prints the version number.
81: .It Ar from-unit Ar to-unit
82: Allows a single unit conversion to be done directly from the command line.
83: No prompting will occur.
84: The units program will print out
85: only the result of this single conversion.
86: .El
87: .Pp
1.8 aaron 88: Powers of units can be specified using the
89: .Ql ^
90: character as shown in
91: the example, or by simple concatenation:
1.9 pjanzen 92: .Sq cm3
1.8 aaron 93: is equivalent to
1.9 pjanzen 94: .Sq cm^3 .
1.1 deraadt 95: Multiplication of units can be specified by using spaces, a dash or
1.10 aaron 96: an asterisk.
97: Division of units is indicated by the slash
1.8 aaron 98: .Pq Ql / .
99: Note that multiplication has a higher precedence than division, so
1.9 pjanzen 100: .Sq m/s/s
1.8 aaron 101: is the same as
1.9 pjanzen 102: .Sq m/s^2
1.8 aaron 103: or
1.9 pjanzen 104: .Sq m/s s .
1.1 deraadt 105: If the user enters incompatible unit types, the units program will
106: print a message indicating that the units are not conformable and
107: it will display the reduced form for each unit:
1.15 jmc 108: .Bd -literal -offset indent
109: You have: ergs/hour
110: You want: fathoms kg^2 / day
111: conformability error
112: 2.7777778e-11 kg m^2 / sec^3
113: 2.1166667e-05 kg^2 m / sec
114: .Ed
1.4 deraadt 115: .Pp
1.10 aaron 116: The conversion information is read from a units data file.
117: The default file includes definitions for most familiar units,
118: abbreviations and metric prefixes.
119: Some constants of nature included are:
1.23 ! jmc 120: .Pp
! 121: .Bl -tag -width mercuryXXX -offset indent -compact
1.4 deraadt 122: .It pi
123: ratio of circumference to diameter
124: .It c
125: speed of light
126: .It e
127: charge on an electron
128: .It g
129: acceleration of gravity
130: .It force
131: same as g
132: .It mole
133: Avogadro's number
134: .It water
1.9 pjanzen 135: pressure per unit height of water (at 4 C)
1.4 deraadt 136: .It mercury
137: pressure per unit height of mercury
1.9 pjanzen 138: .It ao
139: Bohr radius
140: .It AU
1.4 deraadt 141: astronomical unit
142: .El
143: .Pp
1.9 pjanzen 144: .Sq Pound
1.10 aaron 145: is a unit of mass.
146: Compound names are run together so
1.9 pjanzen 147: .Sq poundforce
1.10 aaron 148: is a unit of force.
149: British units that differ from their US counterparts are prefixed with
1.9 pjanzen 150: .Sq br ,
151: and currency is prefixed with its country name:
152: .Sq belgiumfranc ,
153: .Sq britainpound .
154: When searching for
1.1 deraadt 155: a unit, if the specified string does not appear exactly as a unit
1.9 pjanzen 156: name, then the units program will try to remove a trailing
157: .Sq s
158: or a trailing
159: .Sq es
160: and check again for a match.
1.4 deraadt 161: .Pp
1.1 deraadt 162: All of these definitions can be read in the standard units file, or you
1.10 aaron 163: can supply your own file.
164: A unit is specified on a single line by
165: giving its name and an equivalence.
166: One should be careful to define
1.1 deraadt 167: new units in terms of old ones so that a reduction leads to the
1.8 aaron 168: primitive units which are marked with
1.16 jmc 169: .Ql \&!
1.8 aaron 170: characters.
1.1 deraadt 171: The units program will not detect infinite loops that could be caused
172: by careless unit definitions.
1.4 deraadt 173: .Pp
1.8 aaron 174: Prefixes are defined in the same way as standard units, but with
1.10 aaron 175: a trailing dash at the end of the prefix name.
176: Prefixes are applied
1.9 pjanzen 177: after the longest matching unit name is found; for example,
178: .Dq nmile
179: is taken to be a nautical mile rather than a nanomile.
1.12 aaron 180: .Sh FILES
181: .Bl -tag -width /usr/share/misc/units.lib
182: .It Pa /usr/share/misc/units.lib
183: the standard units library
184: .El
1.21 jmc 185: .Sh SEE ALSO
186: .Rs
187: .%I International Bureau of Weights and Measures
188: .%T The International System of Units
189: .%U http://www.bipm.org/utils/common/pdf/si_brochure_8.pdf
190: .Re
191: .Rs
192: .%R ISO 4217
193: .%T Codes for the representation of currencies and funds
194: .%D 2008
1.22 jmc 195: .Re
196: .Rs
197: .%R ISO/IEC 80000
198: .%T Quantities and units \(em Part 13: Information science and technology
1.21 jmc 199: .Re
1.12 aaron 200: .Sh AUTHORS
201: Adrian Mariano (adrian@cam.cornell.edu or mariano@geom.umn.edu)
1.4 deraadt 202: .Sh BUGS
1.8 aaron 203: The effect of including a
204: .Ql /
205: in a prefix is surprising.
1.4 deraadt 206: .Pp
1.9 pjanzen 207: Exponents of units entered by the user can be only one digit.
1.1 deraadt 208: You can work around this by multiplying several terms.
1.4 deraadt 209: .Pp
1.10 aaron 210: The user must use
211: .Ql |
212: to indicate division of numbers and
213: .Ql /
214: to indicate division of symbols.
215: This distinction should not be necessary.
1.9 pjanzen 216: .Pp
217: Prefixes specified without a unit are treated as dimensionless quantities.
218: This can lead to confusion when some prefixes are also defined as units
1.10 aaron 219: (e.g., m).
220: For example, Tera- / Giga- is 1000, but one Tesla (T) is 10,000
1.9 pjanzen 221: Gauss (G).
222: .Pp
1.17 jmc 223: Some non-SI units have multiple definitions (e.g., barrel, calorie) and
1.10 aaron 224: others have changed over time (e.g., cubit).
225: In particular, monetary values fluctuate.
1.4 deraadt 226: .Pp
1.1 deraadt 227: The program contains various arbitrary limits on the length
228: of the units converted and on the length of the data file.
1.4 deraadt 229: .Pp
1.1 deraadt 230: The program should use a hash table to store units so that
231: it doesn't take so long to load the units list and check
1.8 aaron 232: for duplication.