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@ "8 March 2015"
  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 .LP
  63 In addition, packets time-stamped by different cores might be
  64 time-stamped in one order and added to the queue of packets for libpcap
  65 to read in another order, so time stamps might not be monotonically
  66 increasing.
  67 .LP
  68 Some capture devices on some platforms can provide time stamps for
  69 packets; those time stamps are usually high-resolution time stamps, and
  70 are usually applied to the packet when the first or last bit of the
  71 packet arrives, and are thus more accurate than time stamps provided by
  72 the host operating system.  Those time stamps might not, however, be
  73 synchronized with the host operating system's clock, so that, for
  74 example, the time stamp of a packet might not correspond to the time
  75 stamp of an event on the host triggered by the arrival of that packet.
  76 .LP
  77 Depending on the capture device and the software on the host, libpcap
  78 might allow different types of time stamp to be used.  The
  79 .BR pcap_list_tstamp_types (3PCAP)
  80 routine provides, for a packet capture handle created by
  81 .BR pcap_create (3PCAP)
  82 but not yet activated by
  83 .BR pcap_activate (3PCAP),
  84 a list of time stamp types supported by the capture device for that
  85 handle.
  86 The list might be empty, in which case no choice of time stamp type is
  87 offered for that capture device.  If the list is not empty, the
  88 .BR pcap_set_tstamp_type (3PCAP)
  89 routine can be used after a
  90 .BR pcap_create ()
  91 call and before a
  92 .BR pcap_activate ()
  93 call to specify the type of time stamp to be used on the device.
  94 The time stamp types are listed here; the first value is the #define to
  95 use in code, the second value is the value returned by
  96 .BR pcap_tstamp_type_val_to_name (3PCAP)
  97 and accepted by
  98 .BR pcap_tstamp_type_name_to_val (3PCAP) .
  99 .RS 5
 100 .TP 5
 101 .BR PCAP_TSTAMP_HOST " - " host
 102 Time stamp provided by the host on which the capture is being done.  The
 103 precision of this time stamp is unspecified; it might or might not be
 104 synchronized with the host operating system's clock.
 105 .TP 5
 106 .BR PCAP_TSTAMP_HOST_LOWPREC " - " host_lowprec
 107 Time stamp provided by the host on which the capture is being done.
 108 This is a low-precision time stamp, synchronized with the host operating
 109 system's clock.
 110 .TP 5
 111 .BR PCAP_TSTAMP_HOST_HIPREC " - " host_hiprec
 112 Time stamp provided by the host on which the capture is being done.
 113 This is a high-precision time stamp, synchronized with the host
 114 operating system's clock. It might be more expensive to fetch than
 115 .BR PCAP_TSTAMP_HOST_LOWPREC .
 116 .TP 5
 117 .BR PCAP_TSTAMP_HOST_HIPREC_UNSYNCED " - " host_hiprec_unsynced
 118 Time stamp provided by the host on which the capture is being done.
 119 This is a high-precision time stamp, not synchronized with the host
 120 operating system's clock. It might be more expensive to fetch than
 121 .BR PCAP_TSTAMP_HOST_LOWPREC .
 122 .TP 5
 123 .BR PCAP_TSTAMP_ADAPTER " - " adapter
 124 Time stamp provided by the network adapter on which the capture is being
 125 done.  This is a high-precision time stamp, synchronized with the host
 126 operating system's clock.
 127 .TP 5
 128 .BR PCAP_TSTAMP_ADAPTER_UNSYNCED " - " adapter_unsynced
 129 Time stamp provided by the network adapter on which the capture is being
 130 done.  This is a high-precision time stamp; it is not synchronized with
 131 the host operating system's clock.
 132 .RE
 133 .LP
 134 Time stamps synchronized with the system clock can go backwards, as the
 135 system clock can go backwards. If a clock is not in sync with the
 136 system clock, that could be because the system clock isn't keeping
 137 accurate time, because the other clock isn't keeping accurate time, or
 138 both.
 139 .LP
 140 Host-provided time stamps generally correspond to the time when the
 141 time-stamping code sees the packet; this could be some unknown amount of
 142 time after the first or last bit of the packet is received by the
 143 network adapter, due to batching of interrupts for packet arrival,
 144 queueing delays, etc..
 145 .LP
 146 By default, when performing a live capture or reading from a savefile,
 147 time stamps are supplied as seconds since January 1, 1970, 00:00:00 UTC,
 148 and microseconds since that seconds value, even if higher-resolution
 149 time stamps are available from the capture device or in the savefile.
 150 If, when reading a savefile, the time stamps in the file have a higher
 151 resolution than one microsecond, the additional digits of resolution are
 152 discarded.
 153 .LP
 154 The
 155 .BR pcap_set_tstamp_precision (3PCAP)
 156 routine can be used after a
 157 .BR pcap_create ()
 158 call and after a
 159 .BR pcap_activate ()
 160 call to specify the resolution of the time stamps to get for the device.
 161 If the hardware or software cannot supply a higher-resolution time
 162 stamp, the
 163 .BR pcap_set_tstamp_precision ()
 164 call will fail, and the time stamps supplied after the
 165 .BR pcap_activate ()
 166 call will have microsecond resolution.
 167 .LP
 168 When opening a savefile, the
 169 .BR \%pcap_open_offline_with_tstamp_precision (3PCAP)
 170 and
 171 .BR \%pcap_fopen_offline_with_tstamp_precision (3PCAP)
 172 routines can be used to specify the resolution of time stamps to be read
 173 from the file; if the time stamps in the file have a lower resolution,
 174 the fraction-of-a-second portion of the time stamps will be scaled to
 175 the specified resolution.
 176 .LP
 177 The
 178 .BR pcap_get_tstamp_precision (3PCAP)
 179 routine returns the resolution of time stamps that will be supplied;
 180 when capturing packets, this does not reflect the actual precision of
 181 the time stamp supplied by the hardware or operating system and, when
 182 reading a savefile, this does not indicate the actual precision of time
 183 stamps in the file.
 184 .SH SEE ALSO
 185 pcap(3PCAP)