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()  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 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_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_offline_with_tstamp_precision(3PCAP),  pcap_get_tstamp_precision(3PCAP)

                                           8 March 2015                            PCAP-TSTAMP(7)