pcap-tstamp

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
       approximation 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 networking 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
              resolution, 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
       example, 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 capture
       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(3PCAP) and accepted by
       pcap_tstamp_type_name_to_val(3PCAP).

            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 capture
                 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 capture
                 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-resolution time
       stamps are available from the capture device or in the savefile.  If,
       when reading a savefile, the time stamps in the file have a higher
       resolution than one microsecond, the additional digits of resolution 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
       resolution 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 supplied
       after the pcap_activate() call will have microsecond resolution.

       When opening a savefile, the
       pcap_open_offline_with_tstamp_precision(3PCAP) and
       pcap_fopen_offline_with_tstamp_precision(3PCAP) routines 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(3PCAP)



                                  8 March 2015                    PCAP-TSTAMP(7)