.\"
.\" Copyright 2011, Stefano Rivera <stefanor@ubuntu.com>
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.TH BYTEPREFIX 5 "January 2011" libkibi
.SH NAME
byteprefix \- Configuration for display of sizes
.\"
.SH DESCRIPTION
There are two standard ways to use units in computing: base 10 (1\ k =
10^3 = 1\ 000) and base 2 (1\ K = 2^10 = 1\ 024).
Historically, most computer programs have used units in base 2, where
1\ KB = 1\ 024\ bytes, 1\ MB = 1\ 048\ 576\ bytes, etc.
However, users are more likely to expect and understand sizes in base
10, as this is the norm outside of computing.
.P
This configuration file is a method for configuring programs (that use
libkibi) to display sizes in the user's preferred style.
It can be configured through a configuration file or environment
variable (which takes precedence).
.P
When not using the "\fBhistoric\fR" style, IEC-style prefixes (KiB, MiB,
etc.) are used for base 2 units, to disambiguate them from base 10 units
(kB, MB, etc.).
.\"
.SH OPTIONS
There are three possible styles (Default: \fBbase10\fR):
.TP
.B base2
Display all sizes in Base 2 with IEC prefixes.
.IP
1\ KiB = 1\ 024\ bytes.
.br
1\ MiB = 1\ 024\ KiB = 1\ 048\ 576\ bytes.
.br
1\ GiB = 1\ 024\ MiB = 1\ 048\ 576\ KiB = 1\ 073\ 741\ 824\ bytes.
.\"
.TP
.B base10
Display all sizes in Base 10, except for sizes of RAM, which use base 2
with IEC prefixes.
.IP
.B Everything except RAM:
.br
1\ kB = 1\ 000\ bytes.
.br
1\ MB = 1\ 000\ kB = 1\ 000\ 000\ bytes.
.br
1\ GB = 1\ 000\ MB = 1\ 000\ 000\ kB = 1\ 000\ 000\ 000\ bytes.
.IP
.B RAM:
.br
1\ KiB = 1\ 024\ bytes.
.br
1\ MiB = 1\ 024\ KiB = 1\ 048\ 576\ bytes.
.br
1\ GiB = 1\ 024\ MiB = 1\ 048\ 576\ KiB = 1\ 073\ 741\ 824\ bytes.
.\"
.TP
.B historic
Display all sizes in Base 2, without IEC prefixes.
.IP
1\ KB = 1\ 024\ bytes.
.br
1\ MB = 1\ 024\ KB = 1\ 048\ 576\ bytes.
.br
1\ GB = 1\ 024\ MB = 1\ 048\ 576\ KB = 1\ 073\ 741\ 824\ bytes.
.IP
\fBNot recommended.\fR This style uses base units 2 with prefixes
usually associated with base 10 units.
While it uses \fBKB\fR rather than the SI (base 10) \fBkB\fR, there is
no such distinction beyond the kilobyte range, and the units are
ambiguous.
.\"
.SH ENVIRONMENT
.TP
.B BYTEPREFIX
This environment variable will override the configured or default style.
It should just contain one of the style names, listed in OPTIONS above.
.TP
.B XDG_CONFIG_HOME
The location of the user's configuration files.
If not set, it will be assumed to be \fB~/.config\fR.
.\"
.SH FILES
The preferred style can be set in a system-wide configuration file
and/or in user's own configuration file (which will take precedence).
If no configuration file exists, the default style is
\fBbase10\fR.
.TP
.B /etc/byteprefix\fR or \fIXDG_CONFIG_HOME\fB/byteprefix
This file should contain a single line: \fBformat=\fIstyle\fR.
Lines beginning with \fB#\fR are treated as comments.
.\"
.SH EXAMPLE
A user wanting \fIbase 2\fR display can set the following in
\fB~/.config/byteprefix\fR:
.IP
.nf
format=base2
.fi
.\"
.SH SEE ALSO
.BR units (7)