Elliott Hughes | 965a4b5 | 2017-05-15 10:37:39 -0700 | [diff] [blame] | 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 7 "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 | .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_type_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 | .LP |
| 129 | By default, when performing a live capture or reading from a savefile, |
| 130 | time stamps are supplied as seconds since January 1, 1970, 00:00:00 UTC, |
| 131 | and microseconds since that seconds value, even if higher-resolution |
| 132 | time stamps are available from the capture device or in the savefile. |
| 133 | If, when reading a savefile, the time stamps in the file have a higher |
| 134 | resolution than one microsecond, the additional digits of resolution are |
| 135 | discarded. |
| 136 | .LP |
| 137 | The |
| 138 | .BR pcap_set_tstamp_precision (3PCAP) |
| 139 | routine can be used after a |
| 140 | .B pcap_create() |
| 141 | call and after a |
| 142 | .B pcap_activate() |
| 143 | call to specify the resolution of the time stamps to get for the device. |
| 144 | If the hardware or software cannot supply a higher-resolution time |
| 145 | stamp, the |
| 146 | .B pcap_set_tstamp_precision() |
| 147 | call will fail, and the time stamps supplied after the |
| 148 | .B pcap_activate() |
| 149 | call will have microsecond resolution. |
| 150 | .LP |
| 151 | When opening a savefile, the |
| 152 | .BR pcap_open_offline_with_tstamp_precision (3PCAP) |
| 153 | and |
| 154 | .BR pcap_fopen_offline_with_tstamp_precision (3PCAP) |
| 155 | routines can be used to specify the resolution of time stamps to be read |
| 156 | from the file; if the time stamps in the file have a lower resolution, |
| 157 | the fraction-of-a-second portion of the time stamps will be scaled to |
| 158 | the specified resolution. |
| 159 | .LP |
| 160 | The |
| 161 | .BR pcap_get_tstamp_precision (3PCAP) |
| 162 | routine returns the resolution of time stamps that will be supplied; |
| 163 | when capturing packets, this does not reflect the actual precision of |
| 164 | the time stamp supplied by the hardware or operating system and, when |
| 165 | reading a savefile, this does not indicate the actual precision of time |
| 166 | stamps in the file. |
| 167 | .SH SEE ALSO |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 168 | .na |
Elliott Hughes | 965a4b5 | 2017-05-15 10:37:39 -0700 | [diff] [blame] | 169 | pcap_set_tstamp_type(3PCAP), |
| 170 | pcap_list_tstamp_types(3PCAP), |
| 171 | pcap_tstamp_type_val_to_name(3PCAP), |
| 172 | pcap_tstamp_type_name_to_val(3PCAP), |
| 173 | pcap_set_tstamp_precision(3PCAP), |
| 174 | pcap_open_offline_with_tstamp_precision(3PCAP), |
Haibo Huang | 165065a | 2018-07-23 17:26:52 -0700 | [diff] [blame] | 175 | \%pcap_fopen_offline_with_tstamp_precision(3PCAP), |
| 176 | \%pcap_get_tstamp_precision(3PCAP) |
| 177 | .ad |