usr.bin/units/units.1

   1 .\"     $NetBSD: units.1,v 1.12 2002/09/30 11:09:15 grant Exp $
   2 .Dd December 18, 2001
   3 .Dt UNITS 1
   4 .Os
   5 .Sh NAME
   6 .Nm units
   7 .Nd conversion program
   8 .Sh SYNOPSIS
   9 .Nm
  10 .Op Fl f Ar filename
  11 .Op Fl qv
  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 are supported:
  25 .Bl -tag -width "from-unit to-unit" -offset indent
  26 .It Fl f Ar filename
  27 Specifies the name of the units data file to load.
  28 .It Fl q
  29 Suppresses prompting of the user for units and the display of statistics
  30 about the number of units loaded.
  31 .It Fl v
  32 Prints the version number.
  33 .It Ar from-unit Ar to-unit
  34 Allows a single unit conversion to be done directly from the command
  35 line.
  36 No prompting will occur.
  37 .Nm
  38 will print out only the result of this single conversion.
  39 The
  40 .Ar count
  41 argument can be prepended to the
  42 .Ar from-unit
  43 or it can be separate.
  44 .El
  45 .Pp
  46 .Nm
  47 works interactively by prompting the user for input:
  48 .Bd -literal
  49     You have: meters
  50     You want: feet
  51             * 3.2808399
  52             / 0.3048
  53
  54     You have: cm^3
  55     You want: gallons
  56             * 0.00026417205
  57             / 3785.4118
  58 .Ed
  59 .Pp
  60 Powers of units can be specified using the
  61 .Dq \&^
  62 character as shown in the example, or by simple concatenation:
  63 .Dq cm3
  64 is equivalent to
  65 .Dq cm^3 .
  66 Multiplication of units can be specified by using spaces, a dash or
  67 an asterisk.
  68 Division of units is indicated by the slash
  69 .Pq Sq \&/ .
  70 Note that multiplication has a higher precedence than division,
  71 so
  72 .Dq m/s/s
  73 is the same as
  74 .Dq m/s^2
  75 or
  76 .Dq "m/s s" .
  77 If the user enters incompatible unit types, the
  78 .Nm
  79 program will print a message indicating that the units are not
  80 conformable and it will display the reduced form for each unit:
  81 .Bd -literal
  82     You have: ergs/hour
  83     You want: fathoms kg^2 / day
  84     conformability error
  85             2.7777778e-11 kg m^2 / sec^3
  86             2.1166667e-05 kg^2 m / sec
  87 .Ed
  88 .Pp
  89 The conversion information is read from a units data file.
  90 The default
  91 file includes definitions for most familiar units, abbreviations and
  92 metric prefixes.
  93 Some constants of nature included are:
  94 .Bl -tag -width mercury -compact -offset indent
  95 .It pi
  96 ratio of circumference to diameter
  97 .It c
  98 speed of light
  99 .It e
 100 charge on an electron
 101 .It g
 102 acceleration of gravity
 103 .It force
 104 same as g
 105 .It mole
 106 Avogadro's number
 107 .It water
 108 pressure per unit height of water
 109 .It mercury
 110 pressure per unit height of mercury
 111 .It au
 112 astronomical unit
 113 .El
 114 .Pp
 115 .Dq pound
 116 is a unit of mass.
 117 Compound names are run together
 118 so
 119 .Dq poundforce
 120 is a unit of force.
 121 British units that differ from their
 122 US counterparts are prefixed with
 123 .Dq br ,
 124 and currency is prefixed with
 125 its country name:
 126 .Dq belgiumfranc ,
 127 .Dq britainpound .
 128 When searching for
 129 a unit, if the specified string does not appear exactly as a unit
 130 name, then the
 131 .Nm
 132 program will try to remove a trailing
 133 .Dq s
 134 or a trailing
 135 .Dq es
 136 and check again for a match.
 137 .Pp
 138 All of these definitions can be read in the standard units file, or you
 139 can supply your own file.
 140 A unit is specified on a single line by
 141 giving its name and an equivalence.
 142 One should be careful to define
 143 new units in terms of old ones so that a reduction leads to the
 144 primitive units which are marked with
 145 .Sq \&!
 146 characters.
 147 .Nm
 148 will not detect infinite loops that could be caused
 149 by careless unit definitions.
 150 .Pp
 151 Prefixes are defined in the same was as standard units, but with
 152 a trailing dash at the end of the prefix name.
 153 .Sh FILES
 154 .Bl -tag -width /usr/share/misc/units.lib -compact
 155 .It Pa /usr/share/misc/units.lib
 156 the standard units library
 157 .El
 158 .Sh AUTHORS
 159 .An Adrian Mariano Aq adrian@cam.cornell.edu
 160 or
 161 .Aq mariano@geom.umn.edu
 162 .Sh BUGS
 163 The effect of including a
 164 .Sq \&/
 165 in a prefix is surprising.
 166 .Pp
 167 Exponents entered by the user can be only one digit.
 168 You can work around this by multiplying several terms.
 169 .Pp
 170 The user must use
 171 .Sq \&|
 172 to indicate division of numbers and
 173 .Sq \&/
 174 to indicate division of symbols.
 175 This distinction should not be necessary.
 176 .Pp
 177 The program contains various arbitrary limits on the length
 178 of the units converted and on the length of the data file.
 179 .Pp
 180 The program should use a hash table to store units so that
 181 it doesn't take so long to load the units list and check
 182 for duplication.