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

FreeBSD Manual Pages

  
 
  

home | help
PCAP-TSTAMP(7)	       Miscellaneous Information Manual		PCAP-TSTAMP(7)

NAME
       pcap-tstamp - packet time stamps	in libpcap

DESCRIPTION
       When capturing traffic, each packet is given a time stamp representing,
       for incoming packets, the arrival time of the packet and, for  outgoing
       packets,	the transmission time of the packet.  This time	is an approxi-
       mation of the arrival or	transmission time.  If it is supplied  by  the
       operating  system  running  on  the  host on which the capture is being
       done, there are several reasons why it might  not  precisely  represent
       the arrival or transmission time:

	      if  the  time stamp is applied to	the packet when	the networking
	      stack receives the packet, the networking	stack  might  not  see
	      the  packet  until an interrupt is delivered for the packet or a
	      timer event causes the networking	 device	 driver	 to  poll  for
	      packets,	and  the  time	stamp  might  not be applied until the
	      packet has had some processing done by other code	 in  the  net-
	      working stack, so	there might be a significant delay between the
	      time when	the last bit of	the packet is received by the  capture
	      device and when the networking stack time-stamps the packet;

	      the  timer used to generate the time stamps might	have low reso-
	      lution, for example, it might be a timer updated once  per  host
	      operating	 system	 timer	tick,  with  the host operating	system
	      timer ticking once every few milliseconds;

	      a	high-resolution	timer might use	a counter that runs at a  rate
	      dependent	 on  the  processor  clock speed, and that clock speed
	      might be adjusted	upwards	or downwards over time and  the	 timer
	      might not	be able	to compensate for all those adjustments;

	      the host operating system's clock	might be adjusted over time to
	      match a time standard to which the host is  being	 synchronized,
	      which  might  be done by temporarily slowing down	or speeding up
	      the clock	or by making a single adjustment;

	      different	CPU cores on a multi-core  or  multi-processor	system
	      might  be	 running  at  different	speeds,	or might not have time
	      counters all synchronized, so packets time-stamped by  different
	      cores might not have consistent time stamps.

       In  addition,  packets  time-stamped  by	different cores	might be time-
       stamped in one order and	added to the queue of packets for  libpcap  to
       read  in	 another  order,  so  time  stamps  might not be monotonically
       increasing.

       Some capture devices on some platforms  can  provide  time  stamps  for
       packets;	those time stamps are usually high-resolution time stamps, and
       are usually applied to the packet when the first	or  last  bit  of  the
       packet arrives, and are thus more accurate than time stamps provided by
       the host	operating system.  Those time stamps might  not,  however,  be
       synchronized with the host operating system's clock, so that, for exam-
       ple, the	time stamp of a	packet might not correspond to the time	 stamp
       of an event on the host triggered by the	arrival	of that	packet.

       Depending  on  the capture device and the software on the host, libpcap
       might  allow  different	types  of  time	 stamp	to   be	  used.	   The
       pcap_list_tstamp_types(3PCAP)  routine  provides,  for a	packet capture
       handle  created	by  pcap_create(3PCAP)	but  not  yet	activated   by
       pcap_activate(3PCAP),  a	list of	time stamp types supported by the cap-
       ture device for that handle.  The list might be empty, in which case no
       choice  of  time	stamp type is offered for that capture device.	If the
       list is not empty, the pcap_set_tstamp_type(3PCAP) routine can be  used
       after a pcap_create() call and before a pcap_activate() call to specify
       the type	of time	stamp to be used on the	device.	 The time stamp	 types
       are  listed  here;  the	first value is the #define to use in code, the
       second value is the value  returned  by	pcap_tstamp_type_val_to_name()
       and accepted by pcap_tstamp_type_name_to_val().

	    PCAP_TSTAMP_HOST - host
		 Time stamp provided by	the host on which the capture is being
		 done.	The precision of this time stamp  is  unspecified;  it
		 might	or  might  not be synchronized with the	host operating
		 system's clock.

	    PCAP_TSTAMP_HOST_LOWPREC - host_lowprec
		 Time stamp provided by	the host on which the capture is being
		 done.	 This is a low-precision time stamp, synchronized with
		 the host operating system's clock.

	    PCAP_TSTAMP_HOST_HIPREC - host_hiprec
		 Time stamp provided by	the host on which the capture is being
		 done.	This is	a high-precision time stamp; it	might or might
		 not be	synchronized with the host operating  system's	clock.
		 It    might	be    more    expensive	   to	 fetch	  than
		 PCAP_TSTAMP_HOST_LOWPREC.

	    PCAP_TSTAMP_ADAPTER	- adapter
		 Time stamp provided by	the network adapter on which the  cap-
		 ture  is  being  done.	  This is a high-precision time	stamp,
		 synchronized with the host operating system's clock.

	    PCAP_TSTAMP_ADAPTER_UNSYNCED - adapter_unsynced
		 Time stamp provided by	the network adapter on which the  cap-
		 ture  is being	done.  This is a high-precision	time stamp; it
		 is not	synchronized with the host operating system's clock.

       By default, when	performing a live capture or reading from a  savefile,
       time  stamps  are  supplied  as seconds since January 1,	1970, 00:00:00
       UTC, and	microseconds since that	seconds	value, even if	higher-resolu-
       tion  time stamps are available from the	capture	device or in the save-
       file.  If, when reading a savefile, the time stamps in the file have  a
       higher  resolution than one microsecond,	the additional digits of reso-
       lution are discarded.

       The  pcap_set_tstamp_precision(3PCAP)  routine  can  be	used  after  a
       pcap_create() call and after a pcap_activate() call to specify the res-
       olution of the time stamps to get for the device.  If the  hardware  or
       software	  cannot   supply   a	higher-resolution   time   stamp,  the
       pcap_set_tstamp_precision() call	will fail, and the  time  stamps  sup-
       plied after the pcap_activate() call will have microsecond resolution.

       When   opening  a  savefile,  the  pcap_open_offline_with_tstamp_preci-
       sion(3PCAP)  and	 pcap_fopen_offline_with_tstamp_precision(3PCAP)  rou-
       tines  can  be used to specify the resolution of	time stamps to be read
       from the	file; if the time stamps in the	file have a lower  resolution,
       the  fraction-of-a-second  portion of the time stamps will be scaled to
       the specified resolution.

       The pcap_get_tstamp_precision(3PCAP) routine returns the	resolution  of
       time  stamps  that  will	be supplied; when capturing packets, this does
       not reflect the actual precision	of the	time  stamp  supplied  by  the
       hardware	 or  operating	system and, when reading a savefile, this does
       not indicate the	actual precision of time stamps	in the file.

SEE ALSO
       pcap_set_tstamp_type(3PCAP),		pcap_list_tstamp_types(3PCAP),
       pcap_tstamp_type_val_to_name(3PCAP),
       pcap_tstamp_type_name_to_val(3PCAP),  pcap_set_tstamp_precision(3PCAP),
       pcap_open_offline_with_tstamp_precision(3PCAP),	       pcap_fopen_off-
       line_with_tstamp_precision(3PCAP), pcap_get_tstamp_precision(3PCAP)

				 8 March 2015			PCAP-TSTAMP(7)

NAME | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pcap-tstamp&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help