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

FreeBSD Manual Pages


home | help
Traceroute6(3)	      User Contributed Perl Documentation	Traceroute6(3)

       Net::Traceroute6	- traceroute(1)/traceroute6(1) functionality in	perl

	   use Socket6;
	   use Net::Traceroute6;
	   $tr = Net::Traceroute6->new(host=> "");
	   if($tr->found) {
	       my $hops	= $tr->hops;
	       if($hops	> 1) {
		   print "Router was " .
		       $tr->hop_query_host($tr->hops - 1, 0) . "\n";

       This module implements traceroute(1)/traceroute6(1) functionality for
       perl5.  It allows you to	trace the path IP packets take to a
       destination.  It	is currently implemented as a parser around the	system
       traceroute command.

       A new Net::Traceroute6 object must be created with the new method.
       Depending on exactly how	the constructor	is invoked, it may perform the
       traceroute immediately, or it may return	a "template" object that can
       be used to set parameters for several subsequent	traceroutes.

       Methods are available for accessing information about a given
       traceroute attempt.  There are also methods that	view/modify the
       options that are	passed to the object's constructor.

       To trace	a route, UDP packets are sent with a small TTL (time-to-live)
       field in	an attempt to get intervening routers to generate ICMP
       TIME_EXCEEDED messages.

	   $obj	= Net::Traceroute6->new([base_port     => $base_port,]
				       [debug	       => $debuglvl,]
				       [max_ttl	       => $max_ttl,]
				       [host	       => $host,]
				       [queries	       => $queries,]
				       [query_timeout  => $query_timeout,]
				       [af	       => $address_family,]
				       [timeout	       => $timeout,]);
	   $frob = $obj->new([options]);

       This is the constructor for a new Net::Traceroute6 object.  If given
       "host", it will actually	perform	the traceroute;	otherwise it will
       return an empty template	object.	 This can be used to setup a template
       object with some	preset defaults	for firing off multiple	traceroutes.

       Given an	existing Net::Traceroute object	$obj as	a template, you	can
       call $obj->new()	with the usual parameters.  The	same rules apply about
       defining	host; that is, traceroute will be run if it is defined.	 You
       can always pass host => undef in	the constructor	call.

       To use a	template objects to perform a traceroute, you invoke new on it
       and pass	a host option.

       Possible	options	are:

       host - A	host to	traceroute to.	If you don't set this, you get a
       Traceroute object with no traceroute data in it.	 The module always
       uses IP addresses internally and	will attempt to	lookup host names via

       base_port - Base	port number to use for the UDP queries.	 Traceroute
       assumes that nothing is listening to port "base_port" to	"base_port +
       (nhops -	1)" where nhops	is the number of hops required to reach	the
       destination address.  Default is	what the system	traceroute uses
       (normally 33434).  "Traceroute"'s "-p" option.

       debuglvl	- A number indicating how verbose debug	information should be.
       Please include debug=>9 output in bug reports.

       max_ttl - Maximum number	of hops	to try before giving up.  Default is
       what the	system traceroute uses (normally 30).  "Traceroute"'s "-m"

       queries - Number	of times to send a query for a given hop.  Defaults to
       whatever	the system traceroute uses (3 for most traceroutes).
       "Traceroute"'s "-q" option.

       query_timeout - How many	seconds	to wait	for a response to each query
       sent.  Uses the system traceroute's default value of 5 if unspecified.
       "Traceroute"'s "-w" option.

       timeout - Maximum time, in seconds, to wait for the traceroute to
       complete.  If not specified, the	traceroute will	not return until the
       host has	been reached, or traceroute counts to infinity ("max_ttl" *
       "queries" * "query_timeout").  Note that	this option is implemented by
       Net::Traceroute,	not the	underlying traceroute command.

       address_family -	Which address family to	use. Currently supported
       address families: PF_UNSPEC, PF_INET, PF_INET6 (if IPv6 is supported).
       If PF_UNSPEC used the "host" is specifying the currently	used address
       family. If "host" has both A and	AAAA addresses,	then you can select
       the desired address family. The default is PF_UNSPEC. The
       Net::Traceroute6	automatically select the right traceroute tool.

   Controlling traceroute invocation
       Each of these methods return the	current	value of the option specified
       by the corresponding constructor	option.	 They will set the object's
       instance	variable to the	given value if one is provided.

       Changing	an instance variable will only affect newly performed
       traceroutes.  Setting a different value on a traceroute object that has
       already performed a trace has no	effect.

       See the constructor documentation for information about each
       method/constructor option.


   Obtaining information about a Trace
       These methods return information	about a	traceroute that	has already
       been performed.

       Any of the methods in this section that return a	count of something or
       want an Nth type	count to identify something employ one based counting.

	   Returns the status of a given traceroute object.  One of
	   defined as an integer).  TRACEROUTE_OK will only be returned	if the
	   host	was actually reachable.

	   Returns 1 if	the host was found, undef otherwise.

	   Returns the number of hops that it took to reach the	host.

	   Returns the number of queries that were sent	for a given hop.  This
	   should normally be the same for every query.

       hop_query_stat(HOP, QUERY)
	   Return the status of	the given HOP's	QUERY.	The return status can
	   be one of the following (each of these is actually an integer
	   constant function defined in	Net::Traceroute's export list):

	       Reached the host, no problems.

	       This query timed	out.

	       Your guess is as	good as	mine.  Shouldn't happen	too often.

	       This hop	returned an ICMP Network Unreachable.

	       This hop	returned an ICMP Host Unreachable.

	       This hop	returned an ICMP Protocol unreachable.

	       Indicates that you can't	reach this host	without	fragmenting
	       your packet further.  Shouldn't happen in regular use.

	       A source	routed packet was rejected for some reason.  Shouldn't

	       A firewall or similar device has	decreed	that your traffic is
	       disallowed by administrative action.  Suspect sheer, raving

	       The destination machine appears to exhibit the 4.[23]BSD	time
	       exceeded	bug.

       hop_query_host(HOP, QUERY)
	   Return the dotted quad IP address of	the host that responded	to
	   HOP's QUERY.

       hop_query_time(HOP, QUERY)
	   Return the round trip time associated with the given	HOP's query.
	   If your system's traceroute supports	fractional second timing, so
	   will	Net::Traceroute.

       In the previous methods,	you can	get the	first successfull QUERY
       parameters, if you specify QUERY	number as 0.

       Net::Traceroute parses the output of the	system traceroute command.  As
       such, it	may not	work on	your system.  Support for more traceroute
       outputs (e.g. Windows, HPUX) could be done, although currently the code
       assumes there is	"One true traceroute".

       For IPv6	currently only on some system is known to work:

       *BSD (FreeBSD 4.0 or later, NetBSD 1.5 or later.	OpenBSD	2.8 and	later)
       + any KAME patched BSD

       Solaris 8 or later

       Currently only few ICMPv6 error options are recognised.

       The actual functionality	of traceroute could also be implemented
       natively	in perl	or linked in from a C library.

       traceroute(1) traceroute6(1)

       Janos Mohacsi <> Daniel Hagerty

       Copyright 1998, 1999 Massachusetts Institute of Technology Copyright
       2001 Janos Mohacsi

perl v5.32.1			  2001-08-31			Traceroute6(3)


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

home | help