|Check that all units and prefixes defined in the units data file reduce to primitive units. Print a list of all units that cannot be reduced. Also display some other diagnostics about suspicious definitions in the units data file. Only definitions active in the current locale are checked. You should always run units units with this option after modifying a units data file.|
|Like the --check --check option, this option prints a list of units that cannot be reduced. But to help find unit definitions that cause endless loops, it lists the units as they are checked. If units units hangs, then the last unit to be printed has a bad definition. Only definitions active in the current locale are checked.|
|-d ndigits, --digits ndigits|
|Set the number of significant digits in the output to the value specified (which must be greater than zero). For example, -d 12 -d 12 sets the number of significant digits to 12. With exponential output units units displays one digit to the left of the decimal point and eleven digits to the right of the decimal point. On most systems, the maximum number of internally meaningful digits is 15; if you specify a greater number than your systems maximum, units units will print a warning and set the number to the largest meaningful value. To directly set the maximum value, give an argument of max max (e.g., -d max). -d max). Be aware, of course, that significant here refers only to the display of numbers; if results depend on physical constants not known to this precision, the physically meaningful precision may be less than that shown. The --digits --digits option conflicts with the --output-format --output-format option.|
|Set the numeric output format to exponential (i.e., scientific notation), like that used in the Unix units units program. The default precision is eight significant digits (seven digits to the right of the decimal point); this can be changed with the --digits --digits option. The --exponential --exponential option conflicts with the --output-format --output-format option.|
|-o format, --output-format format|
|This option affords complete control over the numeric output format using the specified format. The format is a single floating point numeric format for the printf() printf() function in the C programming language. All compilers support the format types g g and G G to specify significant digits, e e and E E for scientific notation, and f f for fixed-point decimal. The ISO C99 standard introduced the F F type for fixed-point decimal and the a a and A A types for hexadecimal floating point; these types are allowed with compilers that support them. The default format is %.8g; %.8g; for greater precision, you could specify -o %.15g. -o %.15g. See Numeric Output Format and the documentation for printf() printf() for more detailed descriptions of the format specification. The --output-format --output-format option affords the greatest control of the output appearance, but requires at least rudimentary knowledge of the printf() printf() format syntax. If you dont want to bother with the printf() printf() syntax, you can specify greater precision more simply with the --digits --digits option or select exponential format with --exponential. --exponential. The --output-format --output-format option is incompatible with the --exponential --exponential and --digits --digits options.|
|-f filename, --file filename|
|Instruct units units to load the units file filename. You can specify up to 25 units files on the command line. When you use this option, units units will load only the files you list on the command line; it will not load the standard file or your personal units file unless you explicitly list them. If filename is the empty string (-f (-f the default units file (or that specified by UNITSFILE) UNITSFILE) will be loaded in addition to any others specified with -f. -f.|
|-L logfile, --log logfile|
|Save the results of calculations in the file logfile; this can be useful if it is important to have a record of unit conversions or other calculations that are to be used extensively or in a critical activity such as a program or design project. If logfile exits, the new results are appended to the file. See Logging Calculations for a more detailed description and some examples.|
|Print out a summary of the options for units. units.|
|Causes - - to be interpreted as a subtraction operator. This is the default behavior.|
|Causes - - to be interpreted as a multiplication operator when it has two operands. It will act as a negation operator when it has only one operand: (-3). (-3). By default - - is treated as a subtraction operator.|
|Causes * * to have the old-style precedence, higher than the precedence of division so that 1/2*3 1/2*3 will equal 1/6. 1/6.|
|Forces * * to have the new (default) precedence that follows the usual rules of algebra: the precedence of * * is the same as the precedence of /, /, so that 1/2*3 1/2*3 will equal 3/2. 3/2.|
|Give compact output featuring only the conversion factor. This turns off the --verbose --verbose option.|
|-q, --quiet, --silent|
|Suppress prompting of the user for units and the display of statistics about the number of units loaded.|
|Disable conversion to unit lists.|
|When converting to a combination of units given by a unit list, round the value of the last unit in the list to the nearest integer.|
|When converting to a combination of units specified in a list, always show a non-unity factor before a unit that begins with a fraction with a unity denominator. By default, if the unit in a list begins with fraction of the form 1|x and its multiplier is an integer other than 1, the fraction is given as the product of the multiplier and the numerator (e.g., 3|8 in 3|8 in rather than 3 * 1|8 in). 3 * 1|8 in). In some cases, this is not what is wanted; for example, the results for a cooking recipe might show 3 * 1|2 cup 3 * 1|2 cup as 3|2 cup. 3|2 cup. With the --show-factor --show-factor option, a result equivalent to 1.5 cups will display as 3 * 1|2 cup 3 * 1|2 cup rather than 3|2 cup. 3|2 cup. A user-specified fractional unit with a numerator other than 1 is never overridden, howeverif a unit list specifies 3|4 cup;1|2 cup, 3|4 cup;1|2 cup, a result equivalent to 1 1/2 cups will always be shown as 2 * 3|4 cup 2 * 3|4 cup whether or not the --show-factor --show-factor option is given.|
|Suppress conversion of units to their reciprocal units. For example, units units will normally convert hertz to seconds because these units are reciprocals of each other. The strict option requires that units be strictly conformable to perform a conversion, and will give an error if you attempt to convert hertz to seconds.|
|Give only one line of output (the forward conversion). Do not print the reverse conversion. If a reciprocal conversion is performed then units units will still print the reciprocal conversion line.|
|Give terse output when converting units. This option can be used when calling units units from another program so that the output is easy to parse. This option has the combined effect of these options: --strict --strict --quiet --quiet --one-line --one-line --compact. --compact. When combined with --version --version it produces a display showing only the program name and version number.|
|Give slightly more verbose output when converting units. When combined with the -c -c option this gives the same effect as --check-verbose. --check-verbose. When combined with --version --version produces a more detailed output, equivalent to the --info --info option.|
|Print the program version number, tell whether the readline readline library has been included, tell whether UTF-8 support has been included; give the locale, the location of the default units data file, and the location of the personal units data file; indicate if the personal units data file does not exist.|
|When given in combination with the --terse --terse option, the program prints only the version number and exits.|
|When given in combination with the --verbose --verbose option, the program, the --version --version option has the same effect as the --info --info option below.|
|Print the information given with the --version --version option, show the pathname of the units program, show the status of the UNITSFILE UNITSFILE and MYUNITSFILE MYUNITSFILE environment variables, and additional information about how units units locates the related files. On systems running Microsoft Windows, the status of the UNITSLOCALE UNITSLOCALE environment variable and information about the related locale map are also given. This option is usually of interest only to developers and administrators, but it can sometimes be useful for troubleshooting.|
|Combining the --version --version and --verbose --verbose options has the same effect as giving --info. --info.|
|Print the location of the default units data file and exit; if the file cannot be found, print Units data file not found.|
|-l locale, --locale locale|
|Print the information given with the --version --version option, show the Force a specified locale such as en_GB en_GB to get British definitions by default. This overrides the locale determined from system settings or environment variables. See Locale for a description of locale format.|
The units and prefixes that units units can convert are defined in the units data file, typically /usr/share/units/definitions.units. /usr/share/units/definitions.units. If you cant find this file, run units --version units --version to get information on the file locations for your installation. Although you can extend or modify this data file if you have appropriate user privileges, its usually better to put extensions in separate files so that the definitions will be preserved if you update units. units.
You can include additional data files in the units database using the !include !include command in the standard units data file. For example
might be appropriate for a site-wide supplemental data file. The location of the !include !include statement in the standard units data file is important; later definitions replace earlier ones, so any definitions in an included file will override definitions before the !include !include statement in the standard units data file. With normal invocation, no warning is given about redefinitions; to ensure that you dont have an unintended redefinition, run units -c units -c after making changes to any units data file.
If you want to add your own units in addition to or in place of standard or site-wide supplemental units data files, you can include them in the .units .units file in your home directory. If this file exists it is read after the standard units data file, so that any definitions in this file will replace definitions of the same units in the standard data file or in files included from the standard data file. This file will not be read if any units files are specified on the command line. (Under Windows the personal units file is named unitdef.units.) unitdef.units.) Running units -V units -V will display the location and name of your personal units file.
The units units program first tries to determine your home directory from the HOME HOME environment variable. On systems running Microsoft Windows, if HOME HOME does not exist, units units attempts to find your home directory from HOMEDRIVE, HOMEDRIVE, HOMEPATH HOMEPATH and USERPROFILE. USERPROFILE. You can specify an arbitrary file as your personal units data file with the MYUNITSFILE MYUNITSFILE environment variable; if this variable exists, its value is used without searching your home directory. The default units data files are described in more detail in Data Files.
A unit is specified on a single line by giving its name and an equivalence. Comments start with a # # character, which can appear anywhere in a line. The backslash character (\ (\ acts as a continuation character if it appears as the last character on a line, making it possible to spread definitions out over several lines if desired. A file can be included by giving the command !include !include followed by the files name. The ! ! must be the first character on the line. The file will be sought in the same directory as the parent file unless you give a full path. The name of the file to be included cannot contain the comment character #. #.
Unit names must not contain any of the operator characters +, +, -, -, *, *, /, /, |, |, ^, ^, ;, ;, ~, ~, the comment character #, #, or parentheses. They cannot begin or end with an underscore (_ (_ a comma (, (, or a decimal point (. (. The figure dash (U+2012), typographical minus (-; U+2212), and en dash (-; U+2013) are converted to the operator -, -, so none of these characters can appear in unit names. Names cannot begin with a digit, and if a name ends in a digit other than zero, the digit must be preceded by a string beginning with an underscore, and afterwards consisting only of digits, decimal points, or commas. For example, foo_2, foo_2, foo_2,1, foo_2,1, or foo_3.14 foo_3.14 are valid names but foo2 foo2 or foo_a2 foo_a2 are invalid. You could define nitrous oxide as
N2O nitrogen 2 + oxygen
but would need to define nitrogen dioxide as
NO_2 nitrogen + oxygen 2
Be careful to define new units in terms of old ones so that a reduction leads to the primitive units, which are marked with ! ! characters. Dimensionless units are indicated by using the string !dimensionless !dimensionless for the unit definition.
When adding new units, be sure to use the -c -c option to check that the new units reduce properly. If you create a loop in the units definitions, then units units will hang when invoked with the -c -c option. You will need to use the --check-verbose --check-verbose option, which prints out each unit as it is checked. The program will still hang, but the last unit printed will be the unit that caused the infinite loop.
If you define any units that contain + + characters, carefully check them because the -c -c option will not catch non-conformable sums. Be careful with the - - operator as well. When used as a binary operator, the - - character can perform addition or multiplication depending on the options used to invoke units. units. To ensure consistent behavior use - - only as a unary negation operator when writing units definitions. To multiply two units leave a space or use the * * operator with care, recalling that it has two possible precedence values and may require parentheses to ensure consistent behavior. To compute the difference of foo foo and bar bar write foo+(-bar) foo+(-bar) or even foo+-bar. foo+-bar.
Here is an example of a short data file that defines some basic units:
m ! # The meter is a primitive unit sec ! # The second is a primitive unit rad !dimensionless # A dimensionless 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 terms of meters ft 12 inches # The foot defined in terms of inches mile 5280 ft # And the mile
A unit that ends with a - - character is a prefix. If a prefix definition contains any / / characters, be sure they are protected by parentheses. If you define half- 1/2 half- 1/2 then halfmeter halfmeter would be equivalent to 1 / (2 meter). 1 / (2 meter).
Some unit conversions of interest are nonlinear; for example, temperature conversions between the Fahrenheit and Celsius scales cannot be done by simply multiplying by conversion factors.
When you give a linear unit definition such as inch 2.54 cm inch 2.54 cm you are providing information that units units uses to convert values in inches into primitive units of meters. For nonlinear units, you give a functional definition that provides the same information.
Nonlinear units 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 to a number, much the same way that writing a linear unit name after a number adds units to that number. Internally, nonlinear units are defined by a pair of functions that convert to and from linear units in the database, so that an eventual conversion to primitive units is possible.
Here is an example nonlinear unit definition:
tempF(x) units=[1;K] domain=[-459.67,) range=[0,) \ (x+(-32)) degF + stdtemp ; (tempF+(-stdtemp))/degF + 32
A nonlinear unit definition comprises a unit name, a formal parameter name, two functions, and optional specifications for units, the domain, and the range (the domain of the inverse function). The functions tell units units how to convert to and from the new unit. To produce valid results, the arguments of these functions need to have the correct dimensions and be within the domains for which the functions are defined.
The definition begins with the unit name followed immediately (with no spaces) by a ( ( character. In the parentheses is the name of the formal parameter. Next is an optional specification of the units required by the functions in the definition. In the example above, the units=[1;K] units=[1;K] specification indicates that the tempF tempF function requires an input argument conformable with 1 1 (i.e., the argument is dimensionless), and that the inverse function requires an input argument conformable with K. K. For normal nonlinear units definition, the forward function will always take a dimensionless argument; in general, the inverse function will need units that match the quantity measured by your nonlinear unit. Specifying the units enables units units to perform error checking on function arguments, and also to assign units to domain and range specifications, which are described later.
Next the function definitions appear. In the example above, the tempF tempF function is defined by
tempF(x) = (x+(-32)) degF + stdtemp
This gives a rule for converting x x in the units tempF tempF to linear units of absolute temperature, which makes it possible to convert from tempF to other units.
To enable conversions to Fahrenheit, you must give a rule for the inverse conversions. The inverse will be x(tempF) 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 and the inverse definition, but then conversions to the unit will not be possible. If the inverse definition is omitted, the --check --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 --check option tests the inverse at one point and prints an error if it is not valid there, but this is not a guarantee that your inverse is correct.
With some definitions, the units may vary. For example, the definition
can have any arbitrary units, and can also take dimensionless arguments. In such a case, you should not specify units. If a definition takes a root of its arguments, the definition is valid only for units that yield such a root. For example,
is valid for a dimensionless argument, and for arguments with even powers of units.
Some definitions may not be valid for all real numbers. In such cases, units units can handle errors better if you specify an appropriate domain and range. You specify the domain and range as shown below:
baume(d) units=[1;g/cm^3] domain=[0,130.5] range=[1,10] \ (145/(145-d)) g/cm^3 ; (baume+-g/cm^3) 145 / baume
In this example the domain is specified after domain= domain= with the endpoints given in brackets. In accord with mathematical convention, square brackets indicate a closed interval (one that includes its endpoints), and parentheses indicate an open interval (one that does not include its endpoints). An interval can be open or closed on one or both ends; an interval that is unbounded on either end is indicated by omitting the limit on that end. For example, a quantity to which decibel (dB) is applied may have any value greater than zero, so the range is indicated by (0,): (0,):
decibel(x) units=[1;1] range=(0,) 10^(x/10); 10 log(decibel)
If the domain or range is given, the second endpoint must be greater than the first.
The domain and range specifications can appear independently and in any order along with the units specification. The values for the domain and range endpoints are attached to the units given in the units specification, and if necessary, the parameter value is adjusted for comparison with the endpoints. For example, if a definition includes units=[1;ft] units=[1;ft] and range=[3,), range=[3,), the range will be taken as 3 ft to infinity. If the function is passed a parameter of 900 mm, 900 mm, that value will be adjusted to 2.9527559 ft, which is outside the specified range. If you omit the units specification from the previous example, units units can not tell whether you intend the lower endpoint to be 3 ft or 3 microfurlongs, and can not adjust the parameter value of 900 mm for comparison. Without units, numerical values other than zero or plus or minus infinity for domain or range endpoints are meaningless, and accordingly they are not allowed. If you give other values without units then the definition will be ignored and you will get an error message.
Although the units, domain, and range specifications are optional, its best to give them when they are applicable; doing so allows units units to perform better error checking and give more helpful error messages. Giving the domain and range also enables the --check --check option to find a point in the domain to use for its point check of your inverse definition.
You can make synonyms for nonlinear units by providing both the forward and inverse functions; inverse functions can be obtained using the ~ ~ operator. So to create a synonym for tempF tempF you could write
fahrenheit(x) units=[1;K] tempF(x); ~tempF(fahrenheit)
This is useful for creating a nonlinear unit definition that differs slightly from an existing definition without having to repeat the original functions. For example,
dBW(x) units=[1;W] range=[0,) dB(x) W ; ~dB(dBW/W)
If you wish a synonym to refer to an existing nonlinear unit without modification, you can do so more simply by adding the synonym with appended parentheses as a new unit, with the existing nonlinear unitwithout parenthesesas the definition. So to create a synonym for tempF tempF you could write
The definition must be a nonlinear unit; for example, the synonym
will result in an error message when units units starts.
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. This definition requires a length as input and produces an area as output, as indicated by the units= units= specification. Specifying the range as the nonnegative numbers can prevent cryptic error messages.
circlearea(r) units=[m;m^2] range=[0,) pi r^2 ; sqrt(circlearea/pi)
Sometimes you may be interested in a piecewise linear unit such as many wire gauges. Piecewise linear units can be defined by specifying conversions to linear units 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 0.002, 10 0.02, 15 0.04, 19 0.06, 23 0.1
In this example, zincgauge zincgauge is the name of the piecewise linear unit. The definition of such a unit is indicated by the embedded [ [ character. After the bracket, you should indicate the units to be attached to the numbers in the table. No spaces can appear before the ] ] character, so a definition like foo[kg meters] foo[kg meters] is invalid; instead write foo[kg*meters]. 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 each pair is the function argument; the second item is the value of the function at that argument (in the units specified in brackets). In this example, we define zincgauge zincgauge at five points. For example, we set zincgauge(1) zincgauge(1) equal to 0.002 in. 0.002 in. Definitions like this may be more readable if written using continuation characters as
zincgauge[in] \ 1 0.002 \ 10 0.02 \ 15 0.04 \ 19 0.06 \ 23 0.1
With the preceding definition, the following conversion can be performed:
You have: zincgauge(10) You want: in * 0.02 / 50 You have: .01 inch You want: zincgauge 5
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 units will return the smallest inverse.
After adding nonlinear units definitions, you should normally run units --check units --check to check for errors. If the units units keyword is not given, the --check --check option checks a nonlinear unit definition using a dimensionless argument, and then checks using an arbitrary combination of units, as well as the square and cube of that combination; a warning is given if any of these tests fail. For example,
Warning: function squirt(x) defined as sqrt(x) failed for some test inputs: squirt(7(kg K)^1): Unit not a root squirt(7(kg K)^3): Unit not a root
Running units --check units --check will print a warning if a non-monotonic piecewise linear unit is encountered. For example, the relationship between ANSI coated abrasive designation and mean particle size is non-monotonic in the vicinity of 800 grit:
ansicoated[micron] \ . . . 600 10.55 \ 800 11.5 \ 1000 9.5 \
Running units --check units --check would give the error message
Table ansicoated lacks unique inverse around entry 800
Although the inverse is not well defined in this region, its not really an error. Viewing such error messages can be tedious, and if there are enough of them, they can distract from true errors. Error checking for nonlinear unit definitions can be suppressed by giving the noerror noerror keyword; for the examples above, this could be done as
squirt(x) noerror domain=[0,) range=[0,) sqrt(x); squirt^2 ansicoated[micron] noerror \ . . .
Use the noerror noerror keyword with caution. The safest approach after adding a nonlinear unit definition is to run units --check units --check and confirm that there are no actual errors before adding the noerror noerror keyword.
Unit list aliases are treated differently from unit definitions, because they are a data entry shorthand rather than a true definition for a new unit. A unit list alias definition begins with !unitlist !unitlist and includes the alias and the definition; for example, the aliases included in the standard units data file are
!unitlist hms hr;min;sec !unitlist time year;day;hr;min;sec !unitlist dms deg;arcmin;arcsec !unitlist ftin ft;in;1|8 in !unitlist usvol cup;3|4 cup;2|3 cup;1|2 cup;1|3 cup;1|4 cup;\ tbsp;tsp;1|2 tsp;1|4 tsp;1|8 tsp
Unit list aliases are only for unit lists, so the definition must include a ;. ;. Unit list aliases can never be combined with units or other unit list aliases, so the definition of time time shown above could not have been shortened to year;day;hms. year;day;hms.
As usual, be sure to run units --check units --check to ensure that the units listed in unit list aliases are conformable.
By default, units units shows results to eight significant digits. You can change this with the --exponential, --exponential, --digits, --digits, and --output-format --output-format options. The first sets an exponential format (i.e., scientific notation) like that used in the original Unix units units program, the second allows you to specify a different number of significant digits, and the last allows you to control the output appearance using the format for the printf() printf() function in the C programming language. If you only want to change the number of significant digits or specify exponential format type, use the --digits --digits and --exponential --exponential options. The --output-format --output-format option affords the greatest control of the output appearance, but requires at least rudimentary knowledge of the printf() printf() format syntax. See Invoking Units for descriptions of these options.
The format specification recognized with the --output-format --output-format option is a subset of that for printf(). printf(). The format specification has the form %[flags][width][ %[flags][width][ .precision]type; .precision]type; it must begin with %, %, and must end with a floating-point type specifier: g g or G G to specify the number of significant digits, e e or E E for scientific notation, and f f for fixed-point decimal. The ISO C99 standard added the F F type for fixed-point decimal and the a a and A A types for hexadecimal floating point; these types are allowed with compilers that support them. Type length modifiers (e.g., L L to indicate a long double) are inapplicable and are not allowed.
The default format for units units is %.8g; %.8g; for greater precision, you could specify -o %.15g. -o %.15g. The g g and G G format types use exponential format whenever the exponent would be less than -4, so the value 0.000013 displays as 1.3e-005. 1.3e-005. These types also use exponential notation when the exponent is greater than or equal to the precision, so with the default format, the value 5times107 displays as 50000000 50000000 and the value 5times108 displays as 5e+008. 5e+008. If you prefer fixed-point display, you might specify -o %.8f; -o %.8f; however, small numbers will display very few significant digits, and values less than 0.5times10-8 will show nothing but zeros.
The format specification may include one or more optional flags: +, +, (space), #, #, -, -, or 0 0 (the digit zero). The digit-grouping flag is allowed with compilers that support it. Flags are followed by an optional value for the minimum field width, and an optional precision specification that begins with a period (e.g., .6). .6). The field width includes the digits, decimal point, the exponent, thousands separators (with the digit-grouping flag), and the sign if any of these are shown.
The + + flag causes the output to have a sign (+ (+ or -). -). The space flag is similar to the + + flag, except that when the value is positive, it is prefixed with a space rather than a plus sign; this flag is ignored if the + + flag is also given. The + + or flag could be useful if conversions might include positive and negative results, and you wanted to align the decimal points in exponential notation. The # # flag causes the output value to contain a decimal point in all cases; by default, the output contains a decimal point only if there are digits (which can be trailing zeros) to the right of the point. With the g g or G G types, the # # flag also prevents the suppression of trailing zeros. The digit-grouping flag shows a thousands separator in digits to the left of the decimal point. This can be useful when displaying large numbers in fixed-point decimal; for example, with the format %f, %f,
You have: mile You want: microfurlong * 8000000.000000 / 0.000000
the magnitude of the first result may not be immediately obvious without counting the digits to the left of the decimal point. If the thousands separator is the comma (, (, the output with the format %f %f might be
You have: mile You want: microfurlong * 8,000,000.000000 / 0.000000
making the magnitude readily apparent. Unfortunately, few compilers support the digit-grouping flag.
With the - - flag, the output value is left aligned within the specified field width. If a field width greater than needed to show the output value is specified, the 0 0 (zero) flag causes the output value to be left padded with zeros until the specified field width is reached; for example, with the format %011.6f, %011.6f,
You have: troypound You want: grain * 5760.000000 / 0000.000174
The 0 0 flag has no effect if the - - (left align) flag is given.
By default, the output value is left aligned and shown with the minimum width necessary for the specified (or default) precision. If a field width greater than this is specified, the value shown is right aligned, and padded on the left with enough spaces to provide the specified field width. A width specification is typically used with fixed-point decimal to have columns of numbers align at the decimal point; this arguably is less useful with units units than with long columnar output, but it may nonetheless assist in quickly assessing the relative magnitudes of results. For example, with the format %12.6f, %12.6f,
You have: km You want: in * 39370.078740 / 0.000025 You have: km You want: rod * 198.838782 / 0.005029 You have: km You want: furlong * 4.970970 / 0.201168
The meaning of precision depends on the format type. With g g or G, G, it specifies the number of significant digits (like the --digits --digits option); with e, e, E, E, f, f, or F, F, it specifies the maximum number of digits to be shown after the decimal point.
With the g g and G G format types, trailing zeros are suppressed, so the results may sometimes have fewer digits than the specified precision (as indicated above, the # # flag causes trailing zeros to be displayed).
The default precision is 6, so %g %g is equivalent to %.6g, %.6g, and would show the output to six significant digits. Similarly, %e %e or %f %f would show the output with six digits after the decimal point.
The C printf() printf() function allows a precision of arbitrary size, whether or not all of the digits are meaningful. With most compilers, the maximum internal precision with units units is 15 decimal digits (or 13 hexadecimal digits). With the --digits --digits option, you are limited to the maximum internal precision; with the --output-format --output-format option, you may specify a precision greater than this, but it may not be meaningful. In some cases, specifying excess precision can result in rounding artifacts. For example, a pound is exactly 7000 grains, but with the format %.18g, %.18g, the output might be
You have: pound You want: grain * 6999.9999999999991 / 0.00014285714285714287
With the format %.25g %.25g you might get the following:
You have: 1/3 You want: Definition: 0.333333333333333314829616256247
In this case the displayed value includes a series of digits that represent the underlying binary floating-point approximation to 1/3 but are not meaningful for the desired computation. In general, the result with excess precision is system dependent. The precision affects only the display of numbers; if a result relies on physical constants that are not known to the specified precision, the number of physically meaningful digits may be less than the number of digits shown.
See the documentation for printf() printf() for more detailed descriptions of the format specification.
The --output-format --output-format option is incompatible with the --exponential --exponential or --digits --digits options; if the former is given in combination with either of the latter, the format is controlled by the last option given.
Some units have different values in different locations. The localization feature accommodates this by allowing a units data file to specify definitions that depend on the users locale.
A locale is a subset of a users environment that indicates the users language and country, and some attendant preferences, such as the formatting of dates. The units units program attempts to determine the locale from the POSIX setlocale function; if this cannot be done, units units examines the environment variables LC_CTYPE LC_CTYPE and LANG. LANG. On POSIX systems, a locale is of the form language_ language_ where language is the two-character code from ISO 639-1 and country is the two-character code from ISO 3166-1; language is lower case and country is upper case. For example, the POSIX locale for the United Kingdom is en_GB. en_GB.
On systems running Microsoft Windows, the value returned by setlocale() is different from that on POSIX systems; units units attempts to map the Windows value to a POSIX value by means of a table in the file locale_map.txt locale_map.txt in the same directory as the other data files. The file includes entries for many combinations of language and country, and can be extended to include other combinations. The locale_map.txt locale_map.txt file comprises two tab-separated columns; each entry is of the form
where POSIX-locale is as described above, and Windows-locale typically spells out both the language and country. For example, the entry for the United States is
English_United States en_US
You can force units units to run in a desired locale by using the -l -l option.
In order to create unit definitions for a particular locale you begin a block of definitions in a unit datafile with !locale !locale followed by a locale name. The ! ! must be the first character on the line. The units units program reads the following definitions only if the current locale matches. You end the block of localized units with !endlocale. !endlocale. Here is an example, which defines the British gallon.
!locale en_GB gallon 4.54609 liter !endlocale
Sometimes the locale isnt sufficient to determine unit preferences. There could be regional preferences, or a company could have specific preferences. Though probably uncommon, such differences could arise with the choice of English customary units outside of English-speaking countries. To address this, units units allows specifying definitions that depend on environment variable settings. The environment variables can be controled based on the current locale, or the user can set them to force a particular group of definitions.
A conditional block of definitions in a units data file begins with either !var !var or !varnot !varnot following by an environment variable name and then a space separated list of values. The leading ! ! must appear in the first column of a units data file, and the conditional block is terminated by !endvar. !endvar. Definitions in blocks beginning with !var !var are executed only if the environment variable is exactly equal to one of the listed values. Definitions in blocks beginning with !varnot !varnot are executed only if the environment variable does not equal any of the list values.
The inch has long been a customary measure of length in many places. The word comes from the latin uncia meaning one twelfth, referring to its relationship with the foot. By the 20th century, the inch was officially defined in English-speaking countries relative to the yard, but until 1959, the yard differed slightly among those countries. In France the customary inch, which was displaced in 1799 by the meter, had a different length based on a french foot. These customary definitions could be accommodated as follows:
!var INCH_UNIT usa yard 3600|3937 m !endvar !var INCH_UNIT canada yard 0.9144 meter !endvar !var INCH_UNIT uk yard 0.91439841 meter !endvar !var INCH_UNIT canada uk usa foot 1|3 yard inch 1|12 foot !endvar !var INCH_UNIT france foot 144|443.296 m inch 1|12 foot line 1|12 inch !endvar !varnot INCH_UNIT usa uk france canada !message Unknown value for INCH_UNIT !endvar
When units units reads the above definitions it will check the environment variable INCH_UNIT INCH_UNIT and load only the definitions for the appropriate section. If INCH_UNIT INCH_UNIT is unset or is not set to one of the four values listed then units units will run the last block. In this case that block uses the !message !message command to display a warning message. Alternatively that block could set default values.
In order to create default values that are overridden by user settings the data file can use the !set !set command, which sets an environment variable only if it is not already set; these settings are only for the current units units invocation and do not persist. So if the example above were preceded by !set INCH_UNIT france !set INCH_UNIT france then this would make france france the default value for INCH_UNIT. INCH_UNIT. If the user had set the variable in the environment before invoking units, units, then units units would use the users value.
To link these settings to the users locale you combine the !set !set command with the !locale !locale command. If you wanted to combine the above example with suitable locales you could do by preceding the above definition with the following:
!locale en_US !set INCH_UNIT usa !endlocale !locale en_GB !set INCH_UNIT uk !endlocale !locale en_CA !set INCH_UNIT canada !endlocale !locale fr_FR !set INCH_UNIT france !endlocale !set INCH_UNIT france
These definitions set the overall default for INCH_UNIT INCH_UNIT to france france and set default values for four locales appropriately. The overall default setting comes last so that it only applies when INCH_UNIT INCH_UNIT was not set by one of the other commands or by the user.
If the variable given after !var !var or !varnot !varnot is undefined then units units prints an error message and ignores the definitions that follow. Use !set !set to create defaults to prevent this situation from arising. The -c -c option only checks the definitions that are active for the current environment and locale, so when adding new definitions take care to check that all cases give rise to a well defined set of definitions.
The units units program uses the following environment variables:
HOME Specifies the location of your home directory; it is used by units units to find a personal units data file .units. .units. On systems running Microsoft Windows, the file is unitdef.units, unitdef.units, and if HOME HOME does not exist, units units tries to determine your home directory from the HOMEDRIVE HOMEDRIVE and HOMEPATH HOMEPATH environment variables; if these variables do not exist, units finally tries USERPROFILEtypically USERPROFILEtypically C:\Users\username C:\Users\username (Windows Vista and Windows 7) or C:\Documents and Settings\username C:\Documents and Settings\username (Windows XP). LC_CTYPE, LANG Checked to determine the locale if units units cannot obtain it from the operating system. Sections of the standard units data file are specific to certain locales. MYUNITSFILE Specifies your personal units data file. If this variable exists, units units uses its value rather than searching your home directory for .units. .units. The personal units file will not be loaded if any data files are given using the -f -f option. PAGER Specifies the pager to use for help and for displaying the conformable units. The help function browses the units database and calls the pager using the +nn +nn syntax for specifying a line number. The default pager is more; more; PAGER PAGER can be used to specify alternatives such as less, less, pg, pg, emacs, emacs, or vi. vi. UNITS_ENGLISH Set to either US US or GB GB to choose United States or British volume definitions, overriding the default from your locale. UNITSFILE Specifies the units data file to use (instead of the default). You can only specify a single units data file using this environment variable. If units data files are given using the -f -f option, the file specified by UNITSFILE UNITSFILE will be not be loaded unless the -f -f option is given with the empty string (units -f (units -f UNITSLOCALEMAP Windows only; this variable has no effect on Unix-like systems. Specifies the units locale map file to use (instead of the default). This variable seldom needs to be set, but you can use it to ensure that the locale map file will be found if you specify a location for the units data file using either the -f -f option or the UNITSFILE UNITSFILE environment variable, and that location does not also contain the locale map file.
The units units program uses two default data files: definitions.units definitions.units and currency.units. currency.units. The program can also use an optional personal units data file .units .units (unitdef.units (unitdef.units under Windows) located in the users home directory. The personal units data file is described in more detail in Units Data Files.
On Unix-like systems, the data files are typically located in /usr/share/units /usr/share/units if units units is provided with the operating system, or in /usr/local/share/units /usr/local/share/units if units units is compiled from the source distribution.
On systems running Microsoft Windows, the files may be in the same locations if Unix-like commands are available, a Unix-like file structure is present (e.g., C:/usr/local), C:/usr/local), and units units is compiled from the source distribution. If Unix-like commands are not available, a more common location is C:\Program Files (x86)\GNU\units C:\Program Files (x86)\GNU\units (for 64-bit Windows installations) or C:\Program Files\GNU\units C:\Program Files\GNU\units (for 32-bit installations).
If units units is obtained from the GNU Win32 Project (http://gnuwin32.sourceforge.net/), the files are commonly in C:\Program Files\GnuWin32\share\units. C:\Program Files\GnuWin32\share\units.
If the default units data file is not an absolute pathname, units units will look for the file in the directory that contains the units units program; if the file is not found there, units units will look in a directory ../share/units ../share/units relative to the directory with the units units program.
You can determine the location of the files by running units --version. units --version. Running units --info units --info will give you additional information about the files, how units units will attempt to find them, and the status of the related environment variables.
The standard units data file is in Unicode, using UTF-8 encoding. Most definitions use only ASCII characters (i.e., code points U+0000 through U+007F); definitions using non-ASCII characters appear in blocks beginning with !utf8 !utf8 and ending with !endutf8. !endutf8.
When units units starts, it checks the locale to determine the character set. If units units is compiled with Unicode support and definitions; otherwise these definitions are ignored. When Unicode support is active, units units will check every line of all of the units data files for invalid or non-printing UTF-8 sequences; if such sequences occur, units units ignores the entire line. In addition to checking validity, units units determines the display width of non-ASCII characters to ensure proper positioning of the pointer in some error messages and to align columns for the search search and ? ? commands.
At present, units units does not support Unicode under Microsoft Windows. The UTF-16 and UTF-32 encodings are not supported on any systems.
If definitions that contain non-ASCII characters are added to a units data file, those definitions should be enclosed within !utf8 !utf8 . . . !endutf8 !endutf8 to ensure that they are only loaded when Unicode support is available. As usual, the ! ! must appear as the first character on the line. As discussed in Units Data Files, its usually best to put such definitions in supplemental data files linked by an !include !include command or in a personal units data file.
When Unicode support is not active, units units makes no assumptions about character encoding, except that characters in the range 00-7F hexadecimal correspond to ASCII encoding. Non-ASCII characters are simply sequences of bytes, and have no special meanings; for definitions in supplementary units data files, you can use any encoding consistent with this assumption. For example, if you wish to use non-ASCII characters in definitions when running units units under Windows, you can use a character set such as Windows ANSI (code page 1252 in the US and Western Europe). You can even use UTF-8, though some messages may be improperly aligned, and units units will not detect invalid UTF-8 sequences. If you use UTF-8 encoding when Unicode support is not active, you should place any definitions with non-ASCII characters outside !utf8 !utf8 . . . !endutf8 !endutf8 blocksotherwise, they will be ignored.
Typeset material other than code examples usually uses the Unicode minus (U+2212) rather than the ASCII hyphen-minus operator (U+002D) used in units; units; the figure dash (U+2012) and en dash (U+2013) are also occasionally used. To allow such material to be copied and pasted for interactive use or in units data files, units units converts these characters to U+002D before further processing. Because of this, none of these characters can appear in unit names.
If the readline readline package has been compiled in, then when units units is used interactively, numerous command line editing features are available. To check if your version of units units includes readline, readline, invoke the program with the --version --version option.
For complete information about readline, readline, consult the documentation for the readline readline package. Without any configuration, units units will allow editing in the style of emacs. Of particular use with units units are the completion commands.
If you type a few characters and then hit ESC followed by ? ? then units units will display a list of all the units that start with the characters typed. For example, if you type metr 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 units will provide the rest of the unit name. If units units beeps, it means that there is no unique completion. Pressing the TAB key a second time will print the list of all completions.
The units program includes currency exchange rates and prices for some precious metals in the database. Of course, these values change over time, sometimes very rapidly, and units units cannot provide real time values. To update the exchange rates run the units_cur, units_cur, which rewrites the files containing the currency rates, typically /usr/share/units/currency.units. /usr/share/units/currency.units. This program requires python python and the unidecode unidecode package, and must be run with suitable permissions to write the file. To keep the rates updated automatically, run it using a cron job on a Unix-like system, or a similar scheduling program on a different system. Currency exchange rates are taken from Time Genie (http://www.timegenie.com) and precious metals pricing from Packetizer (www.packetizer.com). These sites update once per day, so there is no benefit in running the update script more often than daily. You can run units_cur units_cur with a filename specified on the command line and it will write the data to that file. If you give - - for the file it will write to standard output.
unit definition Define a regular unit. prefix- definition Define a prefix. funcname(var) noerror units=[in-units,out-units] domain=[x1,x2] range=[y1,y2] definition(var) ; inverse(funcname) Define a nonlinear unit or unit function. The four optional keywords noerror, noerror, units=, units=, range= range= and domain= domain= can appear in any order. The definition of the inverse is optional. tabname[out-units] noerror pair-list Define a piecewise linear unit. The pair list gives the points on the table listed in ascending order. The noerror noerror keyword is optional. !endlocale End a block of definitions beginning with !locale !locale !endutf8 End a block of definitions begun with !utf8 !utf8 !endvar End a block of definitions begun with !var !var or !varnot !varnot !include file Include the specified file. !locale value Load the following definitions only of the locale is set to value. !message text Display text when the database is read unless the quiet option (-q (-q is enabled. !set variable value Sets the environment variable, variable, to the specified value only if it is not already set. !unitlist alias definition Define a unit list alias. !utf8 Load the following definitions only if units units is running with UTF-8 enabled. !var envar value-list Load the block of definitions that follows only if the environment variable envar is set to one of the values listed in the space-separated value list. If envar is not set, units units prints an error message and ignores the block of definitions. !varnot envar value-list Load the block of definitions that follows only if the environment variable envar is set to value that is not listed in the space-separated value list. If envar is not set, units units prints an error message and ignores the block of definitions.
/usr/local/share/units/definitions.units the standard units data file
|-->||UNITS (1)||19 March 2014|