imported>Thüringer: /* top */ missing space

2025-09-17T07:36:13Z

top: missing space

New page

{{short description|Data serialization format}}
'''Bencode''' (pronounced like ''Bee-encode'') is the encoding used by the [[peer-to-peer]] file sharing system [[BitTorrent (protocol)|BitTorrent]] for storing and transmitting loosely structured data.<ref>[https://www.bittorrent.org/beps/bep_0003.html The BitTorrent Protocol Specification] {{Webarchive|url=https://web.archive.org/web/20190726102940/http://www.bittorrent.org/beps/bep_0003.html |date=2019-07-26 }}. BitTorrent.org. Retrieved 8 October 2018.</ref>

It supports four different types of values:
* [[string (computer science)|byte strings]],
* [[integer]]s,
* [[List (computing)|list]]s (arrays), and
* [[associative array|dictionaries (associative arrays)]].

Bencoding is most commonly used in [[torrent file]]s, and as such is part of the BitTorrent specification. These [[metadata]] files are simply bencoded dictionaries.

Bencoding is simple and (because numbers are encoded as text in decimal notation) is unaffected by [[endianness]], which is important for a [[cross-platform]] application like BitTorrent. It is also fairly flexible, as long as applications ignore unexpected dictionary keys, so that new ones can be added without creating incompatibilities.

== Encoding Algorithm ==

Bencode uses ASCII characters as delimiters and digits to encode data structures in a simple and compact format.

* '''Integers''' are encoded as <code>i<base10 integer>e</code>.
** The integer is encoded in base 10 and may be negative (indicated by a leading hyphen-minus).
** Leading zeros are not allowed unless the integer is zero.
** Examples:
*** Zero is encoded as <code>i0e</code>.
*** The number 42 is encoded as <code>i42e</code>.
*** Negative forty-two is encoded as <code>i-42e</code>.

* '''Byte Strings''' are encoded as <code><length>:<contents></code>.
** The length is the number of bytes in the string, encoded in base 10.
** A colon (<code>:</code>) separates the length and the contents.
** The contents are the exact number of bytes specified by the length.
** The contents are a sequence of bytes (not a textual string)
** Examples:
*** An empty string is encoded as <code>0:</code>.
*** The string "bencode" is encoded as <code>7:bencode</code>.

* '''Lists''' are encoded as <code>l<elements>e</code>.
** Begins with <code>l</code> and ends with <code>e</code>.
** Elements are bencoded values concatenated without delimiters.
** Examples:
*** An empty list is encoded as <code>le</code>.
*** A list containing the string "bencode" and the integer -20 is encoded as <code>l7:bencodei-20ee</code>.

* '''Dictionaries''' are encoded as <code>d<pairs>e</code>.
** Begins with <code>d</code> and ends with <code>e</code>.
** Contains key-value pairs.
** Keys are byte strings and must appear in lexicographical order.
** Each key is immediately followed by its value, which can be any bencoded type.
** Examples:
*** An empty dictionary is encoded as <code>de</code>.
*** A dictionary with keys "wiki" → "bencode" and "meaning" → 42 is encoded as <code>d7:meaningi42e4:wiki7:bencodee</code>.

There are no restrictions on the types of values stored within lists and dictionaries; they may contain other lists and dictionaries, allowing for arbitrarily complex data structures.

Bencode defines only byte string types, rather than any particular [[character encoding]] for storing text. Downstream applications and data format specifications that use bencode are free to specify whichever encoding they prefer for encoding text into bencoded byte strings.

=== Types of errors in Bencode ===

Here is the list of the possible errors that a ill-formatted bencode may have:

# Null root value.
# Non-singular root item.
# Invalid type encountered (character not 'i', 'l', 'd', or '0'-'9').
# Missing 'e' terminator for 'i', 'l', or 'd' types.
# '''Integer errors:'''
## Contains non-digit characters.
## Has a leading zero.
## Is negative zero.
# '''Byte string errors:'''
## Negative length.
## Length not followed by ':'.
## Unexpected EOF before completing string.
## Length specified in units of codepoints (characters) rather than bytes.
# '''Dictionary errors:'''
## Key is not a string.
## Duplicate keys.
## Keys not sorted.
## Keys incorrectly sorted by codepoint in a particular character encoding, rather than lexicographically sorted by ordinal.
## Missing value for a key.

==Features==
Bencode is a very specialized kind of binary coding with some unique properties:

* For each possible (complex) value, there is only a single valid bencoding; i.e. there is a [[bijection]] between values and their encodings. This has the advantage that applications may compare bencoded values by comparing their encoded forms, eliminating the need to decode the values.
* Bencoding serves similar purposes as data languages like [[JSON]] and [[YAML]], allowing complex yet loosely structured data to be stored in a [[platform independent]] way. This allowing a linear memory storage for complex data.

== Drawbacks ==

Bencode is not considered a [[human-readable]] encoding format. While the BE codegroups can be decoded manually, the bencoded values often contain [[Binary file|binary data]], so decoding by hand may be error prone. It is not safe to edit bencode files in text editors because bencoded files contain binary data, so a [[hex editor]] or specialised bencode editor tool must be used.

Bencode does not store any metadata about the size of list or dictionary structures, requiring all preceding elements to be read sequentially in order to reach a particular field. As such, bencode may not be suitable for large data structures where [[random access]] to fields is required.

==See also==
*[[Canonical S-expressions]]
*[[BitTorrent (protocol)|BitTorrent]]

== References ==
{{Reflist}}

==External links==
* [https://wiki.theory.org/BitTorrentSpecification#Bencoding Bencoding specification]
* [http://pear.php.net/package/File_Bittorrent2/ File_Bittorrent2] - Another PHP Bencode/decode implementation
* [https://pypi.python.org/pypi/BitTorrent-bencode/5.0.8 The original BitTorrent implementation in Python as standalone package]
* [https://torrent-file-editor.github.io/ Torrent File Editor] cross-platform GUI editor for BEncode files
* [http://zakalwe.fi/~shd/foss/bencode-tools/ bencode-tools] - a C library for manipulating bencoded data and a XML schema like validator for bencode messages in Python
* [https://github.com/folz/bento Bento] - Bencode library in Elixir.
* [https://github.com/soulaway/beecoder Beecoder] - the file stream parser that de/encoding "B-encode" data format on Java using java.io.* stream Api.
* [https://web.archive.org/web/20131203085012/http://www.codecommit.com/blog/java/bencode-stream-parsing-in-java Bencode parsing in Java]
* [https://bitbucket.org/cs0ip/scala-lib_cs0ip.bencode Bencode library in Scala]
* [https://web.archive.org/web/20110724074506/http://funzix.git.sourceforge.net/git/gitweb.cgi?p=funzix%2Ffunzix%3Ba%3Dblob%3Bf%3Dbencode%2Fbencode.c Bencode parsing in C]
* [https://metacpan.org/search?q=bencode There are numerous Perl implementations on CPAN]

[[Category:BitTorrent]]
[[Category:Data serialization formats]]

Bencode - Revision history

imported>Thüringer: /* top */ missing space