contrib/libpcap/pcap-tstamp.manmisc.in

   1 .\"
   2 .\" Copyright (c) 1987, 1988, 1989, 1990, 1991, 1992, 1994, 1995, 1996, 1997
   3 .\"     The Regents of the University of California.  All rights reserved.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that: (1) source code distributions
   8 .\" retain the above copyright notice and this paragraph in its entirety, (2)
   9 .\" distributions including binary code include the above copyright notice and
  10 .\" this paragraph in its entirety in the documentation or other materials
  11 .\" provided with the distribution, and (3) all advertising materials mentioning
  12 .\" features or use of this software display the following acknowledgement:
  13 .\" ``This product includes software developed by the University of California,
  14 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
  15 .\" the University nor the names of its contributors may be used to endorse
  16 .\" or promote products derived from this software without specific prior
  17 .\" written permission.
  18 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  19 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  20 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  21 .\"
  22 .TH PCAP-TSTAMP @MAN_MISC_INFO@ "14 July 2020"
  23 .SH NAME
  24 pcap-tstamp \- packet time stamps in libpcap
  25 .SH DESCRIPTION
  26 When capturing traffic, each packet is given a time stamp representing,
  27 for incoming packets, the arrival time of the packet and, for outgoing
  28 packets, the transmission time of the packet.  This time is an
  29 approximation of the arrival or transmission time.  If it is supplied by
  30 the operating system running on the host on which the capture is being
  31 done, there are several reasons why it might not precisely represent the
  32 arrival or transmission time:
  33 .IP
  34 if the time stamp is applied to the packet when the networking stack
  35 receives the packet, the networking stack might not see the packet until
  36 an interrupt is delivered for the packet or a timer event causes the
  37 networking device driver to poll for packets, and the time stamp might
  38 not be applied until the packet has had some processing done by other
  39 code in the networking stack, so there might be a significant delay
  40 between the time when the last bit of the packet is received by the
  41 capture device and when the networking stack time-stamps the packet;
  42 .IP
  43 the timer used to generate the time stamps might have low resolution,
  44 for example, it might be a timer updated once per host operating system
  45 timer tick, with the host operating system timer ticking once every few
  46 milliseconds;
  47 .IP
  48 a high-resolution timer might use a counter that runs at a rate
  49 dependent on the processor clock speed, and that clock speed might be
  50 adjusted upwards or downwards over time and the timer might not be able
  51 to compensate for all those adjustments;
  52 .IP
  53 the host operating system's clock might be adjusted over time to match a
  54 time standard to which the host is being synchronized, which might be
  55 done by temporarily slowing down or speeding up the clock or by making a
  56 single adjustment;
  57 .IP
  58 different CPU cores on a multi-core or multi-processor system might be
  59 running at different speeds, or might not have time counters all
  60 synchronized, so packets time-stamped by different cores might not have
  61 consistent time stamps;
  62 .IP
  63 some time sources, such as those that supply POSIX "seconds since the
  64 Epoch" time, do not count leap seconds, meaning that the seconds
  65 portion
  66 .RB ( tv_sec )
  67 of the time stamp might not be incremented for a leap second, so that
  68 the fraction-of-a-second part of the time stamp might roll over past
  69 zero but the second part would not change, or the clock might run
  70 slightly more slowly for a period before the leap second.
  71 .LP
  72 For these reasons, time differences between packet time stamps will not
  73 necessarily accurately reflect the time differences between the receipt
  74 or transmission times of the packets.
  75 .LP
  76 In addition, packets time-stamped by different cores might be
  77 time-stamped in one order and added to the queue of packets for libpcap
  78 to read in another order, so time stamps might not be monotonically
  79 increasing.
  80 .LP
  81 Some capture devices on some platforms can provide time stamps for
  82 packets; those time stamps are usually high-resolution time stamps, and
  83 are usually applied to the packet when the first or last bit of the
  84 packet arrives, and are thus more accurate than time stamps provided by
  85 the host operating system.  Those time stamps might not, however, be
  86 synchronized with the host operating system's clock, so that, for
  87 example, the time stamp of a packet might not correspond to the time
  88 stamp of an event on the host triggered by the arrival of that packet.
  89 If they are synchronized with the host operating system's clock, some of
  90 the issues listed above with time stamps supplied by the host operating
  91 system may also apply to time stamps supplied by the capture device.
  92 .LP
  93 Depending on the capture device and the software on the host, libpcap
  94 might allow different types of time stamp to be used.  The
  95 .BR pcap_list_tstamp_types (3PCAP)
  96 routine provides, for a packet capture handle created by
  97 .BR pcap_create (3PCAP)
  98 but not yet activated by
  99 .BR pcap_activate (3PCAP),
 100 a list of time stamp types supported by the capture device for that
 101 handle.
 102 The list might be empty, in which case no choice of time stamp type is
 103 offered for that capture device.  If the list is not empty, the
 104 .BR pcap_set_tstamp_type (3PCAP)
 105 routine can be used after a
 106 .BR pcap_create ()
 107 call and before a
 108 .BR pcap_activate ()
 109 call to specify the type of time stamp to be used on the device.
 110 The time stamp types are listed here; the first value is the #define to
 111 use in code, the second value is the value returned by
 112 .BR pcap_tstamp_type_val_to_name (3PCAP)
 113 and accepted by
 114 .BR pcap_tstamp_type_name_to_val (3PCAP) .
 115 .RS 5
 116 .TP 5
 117 .BR PCAP_TSTAMP_HOST " - " host
 118 Time stamp provided by the host on which the capture is being done.  The
 119 precision of this time stamp is unspecified; it might or might not be
 120 synchronized with the host operating system's clock.
 121 .TP 5
 122 .BR PCAP_TSTAMP_HOST_LOWPREC " - " host_lowprec
 123 Time stamp provided by the host on which the capture is being done.
 124 This is a low-precision time stamp, synchronized with the host operating
 125 system's clock.
 126 .TP 5
 127 .BR PCAP_TSTAMP_HOST_HIPREC " - " host_hiprec
 128 Time stamp provided by the host on which the capture is being done.
 129 This is a high-precision time stamp, synchronized with the host
 130 operating system's clock. It might be more expensive to fetch than
 131 .BR PCAP_TSTAMP_HOST_LOWPREC .
 132 .TP 5
 133 .BR PCAP_TSTAMP_HOST_HIPREC_UNSYNCED " - " host_hiprec_unsynced
 134 Time stamp provided by the host on which the capture is being done.
 135 This is a high-precision time stamp, not synchronized with the host
 136 operating system's clock. It might be more expensive to fetch than
 137 .BR PCAP_TSTAMP_HOST_LOWPREC .
 138 .TP 5
 139 .BR PCAP_TSTAMP_ADAPTER " - " adapter
 140 Time stamp provided by the network adapter on which the capture is being
 141 done.  This is a high-precision time stamp, synchronized with the host
 142 operating system's clock.
 143 .TP 5
 144 .BR PCAP_TSTAMP_ADAPTER_UNSYNCED " - " adapter_unsynced
 145 Time stamp provided by the network adapter on which the capture is being
 146 done.  This is a high-precision time stamp; it is not synchronized with
 147 the host operating system's clock.
 148 .RE
 149 .LP
 150 Time stamps synchronized with the system clock can go backwards, as the
 151 system clock can go backwards. If a clock is not in sync with the
 152 system clock, that could be because the system clock isn't keeping
 153 accurate time, because the other clock isn't keeping accurate time, or
 154 both.
 155 .LP
 156 Host-provided time stamps generally correspond to the time when the
 157 time-stamping code sees the packet; this could be some unknown amount of
 158 time after the first or last bit of the packet is received by the
 159 network adapter, due to batching of interrupts for packet arrival,
 160 queueing delays, etc..
 161 .LP
 162 By default, when performing a live capture or reading from a savefile,
 163 time stamps are supplied as seconds since January 1, 1970, 00:00:00 UTC,
 164 and microseconds since that seconds value, even if higher-resolution
 165 time stamps are available from the capture device or in the savefile.
 166 If, when reading a savefile, the time stamps in the file have a higher
 167 resolution than one microsecond, the additional digits of resolution are
 168 discarded.
 169 .LP
 170 The
 171 .BR pcap_set_tstamp_precision (3PCAP)
 172 routine can be used after a
 173 .BR pcap_create ()
 174 call and after a
 175 .BR pcap_activate ()
 176 call to specify the resolution of the time stamps to get for the device.
 177 If the hardware or software cannot supply a higher-resolution time
 178 stamp, the
 179 .BR pcap_set_tstamp_precision ()
 180 call will fail, and the time stamps supplied after the
 181 .BR pcap_activate ()
 182 call will have microsecond resolution.
 183 .LP
 184 When opening a savefile, the
 185 .BR \%pcap_open_offline_with_tstamp_precision (3PCAP)
 186 and
 187 .BR \%pcap_fopen_offline_with_tstamp_precision (3PCAP)
 188 routines can be used to specify the resolution of time stamps to be read
 189 from the file; if the time stamps in the file have a lower resolution,
 190 the fraction-of-a-second portion of the time stamps will be scaled to
 191 the specified resolution.
 192 .LP
 193 The
 194 .BR pcap_get_tstamp_precision (3PCAP)
 195 routine returns the resolution of time stamps that will be supplied;
 196 when capturing packets, this does not reflect the actual precision of
 197 the time stamp supplied by the hardware or operating system and, when
 198 reading a savefile, this does not indicate the actual precision of time
 199 stamps in the file.
 200 .SH SEE ALSO
 201 .BR pcap (3PCAP)