Seth Woolley's Man Viewer

Manual for units - man 1 units

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

UNITS(1)                                                              UNITS(1)

       units(1,7) - unit conversion program

       The  `units(1,7)' program converts quantities expressed in(1,8) various scales to
       their equivalents in(1,8) other scales.  The `units(1,7)' program can handle mul-
       tiplicative  scale  changes  as  well  as nonlinear conversions such as
       Fahrenheit to Celsius.

       The units(1,7) are defined in(1,8) an external data file.  You can use the exten-
       sive  data  file(1,n)  that comes with this program, or you can provide your
       own data file(1,n) to suit your needs.

       You can use the program interactively with prompts, or you can  use  it
       from the command line.

       To invoke units(1,7) for interactive use, type `units(1,7)' at your shell prompt.
       The program will print something like this:

           2131 units(1,7), 53 prefixes, 24 nonlinear units(1,7)

           You have:

       At the `You have:' prompt, type the quantity and  units(1,7)  that  you  are
       converting  from.   For  example,  if(3,n) you want to convert ten meters to
       feet, type `10 meters'.  Next, `units(1,7)' will  print  `You  want:'.   You
       should  type  the  type of units(1,7) you want to convert to.  To convert to
       feet, you would type `feet'.

       The answer will be displayed in(1,8) two ways.  The first  line  of  output,
       which is marked with a `*' to indicate multiplication, gives the result
       of the conversion you have asked for.  The second line of output, which
       is  marked  with  a  `/' to indicate division, gives the inverse of the
       conversion factor.  If you convert 10  meters  to  feet,  `units(1,7)'  will

               * 32.808399
               / 0.03048

       which tells you that 10 meters equals about 32.8 feet.  The second num-
       ber gives the conversion in(1,8) the opposite direction.  In this  case,  it
       tells  you  that  1  foot  is  equal to about 0.03 dekameters since the
       dekameter is 10 meters.  It also tells you that 1/32.8 is about .03.

       The `units(1,7)' program prints the inverse because sometimes it is  a  more
       convenient  number.   In  the  example  above, for example, the inverse
       value is an exact conversion: a foot is exactly .03048 dekameters.  But
       the number given the other direction is inexact.

       If you try to convert grains to pounds, you will see the following:

           You have: grains
           You want: pounds
                   * 0.00014285714
                   / 7000

       From the second line of the output you can immediately see that a grain
       is equal to a seven thousandth of a pound.  This is not so obvious from
       the  first line of the output.  If you find  the output format  confus-
       ing, try using the `--verbose' option:

           You have: grain
           You want: aeginamina
                   grain = 0.00010416667 aeginamina
                   grain = (1 / 9600) aeginamina

       If you request a conversion  between  units(1,7)  which  measure  reciprocal
       dimensions,  then  `units(1,7)'  will display the conversion results with an
       extra note indicating that reciprocal conversion has been done:

           You have: 6 ohms
           You want: siemens
                   reciprocal conversion
                   * 0.16666667
                   / 6

       Reciprocal conversion can be suppressed by using the `--strict' option.
       As usual, use the `--verbose' option to get more comprehensible output:

           You have: tex
           You want: typp
                   reciprocal conversion
                   1 / tex = 496.05465 typp
                   1 / tex = (1 / 0.0020159069) typp

           You have: 20 mph
           You want: sec/mile
                   reciprocal conversion
                   1 / 20 mph = 180 sec/mile
                   1 / 20 mph = (1 / 0.0055555556) sec/mile

       If you enter incompatible unit types, the `units(1,7)' program will print  a
       message  indicating that the units(1,7) are not conformable and it will dis-
       play the reduced form for each unit:

           You have: ergs/hour
           You want: fathoms kg^2 / day
           conformability error(8,n)
                   2.7777778e-11 kg m^2 / sec^3
                   2.1166667e-05 kg^2 m / sec

       If you only want to find the reduced form or definition of a unit, sim-
       ply press return at the `You want:' prompt.  Here is an example:

           You have: jansky
           You want:
                   Definition: fluxunit = 1e-26 W/m^2 Hz = 1e-26 kg / s^2

       The  output  from  `units(1,7)'  indicates  that the jansky is defined to be
       equal to a fluxunit which in(1,8) turn is defined to be a  certain  combina-
       tion  of watts, meters, and hertz.  The fully reduced (and in(1,8) this case
       somewhat more cryptic) form appears on the far right.

       If you want a list of options you can  type  `?'  at  the  `You  want:'
       prompt.   The program will display a list of named(5,8) units(1,7) which are con-
       formable with the unit that you  entered  at  the  `You  have:'  prompt
       above.  Note that conformable unit combinations will not appear on this

       Typing `help' at either prompt displays a short help message.  You  can
       also  type `help' followed by a unit name.  This will invoke a pager on
       the units(1,7) data base at the point where that unit is defined.   You  can
       read(2,n,1 builtins) the definition and comments that may give more details or histori-
       cal information about the unit.

       The `units(1,7)' program can  perform  units(1,7)  conversions  non-interactively
       from the command line.  To do this, type the command, type the original
       units(1,7) expression, and type the new units(1,7) you want.  You  will  probably
       need  to protect the units(1,7) expressions from interpretation by the shell
       using single quote characters.

       If you type

           units(1,7) '2 liters' 'quarts'

       then `units(1,7)' will print

               * 2.1133764
               / 0.47317647

       and then exit.  The output tells you that 2 liters is about 2.1 quarts,
       or alternatively that a quart is about 0.47 times 2 liters.

       If  the  conversion is successful, then `units(1,7)' will return success (0)
       to the calling environment.  If `units(1,7)' is given non-conformable  units(1,7)
       to  convert,  it  will  print a message giving the reduced form of each
       unit and it will return failure (nonzero) to the calling environment.

       When `units(1,7)' is invoked with only one argument, it will print  out  the
       definition  of  the specified unit.  It will return failure if(3,n) the unit
       is not defined and success if(3,n) the unit is defined.

       In order to enter more complicated units(1,7) or fractions, you will need to
       use  operations such as powers, products and division.  Powers of units(1,7)
       can be specified using the `^' character  as  shown  in(1,8)  the  following
       example, or by simple concatenation: `cm3' is equivalent to `cm^3'.  If
       the exponent is more than one digit, the `^' is required.  An  exponent
       like `2^3^2' is evaluated right to left.  The `^' operator has the sec-
       ond highest precedence.

           You have: cm^3
           You want: gallons
                   * 0.00026417205
                   / 3785.4118

           You have: arabicfoot-arabictradepound-force
           You want: ft lbf
                   * 0.7296
                   / 1.370614

       Multiplication of units(1,7) can be specified  by  using  spaces,  a  hyphen
       (`-')  or  an  asterisk  (`*').   Division of units(1,7) is indicated by the
       slash (`/') or by `per'.

           You have: furlongs per fortnight
           You want: m/s
                   * 0.00016630986
                   / 6012.8727

       Multiplication has a higher precedence than division and  is  evaluated
       left  to right, so `m/s * s/day' is equivalent to `m / s s day' and has
       dimensions of length per time(1,2,n) cubed.  Similarly, `1/2 meter' refers  to
       a  unit  of reciprocal length equivalent to .5/meter, which is probably
       not what you would intend if(3,n) you  entered  that  expression.   You  can
       indicate division of numbers with the vertical dash (`|').  This opera-
       tor has the highest precedence so the square root of two  thirds  could
       be written `2|3^1|2'.

           You have: 1|2 inch
           You want: cm
                   * 1.27
                   / 0.78740157

       Parentheses can be used for grouping as desired.

           You have: (1/2) kg / (kg/meter)
           You want: league
                   * 0.00010356166
                   / 9656.0833

       Prefixes  are defined separately from base units.  In order to get cen-
       timeters, the units(1,7) database defines `centi-'  and  `c-'  as  prefixes.
       Prefixes  can  appear  alone  with no unit following them.  An exponent
       applies only to the immediately preceding unit and its prefix  so  that
       `cm^3' or `centimeter^3' refer to cubic centimeters but `centi-meter^3'
       refers to hundredths of cubic meters.  Only one prefix is permitted per
       unit, so `micromicrofarad' will fail, but `micro-microfarad' will work.

       For `units(1,7)', numbers are just another kind of unit.  They can appear as
       many  times  as  you  like  and in(1,8) any order in(1,8) a unit expression.  For
       example, to find the volume of a box which is 2 ft by 3 ft by 12 ft  in(1,8)
       steres, you could do the following:

           You have: 2 ft 3 ft 12 ft
           You want: stere
                   * 2.038813
                   / 0.49048148

           You have: $ 5 / yard
           You want: cents / inch
                   * 13.888889
                   / 0.072

       And  the  second example shows how the dollar sign in(1,8) the units(1,7) conver-
       sion can precede the five.  Be careful:  `units(1,7)'  will  interpret  `$5'
       with no space as equivalent to dollars^5.

       Outside  of  the SI system, it is often desirable to add values of dif-
       ferent units(1,7) together.  Sums of conformable units(1,7) are written with  the
       `+' character.

           You have: 2 hours + 23 minutes + 32 seconds
           You want: seconds
                   * 8612
                   / 0.00011611705

           You have: 12 ft + 3 in(1,8)
           You want: cm
                   * 373.38
                   / 0.0026782366

           You have: 2 btu + 450 ft-lbf
           You want: btu
                   * 2.5782804
                   / 0.38785542

       The  expressions  which  are  added  together  must reduce to identical
       expressions in(1,8) primitive units(1,7), or an error(8,n) message will be displayed:

           You have: 12 printerspoint + 4 heredium
           Illegal sum of non-conformable units(1,7)

       Because `-' is used for products, it cannot also be used to  form  dif-
       ferences  of  units.   If  a `-' appears after `(' or after `+' then it
       will act as a negation operator.  So you can compute 20  degrees  minus
       12 minutes by entering `20 degrees + -12 arcmin'.  The `+' character is
       sometimes used in(1,8) exponents like `3.43e+8'.  This leads to an ambiguity
       in(1,8)  an  expression  like  `3e+2  yC'.   The unit `e' is a small unit of
       charge, so this can be regarded as equivalent to  `(3e+2)  yC'  or  `(3
       e)+(2  yC)'.   This ambiguity is resolved by always interpreting `+' as
       part of an exponent if(3,n) possible.

       Several built in(1,8) functions are provided:  `sin',  `cos',  `tan',  `ln',
       `log', `log2', `exp', `acos', `atan' and `asin'.  The `sin', `cos', and
       `tan' functions require either a dimensionless argument or an  argument
       with dimensions of angle.

           You have: sin(30 degrees)
           You want:
                   Definition: 0.5

           You have: sin(pi/2)
           You want:
                   Definition: 1

           You have: sin(3 kg)
           Unit not dimensionless

       The  other  functions on the list require dimensionless arguments.  The
       inverse trigonometric functions return  arguments  with  dimensions  of

       If  you  wish  to take roots of units(1,7), you may use the `sqrt' or `cube-
       root' functions.  These functions require that the  argument  have  the
       appropriate  root.   Higher  roots can  be obtained by using fractional

           You have: sqrt(acre)
           You want: feet
                   * 208.71074
                   / 0.0047913202

           You have: (400 W/m^2 / stefanboltzmann)^(1/4)
           You have:
                   Definition: 289.80882 K

           You have: cuberoot(hectare)
           Unit not a root

       Nonlinear units(1,7) are represented using functional notation.   They  make
       possible  nonlinear unit conversions such temperature.  This is differ-
       ent from the linear units(1,7) that convert temperature  differences.   Note
       the difference below.  The absolute temperature conversions are handled
       by units(1,7) starting with `temp', and you must  use  functional  notation.
       The  temperature  differences  are done using units(1,7) starting with `deg'
       and they do not require functional notation.

           You have: tempF(45)
           You want: tempC

           You have: 45 degF
           You want: degC
                   * 25
                   / 0.04

       In this case, think of `tempF(x)' not as a function but as  a  notation
       which  indicates  that `x' should have units(1,7) of `tempF' attached to it.
       @xref{Nonlinear units(1,7)}.

       Some other examples of nonlinears units(1,7) are ring size and  wire  gauge.
       There  are  numerous  different  gauges  and ring sizes.  See the units(1,7)
       database for more details.  Note that wire gauges with multiple  zeroes
       are  signified using negative numbers where two zeroes is -1.  Alterna-
       tively, you can use the synonyms `g00', `g000',  and  so  on  that  are
       defined in(1,8) the units(1,7) database.

           You have: wiregauge(11)
           You want: inches
                   * 0.090742002
                   / 11.020255

           You have: brwiregauge(g00)
           You want: inches
                   * 0.348
                   / 2.8735632

           You have: 1 mm
           You want: wiregauge

       You invoke `units(1,7)' like this:

           units(1,7) OPTIONS [FROM-UNIT [TO-UNIT]]

       If  the  FROM-UNIT  and  TO-UNIT are omitted, then the program will use
       interactive prompts to determine which conversions to perform.  If both
       FROM-UNIT  and TO-UNIT are given, `units(1,7)' will print the result of that
       single conversion and then exit.  If only FROM-UNIT appears on the com-
       mand  line,  `units(1,7)' will display the definition of that unit and exit.
       Units specified on the command line will need to be quoted  to  protect
       them  from  shell  interpretation and to group them into two arguments.
       @xref{Command line use}.

       The following options allow you to read(2,n,1 builtins) in(1,8) an alternative  units(1,7)  file(1,n),
       check your units(1,7) file(1,n), or change the output format:

       -c, --check
              Check that all units(1,7) and prefixes defined in(1,8) the units(1,7) data file(1,n)
              reduce to primitive units.  Print a list of all units(1,7) that  can-
              not  be reduced.  Also display some other diagnostics about sus-
              picious definitions in(1,8) the units(1,7) data file.  Note that only def-
              initions active in(1,8) the current locale(3,5,7) are checked.

              Like  the  `-check'  option,  this option prints a list of units(1,7)
              that cannot be reduced.  But to help find unit  definitions that
              cause endless loops, it lists the units(1,7) as they are checked.  If
              `units(1,7)' hangs, then the last unit to be printed has a bad  defi-
              nition.  Note that only definitions active in(1,8) the current locale(3,5,7)
              are checked.

       -o format, --output-format format
              Use the specified format for numeric output.  Format is the same
              as  that  for  the  printf(1,3,1 builtins) function in(1,8) the ANSI C standard.  For
              example, if(3,n) you want more precision you might use `-o %.15g'.

       -f filename, --file filename
              Use filename as the units(1,7) data  file(1,n)  rather  than  the  default
              units(1,7) data file.  This option overrides the `UNITSFILE' environ-
              ment variable.

       -h, --help
              Print out a summary of the options for `units(1,7)'.

       -q, --quiet, --silent
              Suppress prompting of the user for units(1,7) and the display of sta-
              tistics about the number of units(1,7) loaded.

       -s, --strict
              Suppress conversion of units(1,7) to their reciprocal units.

       -v, --verbose
              Give  slightly  more verbose output when converting units.  When
              combined with the `-c' option this  gives  the  same  effect  as

       -V, --version
              Print  program version(1,3,5) number, tell whether the readline library
              has been included, and give the location of  the  default  units(1,7)
              data file.

       The  conversion  information  is  read(2,n,1 builtins)  from a units(1,7) data file(1,n) which is
       called `units.dat' and is probably located  in(1,8)  the  `/usr/local/share'
       directory.   If  you invoke `units(1,7)' with the `-V' option, it will print
       the location of this file.  The default file(1,n) includes  definitions  for
       all  familiar  units(1,7),  abbreviations  and  metric  prefixes.   It  also
       includes many obscure or archaic units.

       Many constants of nature are defined, including these:

           pi        ratio of circumference to diameter
           c         speed of light
           e         charge on an electron
           force     acceleration of gravity
           mole      Avogadro's number
           water     pressure per unit height of water
           Hg        pressure per unit height of mercury
           au        astronomical unit
           k         Boltzman's constant
           mu0       permeability of vacuum
           epsilon0  permitivity of vacuum
           G         gravitational constant
           mach      speed of sound

       The database includes atomic masses for all of the elements and  numer-
       ous other constants.  Also included are the densities of various ingre-
       dients used in(1,8) baking so that `2 cups flour_sifted' can be converted to
       `grams'.   This is not an exhaustive list.  Consult the units(1,7) data file(1,n)
       to see the complete list, or to see the definitions that are used.

       The unit `pound' is a unit of mass.  To  get  force,  multiply  by  the
       force  conversion  unit `force' or use the shorthand `lbf'.  (Note that
       `g' is already taken as the standard abbreviation for the  gram.)   The
       unit  `ounce'  is also a unit of mass.  The fluid ounce is `fluidounce'
       or `floz'.  British capacity units(1,7) that differ from their  US  counter-
       parts,  such  as  the  British Imperial gallon, are prefixed with `br'.
       Currency is prefixed with its country name:  `belgiumfranc',  `britain-

       The  US  Survey  foot, yard, and mile can be obtained by using the `US'
       prefix.  These units(1,7) differ  slightly  from  the  international  length
       units.   They  were  in(1,8)  general use until 1959, and are still used for
       geographic surveys.  The acre is officially defined in(1,8) terms of the  US
       Survey  foot.   If  you  want an acre defined according to the interna-
       tional foot, use `intacre'.  The  difference  between  these  units(1,7)  is
       about  4 parts per million.  The British also used a slightly different
       length measure before 1959.  These can  be  obtained  with  the  prefix

       When  searching  for  a  unit,  if(3,n) the specified string(3,n) does not appear
       exactly as a unit name, then the `units(1,7)' program will try to  remove  a
       trailing `s' or a trailing `es'.  If that fails, `units(1,7)' will check for
       a prefix.  All of the standard metric prefixes are defined.

       To find out what units(1,7) and prefixes are available,  read(2,n,1 builtins)  the  standard
       units(1,7) data file.

       All  of  the units(1,7) and prefixes that `units(1,7)' can convert are defined in(1,8)
       the units(1,7) data file.  If you want to add your own units(1,7), you can supply
       your own file.

       A  unit is specified on a single line by giving its name and an equiva-
       lence.  Comments start with a `#' character, which can appear  anywhere
       in(1,8) a line.  The backslash character (`) acts as a continuation charac-
       ter if(3,n) it appears as the last character on a line, making  it  possible
       to spread definitions out over several lines if(3,n) desired.

       Unit  names  must  not contain any of the operator characters `+', `-',
       `*', `/', `|', `^' or the parentheses.  They cannot begin with a  digit
       or  a  decimal  point  (`.'), nor can they end with a digit (except for
       zero).  Be careful to define new units(1,7) in(1,8) terms of old ones so  that  a
       reduction leads to the primitive units(1,7), which are marked with `!' char-
       acters.  When adding new units(1,7), be sure to use the `-c' option to check
       that the new units(1,7) reduce properly.  If you define any units(1,7) which con-
       tain `+' characters, carefully check them because the `-c' option  will
       not catch non-conformable sums.  If you create a loop in(1,8) the units(1,7) def-
       initions, then `units(1,7)' will hang when invoked with  the  `-c'  options.
       You will need to use the `--check-verbose' option which prints out each
       unit as it checks them.  The program will still hang, but the last unit
       printed will be the unit which caused the infinite loop.

       Here is an example of a short units(1,7) file(1,n) that defines some basic units:

         m        !         # The meter is a primitive unit
         sec      !         # The second is a primitive unit
         micro-   1e-6      # Define a prefix
         minute   60 sec    # A minute is 60 seconds
         hour     60 min    # An hour is 60 minutes
         inch     0.0254 m  # Inch defined in(1,8) terms of meters
         ft       12 inches # The foot defined in(1,8) terms of inches
         mile     5280 ft   # And the mile

       A unit which ends with a `-' character is a prefix.  If a prefix  defi-
       nition  contains  any  `/'  characters,  be  sure they are protected by
       parentheses.  If you define  `half-  1/2'  then  `halfmeter'  would  be
       equivalent to `1 / 2 meter'.

       Some units(1,7) conversions of interest are nonlinear; for example, tempera-
       ture conversions between the Fahrenheit and Celsius  scales  cannot  be
       done by simply multiplying by conversions factors.

       When  you  give a linear unit definition such as `inch 2.54 cm' you are
       providing information that `units(1,7)' uses to  convert  values  in(1,8)  inches
       into  primitive units(1,7) of meters.  For nonlinear units(1,7), you give a func-
       tional definition that provides the same information.

       Nonlinear units(1,7) are represented using a  functional  notation.   It  is
       best  to  regard  this  notation not as a function call but as a way of
       adding units(1,7) to a number, much the same way that writing a linear  unit
       name  after  a number adds units(1,7) to that number.  Internally, nonlinear
       units(1,7) are defined by a pair of functions which convert to and from lin-
       ear units(1,7) in(1,8) the data file(1,n), so that an eventual conversion to primitive
       units(1,7) is possible.

       Here is an example nonlinear unit definition:

       tempF(x) [1;K] (x+(-32)) degF + stdtemp ; (tempF+(-stdtemp))/degF + 32

       A nonlinear unit definition comprises a unit name,  a  dummy  parameter
       name,  two  functions, and two corresponding units.  The functions tell
       `units(1,7)' how to convert to and from the new unit.  In order  to  produce
       valid  results,  the arguments of these functions need to have the cor-
       rect dimensions.  To facilitate error(8,n) checking,  you  may  specify  the

       The  definition begins with the unit name followed immediately (with no
       spaces) by a `(' character.  In parentheses is the name of the  parame-
       ter.   Next  is  an optional specification of the units(1,7) required by the
       functions in(1,8) this definition.  In the example above, the `tempF'  func-
       tion  requires an input argument conformable with `1'.  For normal non-
       linear units(1,7) definitions the forward function will always take a dimen-
       sionless  argument.   The  inverse  function requires an input argument
       conformable with `K'.  In general the inverse function will need  units(1,7)
       that match the quantity measured by your nonlinear unit.  The sole pur-
       pose of the expression in(1,8) brackets to enable `units(1,7)' to  perform  error(8,n)
       checking on function arguments.

       Next  the  function  definitions  appear.   In  the  example above, the
       `tempF' function is defined by

           tempF(x) = (x+(-32)) degF + stdtemp

       This gives a rule for converting `x' in(1,8) the  units(1,7)  `tempF'  to  linear
       units(1,7)  of absolute temperature, which makes it possible to convert from
       tempF to other units.

       In order to make conversions to Fahrenheit possible, you  must  give  a
       rule  for  the  inverse conversions. The inverse will be `x(tempF)' and
       its definition appears after a `;'  character.   In  our  example,  the
       inverse is

           x(tempF) = (tempF+(-stdtemp))/degF + 32

       This  inverse  definition takes an absolute temperature as its argument
       and converts it to the Fahrenheit  temperature.   The  inverse  can  be
       omitted  by  leaving out the `;' character, but then conversions to the
       unit will be impossible.  If the inverse is omitted then the  `--check'
       option  will display a warning.  It is up to you to calculate and enter
       the  correct  inverse  function  to  obtain  proper  conversions.   The
       `--check'  option  tests the inverse at one point and print an error(8,n) if(3,n)
       it is not valid there, but this is not a guarantee that your inverse is

       If  you  wish  to  make synonyms for nonlinear units(1,7), you still need to
       define both the forward and inverse functions.  Inverse  functions  can
       be obtained using the `~' operator.  So to create a synonym for `tempF'
       you could write(1,2)

           fahrenheit(x) [1;K] tempF(x); ~tempF(fahrenheit)

       You may occasionally wish to define a function that operates on  units.
       This  can  be done using a nonlinear unit definition.  For example, the
       definition below provides conversion between radius and the area  of  a
       circle.   Note that this definition requires a length as input and pro-
       duces an area as output, as indicated by the specification in(1,8) brackets.

           circlearea(r) [m;m^2] pi r^2 ; sqrt(circlearea/pi)

       Sometimes you may be interested in(1,8) a piecewise linear unit such as many
       wire gauges.  Piecewise linear units(1,7) can be defined by specifying  con-
       versions  to  linear  units(1,7)  on  a list of points.  Conversion at other
       points will be done by linear interpolation.  A partial  definition  of
       zinc gauge is

           zincgauge[in(1,8)] 1 0.002, 10 0.02, 15 0.04, 19 0.06, 23 0.1

       In  this example, `zincgauge' is the name of the piecewise linear unit.
       The definition of such a unit is indicated by the embedded `['  charac-
       ter.   After  the bracket, you should indicate the units(1,7) to be attached
       to the numbers in(1,8) the table.  No spaces can appear before the `]' char-
       acter,  so a definition like `foo[kg meters]' is illegal; instead write(1,2)
       `foo[kg*meters]'.  The definition of the unit consists  of  a  list  of
       pairs optionally separated by commas.  This list defines a function for
       converting from the piecewise linear unit to linear units.   The  first
       item  in(1,8)  each  pair  is  the function argument; the second item is the
       value of the function at that  argument  (in(1,8)  the  units(1,7)  specified  in(1,8)
       brackets).  In this example, we define `zincgauge' at five points.  For
       example, we set(7,n,1 builtins) `zincgauge(1)' equal to `0.002 in(1,8)'.   Definitions  like
       this  may  be  more readable  if(3,n) written using  continuation characters

            zincgauge[in(1,8)] \
               1  0.002 \
               10 0.02 \
               15 0.04 \
               19 0.06 \
               23 0.1

       With the preceeding definition, the following conversion  can  be  per-

           You have: zincgauge(10)
           You want: in(1,8)
               * 0.02
               / 50
           You have: .01 inch
           You want: zincgauge

       If  you  define a piecewise linear unit that is not strictly monotonic,
       then the inverse will not be well defined.  If the inverse is requested
       for  such  a  unit,  `units(1,7)'  will  return  the  smallest inverse.  The
       `--check' option will print a warning if(3,n) a non-monotonic piecewise lin-
       ear unit is encountered.

       Some units(1,7) have different values in(1,8) different locations.  The localiza-
       tion feature accomodates this by allowing the units(1,7) database to specify
       region  dependent  definitions.   A locale(3,5,7) region in(1,8) the units(1,7) database
       begins with `!locale(3,5,7)' followed by the name of the locale.  The  leading
       `!'  must appear in(1,8) the first column of the units(1,7) database.  The locale(3,5,7)
       region is terminated by `!endlocale'.  The following example shows  how
       to define a couple units(1,7) in(1,8) a locale.

       !locale(3,5,7) en_GB
       ton                     brton
       gallon                  brgallon

       The  current  locale(3,5,7) is specified by the `LOCALE' environment variable.
       Note that the `-c' option only checks the definitions which are  active
       for the current locale.

       The `units(1,7)' programs uses the following environment variables.

       LOCALE Specifies  the locale.  The default is `en_US'.  Sections of the
              units(1,7) database are specific to certain locales.

       PAGER  Specifies the pager to use for help and for displaying the  con-
              formable  units.   The  help function browses the units(1,7) database
              and calls the pager using the `+nn' syntax for specifying a line
              number.   The  default  pager is `more', but `less(1,3)', `emacs', or
              `vi' are possible alternatives.

              Specifies the  units(1,7)  database  file(1,n)  to  use  (instead  of  the
              default). This will be overridden by the `-f' option.

       If  the  `readline'  package has been compiled in(1,8), then when `units(1,7)' is
       used interactively, numerous command line editing features  are  avail-
       able.   To  check  if(3,n)  your  version(1,3,5)  of `units(1,7)' includes the readline,
       invoke the program with the `--version' option.

       For complete information about readline, consult the documentation  for
       the  readline  package.   Without any configuration, `units(1,7)' will allow
       editing in(1,8) the style of emacs.  Of particular use with `units(1,7)' are  the
       completion commands.

       If you type a few characters and then hit `ESC' followed by the `?' key
       then `units(1,7)' will display a list of all the units(1,7) which start with  the
       characters  typed.   For  example,  if(3,n) you type `metr' and then request
       completion, you will see something like this:

       You have: metr
       metre             metriccup         metrichorsepower  metrictenth
       metretes          metricfifth       metricounce       metricton
       metriccarat       metricgrain       metricquart       metricyarncount
       You have: metr

       If there is a unique way to complete a unitname, you can  hit  the  tab
       key  and  `units(1,7)'  will  provide the rest of the unit name.  If `units(1,7)'
       beeps, it means that there is no unique completion.  Pressing  the  tab
       key a second time(1,2,n) will print the list of all completions.

       /usr/share/units.dat - the standard units(1,7) data file(1,n)

       Adrian Mariano (

                                  30 Jan 2001                         UNITS(1)

References for this manual (incoming links)