docs: Added All FreeBSD Manuals

1 files changed, 473 insertions, 0 deletions

diff --git a/static/freebsd/man1/units.1 b/static/freebsd/man1/units.1
new file mode 100644
index 00000000..c462c0d7
--- /dev/null
+++ b/static/freebsd/man1/units.1
@@ -0,0 +1,473 @@
+.Dd March 17, 2020
+.Dt UNITS 1
+.Os
+.Sh NAME
+.Nm units
+.Nd conversion calculator
+.Sh SYNOPSIS
+.Nm
+.Op Fl ehqtUVv
+.Op Fl f Ar unitsfile
+.Op Fl o Ar format
+.Op Ar from to
+.Sh DESCRIPTION
+The
+.Nm
+program converts quantities expressed in various scales to
+their equivalents in other scales.
+It can only
+handle multiplicative or affine scale changes.
+.Pp
+.Nm
+can work interactively by prompting
+the user for input
+.Pq see Sx EXAMPLES
+or non-interactively, providing a conversion for given arguments
+.Ar from
+and
+.Ar to .
+.Pp
+The following options are available:
+.Bl -tag -width "from to"
+.It Fl e , Fl -exponential
+Same as
+.Fl o
+.Cm %6e
+(see the description of the
+.Fl o
+flag).
+.It Fl f Ar unitsfile , Fl -file Ar unitsfile
+Specify the name of the units data file to load.
+This option may be specified multiple times.
+.It Fl H Ar historyfile , Fl -history Ar historyfile
+Ignored, for compatibility with GNU units.
+.It Fl h , Fl -help
+Show an overview of options.
+.It Fl o Ar format , Fl -output-format Ar format
+Select the output format string by which numbers are printed.
+Defaults to
+.Dq Li %.8g .
+.It Fl q , Fl -quiet
+Suppress prompting of the user for units and the display of statistics
+about the number of units loaded.
+.It Fl t , Fl -terse
+Only print the result.
+This is used when calling
+.Nm
+from other programs for easy to parse results.
+.It Fl U , Fl -unitsfile
+Print the location of the default unit file if it exists.
+Otherwise, print
+.Dq Units data file not found .
+.It Fl V , Fl -version
+Print the version number
+.Pq which is fixed at Dq Fx units ,
+the path to the units data file and exit.
+.It Fl v , Fl -verbose
+Print the units in the conversion output.
+Be more verbose in general.
+.It Ar from to
+Allow a single unit conversion to be done directly from the command
+line.
+The program will not print prompts.
+It will print out the result of the single specified conversion.
+Both arguments, i.e.,
+.Ar from
+and
+.Ar to ,
+can be just a unit
+.Pq e.g., Dq Cm cm ,
+a quantity
+.Pq e.g., Dq Cm 42 ,
+or a quantity with a unit
+.Pq e.g., Dq Cm 42 cm
+.El
+.Ss Mathematical operators
+.Bl -dash -compact
+.It
+Powers of units can be specified using the
+.Dq Ic ^
+character as shown in the example, or by simple concatenation:
+.Dq Ic cm3
+is
+equivalent to
+.Dq Ic cm^3 .
+See the
+.Sx BUGS
+section
+for details on the limitations of exponent values.
+.It
+Multiplication of units can be specified by using spaces
+.Pq Dq " " ,
+a dash
+.Pq Dq -
+or an asterisk
+.Pq Dq * .
+.It
+Division of units is indicated by the slash
+.Pq Dq Ic / .
+.It
+Division of numbers
+must be indicated using the vertical bar
+.Pq Dq Ic \&| Ns .
+.El
+.Pp
+Note that multiplication has a higher precedence than division,
+so
+.Dq Ic m/s/s
+is the same as
+.Dq Ic m/s^2
+or
+.Dq Ic m/s s .
+.Ss Units
+The conversion information is read from a units data file.
+The default
+file includes definitions for most familiar units, abbreviations and
+metric prefixes.
+Some constants of nature included are:
+.Pp
+.Bl -column -offset indent -compact "mercury"
+.It "pi	ratio of circumference to diameter"
+.It "c	speed of light"
+.It "e	charge on an electron"
+.It "g	acceleration of gravity"
+.It "force	same as g"
+.It "mole	Avogadro's number"
+.It "water	pressure per unit height of water"
+.It "mercury	pressure per unit height of mercury"
+.It "au	astronomical unit"
+.El
+.Pp
+The unit
+.Dq Ic pound
+is a unit of mass.
+Compound names are run together
+so
+.Dq Ic pound force
+is a unit of force.
+The unit
+.Dq Ic ounce
+is also a unit of mass.
+The fluid ounce is
+.Dq Ic floz .
+British units that differ from
+their US counterparts are prefixed with
+.Dq br ,
+and currency is prefixed with its country name:
+.Dq Ic belgiumfranc ,
+.Dq Ic britainpound .
+When searching
+for a unit, if the specified string does not appear exactly as a unit
+name, then
+.Nm
+will try to remove a trailing
+.Dq s
+or a trailing
+.Dq es
+and check again for a match.
+.Ss Units file format
+To find out what units are available read the standard units file.
+If you want to add your own units you can supply your own file.
+A unit is specified on a single line by
+giving its name and an equivalence.
+Be careful to define
+new units in terms of old ones so that a reduction leads to the
+primitive units which are marked with
+.Dq \&!
+characters.
+The
+.Nm
+program will not detect infinite loops that could be caused
+by careless unit definitions.
+Comments in the unit definition file
+begin with a
+.Dq #
+or
+.Dq /
+character at the beginning of a line.
+.Pp
+Prefixes are defined in the same way as standard units, but with
+a trailing dash
+.Pq Dq -
+at the end of the prefix name.
+If a unit is not found
+even after removing trailing
+.Dq s
+or
+.Dq es ,
+then it will be checked against the list of prefixes.
+Prefixes will be removed until a legal
+base unit is identified.
+.Sh ENVIRONMENT
+.Bl -tag -width PATH
+.It Ev PATH
+The colon-separated list of root directories at which
+.Nm
+tries to find
+.Pa /usr/share/misc/definitions.units .
+.Pp
+For example if
+.Ev PATH
+is set to
+.Dq Li /tmp:/:/usr/local ,
+no
+.Fl f
+flags are provided, and
+.Pa /usr/share/misc/definitions.units
+is missing then
+.Nm
+tries to open the following files as the default units file:
+.Pa /tmp/usr/share/misc/definitions.units ,
+.Pa /usr/share/misc/definitions.units ,
+and
+.Pa /usr/local/usr/share/misc/definitions.units .
+.El
+.Sh FILES
+.Bl -tag -width /usr/share/misc/definitions.units -compact
+.It Pa /usr/share/misc/definitions.units
+The standard units file.
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+.Bl -tag -width 0n
+.It Sy Example 1 : No Simple conversion of units
+.Pp
+This example shows how to do simple conversions, for example from gigabytes
+to bytes:
+.Bd -literal -offset 2n
+.Li $ Ic units -o %0.f -t '4 gigabytes' bytes
+4294967296
+.Ed
+.Pp
+The
+.Fl o Cm %0.f
+part of the command is required to print the result in a non-scientific
+notation (e.g, 4294967296 instead of 4.29497e+09).
+.It Sy Example 2 : No Interactive usage
+.Pp
+Here is an example of an interactive session where the user is prompted for
+units:
+.Bd -literal -offset 2n
+.Li You have : Ic meters
+.Li You want : Ic feet
+        * 3.2808399
+        / 0.3048
+
+.Li You have : Ic cm^3
+.Li You want : Ic gallons
+        * 0.00026417205
+        / 3785.4118
+
+.Li You have : Ic meters/s
+.Li You want : Ic furlongs/fortnight
+        * 6012.8848
+        / 0.00016630952
+
+.Li You have : Ic 1|2 inch
+.Li You want : Ic cm
+        * 1.27
+        / 0.78740157
+
+.Li You have : Ic 85 degF
+.Li You want : Ic degC
+        29.444444
+.Ed
+.It Sy Example 3 : No Difference between Do Ic \&| Dc No and Do Ic / Dc No division
+.Pp
+The following command shows how to convert half a meter to centimeters.
+.Bd -literal -offset 2n
+.Li $ Ic units '1|2 meter' cm
+        * 50
+        / 0.02
+.Ed
+.Pp
+.Nm
+prints the expected result because the division operator for numbers
+.Pq Dq Li \&|
+was used.
+.Pp
+Using the division operator for units
+.Pq Dq Li /
+would result in an error:
+.Bd -literal -offset 2n
+.Li $ Ic units '1/2 meter' cm
+conformability error
+        0.5 / m
+        0.01 m
+.Ed
+.Pp
+It is because
+.Nm
+interprets
+.Dq Ic 1/2 meter
+as
+.Dq Ic 0.5/meter ,
+which is not conformable to
+.Dq Ic cm .
+.It Sy Example 4 : No Simple units file
+Here is an example of a short units file that defines some basic
+units:
+.Pp
+.Bl -column -offset 2n -compact "minute"
+.It "m	!a!"
+.It "sec	!b!"
+.It "micro-	1e-6"
+.It "minute	60 sec"
+.It "hour	60 min"
+.It "inch	0.0254 m"
+.It "ft	12 inches"
+.It "mile	5280 ft"
+.El
+.It Sy Example 5 : No Viewing units and conversions of the default units file
+The following shell one-liner allows the user to view the contents of the
+default units file:
+.Bd -literal -offset 2n
+.Li $ Ic less \&"$(units -U)"
+.Ed
+.El
+.Sh DIAGNOSTICS
+.Bl -diag
+.It can't find units file '%s'
+The default units file is not in its default location
+.Pq see Sx FILES
+and it is not present in any file tree starting with their roots at directories from
+.Ev PATH
+.Pq see Sx ENVIRONMENT .
+.It cap_rights_limit\&() failed
+See
+.Xr capsicum  4 .
+.It conformability error
+It is not possible to reduce the given units to one common unit:
+they are not conformable.
+Instead of a conversion,
+.Nm
+will display the reduced form for each provided unit:
+.Bd -literal -offset 2n
+.Li You have : Ic ergs/hour
+.Li You want : Ic fathoms kg^2 / day
+conformability error
+        2.7777778e-11 kg m^2 / sec^3
+        2.1166667e-05 kg^2 m / sec
+.Ed
+.It Could not initialize history
+See
+.Xr editline 3 .
+.It dupstr
+.Xr strdup 3
+failed.
+.It memory for prefixes exceeded in line %d
+Over 100 prefixes were defined.
+.It memory for units exceeded in line %d
+Over 1000 prefixes were defined.
+.It memory overflow in unit reduction
+The requested conversion involves too many units
+.Pq see Sx BUGS .
+.It redefinition of prefix '%s' on line %d ignored
+.No ""
+.It redefinition of unit '%s' on line %d ignored
+.No ""
+.It unexpected end of prefix on line %d
+.No ""
+.It unexpected end of unit on line %d
+.No ""
+.It Units data file not found
+The default units file is missing.
+.It unable to enter capability mode
+See
+.Xr capsicum  4 .
+.It unable to open units file '%s'
+One of the user-specified units files cannot be opened.
+.It unit reduces to zero
+.No ""
+.It unknown unit '%s'
+The provided unit cannot be found in the units file.
+.It WARNING: conversion of non-proportional quantities.
+.Nm
+may fail to convert
+.Ar from
+to
+.Ar to
+because the units are not proportional.
+The warning is printed when a quantity is a part of the
+.Ar to
+argument.
+It can be illustrated on an example of conversion from Fahrenheit to Celsius:
+.Bd -literal -offset 2n
+.Li $ Ic units \&"degF" \&"degC"
+         (-> x*0.55555556g -17.777778g)
+         (<- y*1.8g 32g)
+.Li $ Ic units \&"degF" \&"1 degC"
+WARNING: conversion of non-proportional quantities.
+         (-> x*0.55555556g -17.777778g)
+         (<- y*1.8g 32g)
+.Li $ Ic units \&"1 degF" \&"1 degC"
+WARNING: conversion of non-proportional quantities.
+        -17.222222
+.Ed
+.El
+.Sh SEE ALSO
+.Xr bc 1
+.Sh HISTORY
+The
+.Nm
+first appeared in
+.Nx
+and was ported to
+.Fx 2.2.0 .
+.Pp
+The manual page was significantly rewritten in
+.Fx 13.0
+by
+.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org .
+.Sh AUTHORS
+.An Adrian Mariano Aq Mt adrian@cam.cornell.edu
+.Sh BUGS
+The effect of including a
+.Dq /
+in a prefix is surprising.
+.Pp
+Exponents entered by the user can be only one digit.
+You can work around this by multiplying several terms.
+.Pp
+The user must use
+.Dq Ic \&|
+to indicate division of numbers and
+.Dq Ic /
+to indicate division of symbols.
+This distinction should not
+be necessary.
+.Pp
+The program contains various arbitrary limits on the length
+of the units converted and on the length of the data file.
+.Pp
+The program should use a hash table to store units so that
+it does not take so long to load the units list and check
+for duplication.
+.Pp
+It is not possible to convert a negative value.
+.Pp
+The
+.Nm
+program
+does not handle reductions of long lists of units very well:
+.Bd -literal -offset 2n
+.Li $ Ic units \&"$(yes m | head -n 154)" \&"$(yes cm | head -n 154)"
+        * 1e+308
+        / 1e-308
+.Li $ Ic units \&"$(yes m | head -n 333)" \&"$(yes cm | head -n 333)"
+        * inf
+        / 0
+.Li $ Ic units \&"$(yes m | head -n 500)" \&"$(yes cm | head -n 500)"
+units: memory overflow in unit reduction
+conformability error
+        1 m^500
+        1 centi cm^499
+.Li $ Ic units \&"$(yes m | head -n 501)" \&"$(yes cm | head -n 501)"
+units: memory overflow in unit reduction
+units: memory overflow in unit reduction
+units: memory overflow in unit reduction
+conformability error
+        1 m^500
+        1 centi cm^499
+.Ed