The Tcpdump Group git mirrors - libpcap/blob - 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@ "1 October 2024"
  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
 111 .B #define
 112 to use in code, the second value is the value returned by
 113 .BR pcap_tstamp_type_val_to_name (3PCAP)
 114 and accepted by
 115 .BR pcap_tstamp_type_name_to_val (3PCAP).
 116 .RS 5
 117 .TP 5
 118 .BR PCAP_TSTAMP_HOST " - " host
 119 Time stamp provided by the host on which the capture is being done.  The
 120 precision of this time stamp is unspecified; it might or might not be
 121 synchronized with the host operating system's clock.
 122 .TP 5
 123 .BR PCAP_TSTAMP_HOST_LOWPREC " - " host_lowprec
 124 Time stamp provided by the host on which the capture is being done.
 125 This is a low-precision time stamp, synchronized with the host operating
 126 system's clock.
 127 .TP 5
 128 .BR PCAP_TSTAMP_HOST_HIPREC " - " host_hiprec
 129 Time stamp provided by the host on which the capture is being done.
 130 This is a high-precision time stamp, synchronized with the host
 131 operating system's clock. It might be more expensive to fetch than
 132 .BR PCAP_TSTAMP_HOST_LOWPREC .
 133 .TP 5
 134 .BR PCAP_TSTAMP_HOST_HIPREC_UNSYNCED " - " host_hiprec_unsynced
 135 Time stamp provided by the host on which the capture is being done.
 136 This is a high-precision time stamp, not synchronized with the host
 137 operating system's clock. It might be more expensive to fetch than
 138 .BR PCAP_TSTAMP_HOST_LOWPREC .
 139 .TP 5
 140 .BR PCAP_TSTAMP_ADAPTER " - " adapter
 141 Time stamp provided by the network adapter on which the capture is being
 142 done.  This is a high-precision time stamp, synchronized with the host
 143 operating system's clock.
 144 .TP 5
 145 .BR PCAP_TSTAMP_ADAPTER_UNSYNCED " - " adapter_unsynced
 146 Time stamp provided by the network adapter on which the capture is being
 147 done.  This is a high-precision time stamp; it is not synchronized with
 148 the host operating system's clock.
 149 .RE
 150 .LP
 151 Time stamps synchronized with the system clock can go backwards, as the
 152 system clock can go backwards. If a clock is not in sync with the
 153 system clock, that could be because the system clock isn't keeping
 154 accurate time, because the other clock isn't keeping accurate time, or
 155 both.
 156 .LP
 157 Host-provided time stamps generally correspond to the time when the
 158 time-stamping code sees the packet; this could be some unknown amount of
 159 time after the first or last bit of the packet is received by the
 160 network adapter, due to batching of interrupts for packet arrival,
 161 queueing delays, etc..
 162 .LP
 163 By default, when performing a live capture or reading from a savefile,
 164 time stamps are supplied as seconds since January 1, 1970, 00:00:00 UTC,
 165 and microseconds since that seconds value, even if higher-resolution
 166 time stamps are available from the capture device or in the savefile.
 167 If, when reading a savefile, the time stamps in the file have a higher
 168 resolution than one microsecond, the additional digits of resolution are
 169 discarded.
 170 .LP
 171 The
 172 .BR pcap_set_tstamp_precision (3PCAP)
 173 routine can be used after a
 174 .BR pcap_create ()
 175 call and before a
 176 .BR pcap_activate ()
 177 call to specify the resolution of the time stamps to get for the device.
 178 If the hardware or software cannot supply a higher-resolution time
 179 stamp, the
 180 .BR pcap_set_tstamp_precision ()
 181 call will fail, and the time stamps supplied after the
 182 .BR pcap_activate ()
 183 call will have microsecond resolution.
 184 .LP
 185 When opening a savefile, the
 186 .BR \%pcap_open_offline_with_tstamp_precision (3PCAP)
 187 and
 188 .BR \%pcap_fopen_offline_with_tstamp_precision (3PCAP)
 189 routines can be used to specify the resolution of time stamps to be read
 190 from the file; if the time stamps in the file have a lower resolution,
 191 the fraction-of-a-second portion of the time stamps will be scaled to
 192 the specified resolution.
 193 .LP
 194 The
 195 .BR pcap_get_tstamp_precision (3PCAP)
 196 routine returns the resolution of time stamps that will be supplied;
 197 when capturing packets, this does not reflect the actual precision of
 198 the time stamp supplied by the hardware or operating system and, when
 199 reading a savefile, this does not indicate the actual precision of time
 200 stamps in the file.
 201 .SH SEE ALSO
 202 .BR pcap (3PCAP)