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@ "22 August 2010"
  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 .B pcap_create()
  91 call and before a
  92 .B 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 .B pcap_tstamp_type_val_to_name()
  97 and accepted by
  98 .BR pcap_tstamp_name_to_val() .
  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; it might or might not be
 114 synchronized with the host operating system's clock.  It might be more
 115 expensive to fetch than
 116 .BR PCAP_TSTAMP_HOST_LOWPREC .
 117 .TP 5
 118 .BR PCAP_TSTAMP_ADAPTER " - " adapter
 119 Time stamp provided by the network adapter on which the capture is being
 120 done.  This is a high-precision time stamp, synchronized with the host
 121 operating system's clock.
 122 .TP 5
 123 .BR PCAP_TSTAMP_ADAPTER_UNSYNCED " - " adapter_unsynced
 124 Time stamp provided by the network adapter on which the capture is being
 125 done.  This is a high-precision time stamp; it is not synchronized with
 126 the host operating system's clock.
 127 .RE
 128 .SH SEE ALSO
 129 pcap_set_tstamp_type(3PCAP),
 130 pcap_list_tstamp_types(3PCAP),
 131 pcap_tstamp_type_val_to_name(3PCAP),
 132 pcap_tstamp_name_to_val(3PCAP)