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