usr.bin/units/units.1

   1 .\"     $NetBSD: units.1,v 1.22 2014/03/18 18:20:45 riastradh Exp $
   2 .Dd January 6, 2013
   3 .Dt UNITS 1
   4 .Os
   5 .Sh NAME
   6 .Nm units
   7 .Nd conversion program
   8 .Sh SYNOPSIS
   9 .Nm
  10 .Op Fl Llqv
  11 .Op Fl f Ar filename
  12 .Oo
  13 .Op Ar count
  14 .Ar from-unit to-unit
  15 .Oc
  16 .Sh DESCRIPTION
  17 .Nm
  18 converts quantities expression in various scales to
  19 their equivalents in other scales.
  20 .Nm
  21 can only handle multiplicative scale changes.
  22 It cannot convert Centigrade to Fahrenheit, for example.
  23 .Pp
  24 The following options and arguments are supported:
  25 .Bl -tag -width "-fXfilenameX" -offset indent
  26 .It Fl f Ar filename
  27 Specifies the name of the units data file to load.
  28 .It Fl l No or Fl L
  29 List all unit definitions to the standard output,
  30 instead of performing any conversions.
  31 The result may include error messages and comments, beginning with
  32 .Ql \&/ .
  33 .Pp
  34 With the
  35 .Fl l
  36 option, unit definitions will be listed in a format
  37 almost identical to the the units data file that was loaded,
  38 except that comments will be removed, spacing may be changed,
  39 and lines may be re-ordered.
  40 .Pp
  41 With the
  42 .Fl L
  43 option, all unit definitions will be reduced to a form that
  44 depends on only a few primitive units (such as
  45 .Sy m , kg , sec ) .
  46 .It Fl q
  47 Suppresses prompting of the user for units and the display of statistics
  48 about the number of units loaded.
  49 .It Fl v
  50 Prints the version number.
  51 .It Oo Ar count Oc Ar from-unit Ar to-unit
  52 Allows a single unit conversion to be done directly from the command
  53 line.
  54 No prompting will occur.
  55 .Nm
  56 will print out only the result of this single conversion.
  57 Specifying
  58 .Ar count
  59 and
  60 .Ar from-unit
  61 as two separate arguments is equivalent to embedding both parts
  62 inside a single
  63 .Ar from-unit
  64 argument, with the parts separated by a space.
  65 .El
  66 .Pp
  67 .Nm
  68 works interactively by prompting the user for input:
  69 .Bd -literal
  70     You have: meters
  71     You want: feet
  72             * 3.2808399
  73             / 0.3048
  74
  75     You have: cm^3
  76     You want: gallons
  77             * 0.00026417205
  78             / 3785.4118
  79 .Ed
  80 .Pp
  81 Powers of units can be specified using the
  82 .Dq \&^
  83 character as shown in the example, or by simple concatenation:
  84 .Dq cm3
  85 is equivalent to
  86 .Dq cm^3 .
  87 Multiplication of units can be specified by using spaces, a dash or
  88 an asterisk.
  89 Division of units is indicated by the slash
  90 .Pq Sq \&/ .
  91 Note that multiplication has a higher precedence than division,
  92 so
  93 .Dq m/s/s
  94 is the same as
  95 .Dq m/s^2
  96 or
  97 .Dq "m/s s" .
  98 If the user enters incompatible unit types, the
  99 .Nm
 100 program will print a message indicating that the units are not
 101 conformable and it will display the reduced form for each unit:
 102 .Bd -literal
 103     You have: ergs/hour
 104     You want: fathoms kg^2 / day
 105     conformability error
 106             2.7777778e-11 kg m^2 / sec^3
 107             2.1166667e-05 kg^2 m / sec
 108 .Ed
 109 .Pp
 110 The conversion information is read from a units data file.
 111 The default
 112 file includes definitions for most familiar units, abbreviations and
 113 metric prefixes.
 114 Some constants of nature included are:
 115 .Bl -tag -width mercury -compact -offset indent
 116 .It pi
 117 ratio of circumference to diameter
 118 .It c
 119 speed of light
 120 .It e
 121 charge on an electron
 122 .It g
 123 acceleration of gravity
 124 .It force
 125 same as g
 126 .It mole
 127 Avogadro's number
 128 .It water
 129 pressure per unit height of water
 130 .It mercury
 131 pressure per unit height of mercury
 132 .It au
 133 astronomical unit
 134 .El
 135 .Pp
 136 .Dq pound
 137 is a unit of mass.
 138 Compound names are run together
 139 so
 140 .Dq poundforce
 141 is a unit of force.
 142 British units that differ from their
 143 US counterparts are prefixed with
 144 .Dq br ,
 145 and currency is prefixed with
 146 its country name:
 147 .Dq belgiumfranc ,
 148 .Dq britainpound .
 149 When searching for
 150 a unit, if the specified string does not appear exactly as a unit
 151 name, then the
 152 .Nm
 153 program will try to remove a trailing
 154 .Dq s
 155 or a trailing
 156 .Dq es
 157 and check again for a match.
 158 .Pp
 159 All of these definitions can be read in the standard units file, or you
 160 can supply your own file.
 161 A unit is specified on a single line by
 162 giving its name and an equivalence.
 163 One should be careful to define
 164 new units in terms of old ones so that a reduction leads to the
 165 primitive units which are marked with
 166 .Sq \&!
 167 characters.
 168 .Nm
 169 will not detect infinite loops that could be caused
 170 by careless unit definitions.
 171 .Pp
 172 Prefixes are defined in the same way as standard units, but with
 173 a trailing dash at the end of the prefix name.
 174 .Sh FILES
 175 .Bl -tag -width /usr/share/misc/units.lib -compact
 176 .It Pa /usr/share/misc/units.lib
 177 the standard units library
 178 .El
 179 .Sh AUTHORS
 180 .An Adrian Mariano Aq Mt adrian@cam.cornell.edu
 181 or
 182 .Aq mariano@geom.umn.edu
 183 .Sh CAVEATS
 184 While
 185 .Nm
 186 can be used as a calculator for many unit-related computations,
 187 caution is required: many computations require additional constant
 188 factors deriving from the physics (or chemistry or whatever) of the
 189 situation.
 190 As these factors are dimensionless,
 191 .Nm
 192 cannot itself either provide them or warn the user when they have been
 193 forgotten.
 194 For example, one joule is one kilogram meter squared per second
 195 squared, by definition; however, the kinetic energy of a one-kilogram
 196 object moving at one meter per second is half a joule, not one joule,
 197 because of a dimensionless factor that arises from integration.
 198 .Pp
 199 Also, some pairs of units that have the same dimensionality are
 200 nonetheless used to measure different things and attempting to convert
 201 between them may require additional fudge factors or be entirely
 202 meaningless.
 203 For example, torque and energy have the same dimensionality, but
 204 attempting to convert torque in newton-meters to energy in joules is
 205 nonsensical.
 206 There is no practical way for
 207 .Nm
 208 to warn about these issues either.
 209 .Sh BUGS
 210 The effect of including a
 211 .Sq \&/
 212 in a prefix is surprising.
 213 .Pp
 214 Exponents entered by the user can be only one digit.
 215 You can work around this by multiplying several terms.
 216 .Pp
 217 The user must use
 218 .Sq \&|
 219 to indicate division of numbers and
 220 .Sq \&/
 221 to indicate division of symbols.
 222 This distinction should not be necessary.
 223 .Pp
 224 The program contains various arbitrary limits on the length
 225 of the units converted and on the length of the data file.
 226 .Pp
 227 The program should use a hash table to store units so that
 228 it doesn't take so long to load the units list and check
 229 for duplication.