Annotation of src/usr.bin/units/units.1, Revision 1.28
1.28 ! florian 1: .\" $OpenBSD: units.1,v 1.27 2022/02/18 10:24:33 jsg 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.28 ! florian 19: .Dd $Mdocdate: February 18 2022 $
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.25 jmc 29: .Op Oo Ar count Oc 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.24 jmc 41: .Pp
42: .Nm
43: works interactively by prompting the user for input:
1.15 jmc 44: .Bd -literal -offset indent
45: You have: meters
46: You want: feet
47: * 3.2808399
48: / 0.3048
1.1 deraadt 49:
1.15 jmc 50: You have: cm^3
51: You want: gallons
52: * 0.00026417205
53: / 3785.4118
54: .Ed
1.13 pjanzen 55: .Pp
1.24 jmc 56: That is, one meter equals roughly 3.28 feet
57: (or, conversely, one foot is roughly equal to 0.3 meters),
58: and one gallon is roughly equal to 3785 cubic cm.
59: .Pp
1.13 pjanzen 60: The
61: .Nm
62: program can handle numbers as well:
1.15 jmc 63: .Bd -literal -offset indent
64: You have: 60 miles/hr
65: You want: km/hr
66: * 96.56064
67: / 0.010356187
1.13 pjanzen 68:
1.24 jmc 69: You have: 100 USD
70: You want: 10 euro
71: * 7.4354971
72: / 0.13449
1.15 jmc 73: .Ed
1.13 pjanzen 74: .Pp
1.24 jmc 75: In other words, 60 miles per hour is about 96.6 km/hr,
76: and 100 US dollars will get you seven 10-Euro notes.
1.4 deraadt 77: .Pp
1.10 aaron 78: The options are as follows:
79: .Bl -tag -width Ds
80: .It Fl f Ar filename
81: Specifies the name of the units data file to load.
1.28 ! florian 82: This option may be specified multiple times.
! 83: The standard units library is read if
! 84: .Ar filename
! 85: is the empty string.
! 86: This allows extending the standard units library with a personal library.
1.10 aaron 87: .It Fl q
88: Suppresses prompting of the user for units and the display of statistics
89: about the number of units loaded.
90: .It Fl v
91: Prints the version number.
1.25 jmc 92: .It Oo Ar count Oc Ar from-unit to-unit
1.10 aaron 93: Allows a single unit conversion to be done directly from the command line.
94: No prompting will occur.
95: The units program will print out
96: only the result of this single conversion.
1.25 jmc 97: A
98: .Ar count
99: can be given to specify multiples of
100: .Ar from-unit .
1.10 aaron 101: .El
102: .Pp
1.8 aaron 103: Powers of units can be specified using the
104: .Ql ^
105: character as shown in
106: the example, or by simple concatenation:
1.9 pjanzen 107: .Sq cm3
1.8 aaron 108: is equivalent to
1.9 pjanzen 109: .Sq cm^3 .
1.1 deraadt 110: Multiplication of units can be specified by using spaces, a dash or
1.10 aaron 111: an asterisk.
112: Division of units is indicated by the slash
1.8 aaron 113: .Pq Ql / .
114: Note that multiplication has a higher precedence than division, so
1.9 pjanzen 115: .Sq m/s/s
1.8 aaron 116: is the same as
1.9 pjanzen 117: .Sq m/s^2
1.8 aaron 118: or
1.9 pjanzen 119: .Sq m/s s .
1.1 deraadt 120: If the user enters incompatible unit types, the units program will
121: print a message indicating that the units are not conformable and
122: it will display the reduced form for each unit:
1.15 jmc 123: .Bd -literal -offset indent
124: You have: ergs/hour
125: You want: fathoms kg^2 / day
126: conformability error
127: 2.7777778e-11 kg m^2 / sec^3
128: 2.1166667e-05 kg^2 m / sec
129: .Ed
1.4 deraadt 130: .Pp
1.10 aaron 131: The conversion information is read from a units data file.
132: The default file includes definitions for most familiar units,
133: abbreviations and metric prefixes.
134: Some constants of nature included are:
1.23 jmc 135: .Pp
136: .Bl -tag -width mercuryXXX -offset indent -compact
1.4 deraadt 137: .It pi
138: ratio of circumference to diameter
139: .It c
140: speed of light
141: .It e
142: charge on an electron
143: .It g
144: acceleration of gravity
145: .It force
146: same as g
147: .It mole
148: Avogadro's number
149: .It water
1.9 pjanzen 150: pressure per unit height of water (at 4 C)
1.4 deraadt 151: .It mercury
152: pressure per unit height of mercury
1.9 pjanzen 153: .It ao
154: Bohr radius
155: .It AU
1.4 deraadt 156: astronomical unit
157: .El
158: .Pp
1.9 pjanzen 159: .Sq Pound
1.10 aaron 160: is a unit of mass.
161: Compound names are run together so
1.9 pjanzen 162: .Sq poundforce
1.10 aaron 163: is a unit of force.
164: British units that differ from their US counterparts are prefixed with
1.9 pjanzen 165: .Sq br ,
166: and currency is prefixed with its country name:
167: .Sq belgiumfranc ,
168: .Sq britainpound .
169: When searching for
1.1 deraadt 170: a unit, if the specified string does not appear exactly as a unit
1.9 pjanzen 171: name, then the units program will try to remove a trailing
172: .Sq s
173: or a trailing
174: .Sq es
175: and check again for a match.
1.4 deraadt 176: .Pp
1.1 deraadt 177: All of these definitions can be read in the standard units file, or you
1.10 aaron 178: can supply your own file.
179: A unit is specified on a single line by
180: giving its name and an equivalence.
181: One should be careful to define
1.1 deraadt 182: new units in terms of old ones so that a reduction leads to the
1.8 aaron 183: primitive units which are marked with
1.16 jmc 184: .Ql \&!
1.8 aaron 185: characters.
1.1 deraadt 186: The units program will not detect infinite loops that could be caused
187: by careless unit definitions.
1.4 deraadt 188: .Pp
1.8 aaron 189: Prefixes are defined in the same way as standard units, but with
1.10 aaron 190: a trailing dash at the end of the prefix name.
191: Prefixes are applied
1.9 pjanzen 192: after the longest matching unit name is found; for example,
193: .Dq nmile
194: is taken to be a nautical mile rather than a nanomile.
1.12 aaron 195: .Sh FILES
196: .Bl -tag -width /usr/share/misc/units.lib
197: .It Pa /usr/share/misc/units.lib
198: the standard units library
199: .El
1.21 jmc 200: .Sh SEE ALSO
201: .Rs
202: .%I International Bureau of Weights and Measures
203: .%T The International System of Units
1.27 jsg 204: .%U https://www.bipm.org/utils/common/pdf/si_brochure_8.pdf
1.21 jmc 205: .Re
206: .Rs
207: .%R ISO 4217
208: .%T Codes for the representation of currencies and funds
209: .%D 2008
1.22 jmc 210: .Re
211: .Rs
212: .%R ISO/IEC 80000
213: .%T Quantities and units \(em Part 13: Information science and technology
1.21 jmc 214: .Re
1.12 aaron 215: .Sh AUTHORS
1.26 schwarze 216: .An Adrian Mariano Aq Mt adrian@cam.cornell.edu
217: or
218: .Aq Mt mariano@geom.umn.edu
1.4 deraadt 219: .Sh BUGS
1.8 aaron 220: The effect of including a
221: .Ql /
222: in a prefix is surprising.
1.4 deraadt 223: .Pp
1.9 pjanzen 224: Exponents of units entered by the user can be only one digit.
1.1 deraadt 225: You can work around this by multiplying several terms.
1.4 deraadt 226: .Pp
1.10 aaron 227: The user must use
228: .Ql |
229: to indicate division of numbers and
230: .Ql /
231: to indicate division of symbols.
232: This distinction should not be necessary.
1.9 pjanzen 233: .Pp
234: Prefixes specified without a unit are treated as dimensionless quantities.
235: This can lead to confusion when some prefixes are also defined as units
1.10 aaron 236: (e.g., m).
237: For example, Tera- / Giga- is 1000, but one Tesla (T) is 10,000
1.9 pjanzen 238: Gauss (G).
239: .Pp
1.17 jmc 240: Some non-SI units have multiple definitions (e.g., barrel, calorie) and
1.10 aaron 241: others have changed over time (e.g., cubit).
242: In particular, monetary values fluctuate.
1.4 deraadt 243: .Pp
1.1 deraadt 244: The program contains various arbitrary limits on the length
245: of the units converted and on the length of the data file.
1.4 deraadt 246: .Pp
1.1 deraadt 247: The program should use a hash table to store units so that
248: it doesn't take so long to load the units list and check
1.8 aaron 249: for duplication.