Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Net::BitTorrent::ProtoUser3Contributed Perl DocumeNet::BitTorrent::Protocol(3)

       Net::BitTorrent::Protocol - Packet utilities for	the BitTorrent

	   use Net::BitTorrent::Protocol qw[:build parse_packet];

	   # Tell them what we want...
	   my $handshake = build_handshake(
	       pack('C*', split('', '00000000')),
	       pack('H*', 'ddaa46b1ddbfd3564fca526d1b68420b6cd54201'),

	   # And the inverse...
	   my ($reserved, $infohash, $peerid) =	parse_packet( $handshake );

       What would BitTorrent be	without	packets?   TCP noise, mostly.

       For similar work	and links to the specifications	behind these packets,
       move on down to the See Also section.

Exporting from Net::BitTorrent::Protocol
       There are three tags available for import.  To get them all in one go,
       use the ":all" tag.

	   Packet types

	   For more on what these packets actually mean, see the BitTorrent
	   Spec.  This is a list of the	currently supported packet types:

	   These create	packets	ready-to-send to remote	peers.	See Building

	   These are used to parse unknown data	into sensible packets.

   Building Functions
       "build_handshake	( RESERVED, INFOHASH, PEERID )"
	   Creates an initial handshake	packet.	 All parameters	must conform
	   to the BitTorrent spec:

	   "RESERVED" the 8 byte	string used to represent a client's
	       capabilities for	extensions to the protocol.

	   "INFOHASH" the 20 byte SHA1 hash of the bencoded info	from the
	       metainfo	file.

	   "PEERID" 20	bytes.

       "build_keepalive	( )"
	   Creates a keep-alive	packet.	 The keep-alive	packet is zero bytes,
	   specified with the length prefix set	to zero.  There	is no message
	   ID and no payload.  Peers may close a connection if they receive no
	   packets (keep-alive or any other packet) for	a certain period of
	   time, so a keep- alive packet must be sent to maintain the
	   connection alive if no command have been sent for a given amount of
	   time.  This amount of time is generally two minutes.

       "build_choke ( )"
	   Creates a choke packet.  The	choke packet is	fixed-length and has
	   no payload.

	   See Also:	- Choking and
	   Optimistic Unchoking

       "build_unchoke (	)"
	   Creates an unchoke packet.  The unchoke packet is fixed-length and
	   has no payload.

	   See Also:	- Choking and
	   Optimistic Unchoking

       "build_interested ( )"
	   Creates an interested packet.  The interested packet	is fixed-
	   length and has no payload.

       "build_not_interested ( )"
	   Creates a not interested packet.  The not interested	packet is
	   fixed-length	and has	no payload.

       "build_have ( INDEX )"
	   Creates a have packet.  The have packet is fixed length.  The
	   payload is the zero-based INDEX of a	piece that has just been
	   successfully	downloaded and verified	via the	hash.

	   That	is the strict definition, in reality some games	may be played.
	   In particular because peers are extremely unlikely to download
	   pieces that they already have, a peer may choose not	to advertise
	   having a piece to a peer that already has that piece.  At a minimum
	   "HAVE suppression" will result in a 50% reduction in	the number of
	   HAVE	packets, this translates to around a 25-35% reduction in
	   protocol overhead. At the same time,	it may be worthwhile to	send a
	   HAVE	packet to a peer that has that piece already since it will be
	   useful in determining which piece is	rare.

	   A malicious peer might also choose to advertise having pieces that
	   it knows the	peer will never	download. Due to this attempting to
	   model peers using this information is a bad idea.

       "build_bitfield ( BITFIELD )"
	   Creates a bitfield packet.  The bitfield packet is variable length,
	   where "X" is	the length of the "BITFIELD".  The payload is a
	   "BITFIELD" representing the pieces that have	been successfully
	   downloaded.	The high bit in	the first byte corresponds to piece
	   index 0.  Bits that are cleared indicated a missing piece, and set
	   bits	indicate a valid and available piece. Spare bits at the	end
	   are set to zero.

	   A bitfield packet may only be sent immediately after	the
	   handshaking sequence	is completed, and before any other packets are
	   sent.  It is	optional, and need not be sent if a client has no
	   pieces or uses one of the Fast Extension packets: have all or have

       "build_request (	INDEX, OFFSET, LENGTH )"
	   Creates a request packet.  The request packet is fixed length, and
	   is used to request a	block.	The payload contains the following

	   "INDEX" an	integer	specifying the zero-based piece	index.

	   "OFFSET" an	integer	specifying the zero-based byte offset within
	       the piece.

	   "LENGTH" an	integer	specifying the requested length.

	   See Also: build_cancel

       "build_piece ( INDEX, OFFSET, DATA )"
	   Creates a piece packet.  The	piece packet is	variable length, where
	   "X" is the length of	the DATA.  The payload contains	the following

	   "INDEX" an	integer	specifying the zero-based piece	index.

	   "OFFSET" an	integer	specifying the zero-based byte offset within
	       the piece.

	   "DATA" the block of data,	which is a subset of the piece
	       specified by "INDEX".

	   Before sending pieces to remote peers, the client should verify
	   that	the piece matches the SHA1 hash	related	to it in the .torrent

       "build_cancel ( INDEX, OFFSET, LENGTH )"
	   Creates a cancel packet.  The cancel	packet is fixed	length,	and is
	   used	to cancel block	requests.  The payload is identical to that of
	   the request packet.	It is typically	used during 'End Game.'

	   See Also:	- End Game

       "build_extended ( DATA )"
	   Creates an extended protocol	packet.

       Legacy Packets

       The following packets are either	part of	the base protocol or one of
       the common extensions but have either been superseded or	simply removed
       from the	majority of clients.  I	have provided them here	only for
       legacy support; they will not be	removed	in the future.

       "build_port ( PORT )"
	   Creates a port packet.

	   See also: -	The BitTorrent
	   Protocol Specification

       "build_allowed_fast ( INDEX )"
	   Creates an Allowed Fast packet.

	   uTorrent never advertises a fast set... why should we?

	   See also: -	Fast Extension

       "build_suggest (	INDEX )"
	   Creates a Suggest Piece packet.

	   Super seeding is not	supported by Net::BitTorrent.  Yet.

	   See also: -	Fast Extension

       "build_reject ( INDEX, OFFSET, LENGTH )"
	   Creates a Reject Request packet.

	   See also: -	Fast Extension

       "build_have_all ( )"
	   Creates a Have All packet.

	   See also: -	Fast Extension

       "build_have_none	( )"
	   Creates a Have None packet.

	   See also: -	Fast Extension

   Parsing Function(s)
       "parse_packet( DATA )"
	   Attempts to parse any known packet from the data (a scalar ref)
	   passed to it.  On success, the payload and type are returned	and
	   the packet is removed from the incoming data	ref.  "undef" is
	   returned on failure.

See Also	- The BitTorrent Protocol
       Specification	- Fast Extension	- Extension Protocol -	An annotated guide to
       the BitTorrent protocol

       Net::BitTorrent::PeerPacket - by	Joshua McAdams

       Sanko Robinson <> -


License	and Legal
       Copyright (C) 2008-2009 by Sanko	Robinson <>

       This program is free software; you can redistribute it and/or modify it
       under the terms of The Artistic License 2.0.  See the LICENSE file
       included	with this distribution or  For	clarification,

       When separated from the distribution, all POD documentation is covered
       by the Creative Commons Attribution-Share Alike 3.0 License.  See  For
       clarification, see

       Neither this module nor the Author is affiliated	with BitTorrent, Inc.

perl v5.32.1			  2021-11-06	  Net::BitTorrent::Protocol(3)

NAME | Synopsis | Description | Exporting from Net::BitTorrent::Protocol | See Also | Author | License and Legal

Want to link to this manual page? Use this URL:

home | help