1PCAP-TSTAMP(7)         Miscellaneous Information Manual         PCAP-TSTAMP(7)
2
3
4

NAME

6       pcap-tstamp - packet time stamps in libpcap
7

DESCRIPTION

9       When capturing traffic, each packet is given a time stamp representing,
10       for incoming packets, the arrival time of the packet and, for  outgoing
11       packets, the transmission time of the packet.  This time is an approxi‐
12       mation of the arrival or transmission time.  If it is supplied  by  the
13       operating  system  running  on  the  host on which the capture is being
14       done, there are several reasons why it might  not  precisely  represent
15       the arrival or transmission time:
16
17              if  the  time stamp is applied to the packet when the networking
18              stack receives the packet, the networking stack  might  not  see
19              the  packet  until an interrupt is delivered for the packet or a
20              timer event causes the networking  device  driver  to  poll  for
21              packets,  and  the  time  stamp  might  not be applied until the
22              packet has had some processing done by other code  in  the  net‐
23              working stack, so there might be a significant delay between the
24              time when the last bit of the packet is received by the  capture
25              device and when the networking stack time-stamps the packet;
26
27              the  timer used to generate the time stamps might have low reso‐
28              lution, for example, it might be a timer updated once  per  host
29              operating  system  timer  tick,  with  the host operating system
30              timer ticking once every few milliseconds;
31
32              a high-resolution timer might use a counter that runs at a  rate
33              dependent  on  the  processor  clock speed, and that clock speed
34              might be adjusted upwards or downwards over time and  the  timer
35              might not be able to compensate for all those adjustments;
36
37              the host operating system's clock might be adjusted over time to
38              match a time standard to which the host is  being  synchronized,
39              which  might  be done by temporarily slowing down or speeding up
40              the clock or by making a single adjustment;
41
42              different CPU cores on a multi-core  or  multi-processor  system
43              might  be  running  at  different speeds, or might not have time
44              counters all synchronized, so packets time-stamped by  different
45              cores might not have consistent time stamps;
46
47              some  time  sources,  such  as  those that supply POSIX "seconds
48              since the Epoch" time, do not count leap seconds,  meaning  that
49              the  seconds  portion  (tv_sec)  of  the time stamp might not be
50              incremented for a leap second, so that the  fraction-of-a-second
51              part  of the time stamp might roll over past zero but the second
52              part would not change, or the  clock  might  run  slightly  more
53              slowly for a period before the leap second.
54
55       For these reasons, time differences between packet time stamps will not
56       necessarily accurately reflect the time differences between the receipt
57       or transmission times of the packets.
58
59       In  addition,  packets  time-stamped  by different cores might be time-
60       stamped in one order and added to the queue of packets for  libpcap  to
61       read  in  another  order,  so  time  stamps  might not be monotonically
62       increasing.
63
64       Some capture devices on some platforms  can  provide  time  stamps  for
65       packets; those time stamps are usually high-resolution time stamps, and
66       are usually applied to the packet when the first or  last  bit  of  the
67       packet arrives, and are thus more accurate than time stamps provided by
68       the host operating system.  Those time stamps might  not,  however,  be
69       synchronized with the host operating system's clock, so that, for exam‐
70       ple, the time stamp of a packet might not correspond to the time  stamp
71       of  an  event  on the host triggered by the arrival of that packet.  If
72       they are synchronized with the host operating system's clock,  some  of
73       the issues listed above with time stamps supplied by the host operating
74       system may also apply to time stamps supplied by the capture device.
75
76       Depending on the capture device and the software on the  host,  libpcap
77       might   allow   different   types  of  time  stamp  to  be  used.   The
78       pcap_list_tstamp_types(3PCAP) routine provides, for  a  packet  capture
79       handle   created   by  pcap_create(3PCAP)  but  not  yet  activated  by
80       pcap_activate(3PCAP), a list of time stamp types supported by the  cap‐
81       ture device for that handle.  The list might be empty, in which case no
82       choice of time stamp type is offered for that capture device.   If  the
83       list  is not empty, the pcap_set_tstamp_type(3PCAP) routine can be used
84       after a pcap_create() call and before a pcap_activate() call to specify
85       the  type of time stamp to be used on the device.  The time stamp types
86       are listed here; the first value is the #define to  use  in  code,  the
87       second       value       is       the       value      returned      by
88       pcap_tstamp_type_val_to_name(3PCAP)       and        accepted        by
89       pcap_tstamp_type_name_to_val(3PCAP).
90
91            PCAP_TSTAMP_HOST - host
92                 Time stamp provided by the host on which the capture is being
93                 done.  The precision of this time stamp  is  unspecified;  it
94                 might  or  might  not be synchronized with the host operating
95                 system's clock.
96
97            PCAP_TSTAMP_HOST_LOWPREC - host_lowprec
98                 Time stamp provided by the host on which the capture is being
99                 done.   This is a low-precision time stamp, synchronized with
100                 the host operating system's clock.
101
102            PCAP_TSTAMP_HOST_HIPREC - host_hiprec
103                 Time stamp provided by the host on which the capture is being
104                 done.  This is a high-precision time stamp, synchronized with
105                 the host operating system's clock. It might be more expensive
106                 to fetch than PCAP_TSTAMP_HOST_LOWPREC.
107
108            PCAP_TSTAMP_HOST_HIPREC_UNSYNCED - host_hiprec_unsynced
109                 Time stamp provided by the host on which the capture is being
110                 done.  This is a high-precision time stamp, not  synchronized
111                 with  the  host  operating  system's  clock. It might be more
112                 expensive to fetch than PCAP_TSTAMP_HOST_LOWPREC.
113
114            PCAP_TSTAMP_ADAPTER - adapter
115                 Time stamp provided by the network adapter on which the  cap‐
116                 ture  is  being  done.   This is a high-precision time stamp,
117                 synchronized with the host operating system's clock.
118
119            PCAP_TSTAMP_ADAPTER_UNSYNCED - adapter_unsynced
120                 Time stamp provided by the network adapter on which the  cap‐
121                 ture  is being done.  This is a high-precision time stamp; it
122                 is not synchronized with the host operating system's clock.
123
124       Time stamps synchronized with the system clock can go backwards, as the
125       system  clock can go backwards. If a clock is not in sync with the sys‐
126       tem clock, that could be because the system clock isn't  keeping  accu‐
127       rate  time,  because  the  other  clock isn't keeping accurate time, or
128       both.
129
130       Host-provided time stamps generally correspond to  the  time  when  the
131       time-stamping  code  sees the packet; this could be some unknown amount
132       of time after the first or last bit of the packet is  received  by  the
133       network  adapter,  due  to  batching  of interrupts for packet arrival,
134       queueing delays, etc..
135
136       By default, when performing a live capture or reading from a  savefile,
137       time  stamps  are  supplied  as seconds since January 1, 1970, 00:00:00
138       UTC, and microseconds since that seconds value, even if  higher-resolu‐
139       tion  time stamps are available from the capture device or in the save‐
140       file.  If, when reading a savefile, the time stamps in the file have  a
141       higher  resolution than one microsecond, the additional digits of reso‐
142       lution are discarded.
143
144       The  pcap_set_tstamp_precision(3PCAP)  routine  can  be  used  after  a
145       pcap_create() call and after a pcap_activate() call to specify the res‐
146       olution of the time stamps to get for the device.  If the  hardware  or
147       software   cannot   supply   a   higher-resolution   time   stamp,  the
148       pcap_set_tstamp_precision() call will fail, and the  time  stamps  sup‐
149       plied after the pcap_activate() call will have microsecond resolution.
150
151       When            opening            a            savefile,           the
152       pcap_open_offline_with_tstamp_precision(3PCAP)                      and
153       pcap_fopen_offline_with_tstamp_precision(3PCAP) routines can be used to
154       specify the resolution of time stamps to be read from the file; if  the
155       time stamps in the file have a lower resolution, the fraction-of-a-sec‐
156       ond portion of the time stamps will be scaled to the specified  resolu‐
157       tion.
158
159       The  pcap_get_tstamp_precision(3PCAP) routine returns the resolution of
160       time stamps that will be supplied; when capturing  packets,  this  does
161       not  reflect  the  actual  precision  of the time stamp supplied by the
162       hardware or operating system and, when reading a  savefile,  this  does
163       not indicate the actual precision of time stamps in the file.
164

SEE ALSO

166       pcap(3PCAP)
167
168
169
170                                 14 July 2020                   PCAP-TSTAMP(7)
Impressum