|
Packit |
209cc3 |
.\"
|
|
Packit |
209cc3 |
.\" Copyright (c) 1987, 1988, 1989, 1990, 1991, 1992, 1994, 1995, 1996, 1997
|
|
Packit |
209cc3 |
.\" The Regents of the University of California. All rights reserved.
|
|
Packit |
209cc3 |
.\" All rights reserved.
|
|
Packit |
209cc3 |
.\"
|
|
Packit |
209cc3 |
.\" Redistribution and use in source and binary forms, with or without
|
|
Packit |
209cc3 |
.\" modification, are permitted provided that: (1) source code distributions
|
|
Packit |
209cc3 |
.\" retain the above copyright notice and this paragraph in its entirety, (2)
|
|
Packit |
209cc3 |
.\" distributions including binary code include the above copyright notice and
|
|
Packit |
209cc3 |
.\" this paragraph in its entirety in the documentation or other materials
|
|
Packit |
209cc3 |
.\" provided with the distribution, and (3) all advertising materials mentioning
|
|
Packit |
209cc3 |
.\" features or use of this software display the following acknowledgement:
|
|
Packit |
209cc3 |
.\" ``This product includes software developed by the University of California,
|
|
Packit |
209cc3 |
.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
|
|
Packit |
209cc3 |
.\" the University nor the names of its contributors may be used to endorse
|
|
Packit |
209cc3 |
.\" or promote products derived from this software without specific prior
|
|
Packit |
209cc3 |
.\" written permission.
|
|
Packit |
209cc3 |
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
|
|
Packit |
209cc3 |
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
|
Packit |
209cc3 |
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
|
Packit |
209cc3 |
.\"
|
|
Packit |
209cc3 |
.TH PCAP-TSTAMP @MAN_MISC_INFO@ "8 March 2015"
|
|
Packit |
209cc3 |
.SH NAME
|
|
Packit |
209cc3 |
pcap-tstamp \- packet time stamps in libpcap
|
|
Packit |
209cc3 |
.SH DESCRIPTION
|
|
Packit |
209cc3 |
When capturing traffic, each packet is given a time stamp representing,
|
|
Packit |
209cc3 |
for incoming packets, the arrival time of the packet and, for outgoing
|
|
Packit |
209cc3 |
packets, the transmission time of the packet. This time is an
|
|
Packit |
209cc3 |
approximation of the arrival or transmission time. If it is supplied by
|
|
Packit |
209cc3 |
the operating system running on the host on which the capture is being
|
|
Packit |
209cc3 |
done, there are several reasons why it might not precisely represent the
|
|
Packit |
209cc3 |
arrival or transmission time:
|
|
Packit |
209cc3 |
.IP
|
|
Packit |
209cc3 |
if the time stamp is applied to the packet when the networking stack
|
|
Packit |
209cc3 |
receives the packet, the networking stack might not see the packet until
|
|
Packit |
209cc3 |
an interrupt is delivered for the packet or a timer event causes the
|
|
Packit |
209cc3 |
networking device driver to poll for packets, and the time stamp might
|
|
Packit |
209cc3 |
not be applied until the packet has had some processing done by other
|
|
Packit |
209cc3 |
code in the networking stack, so there might be a significant delay
|
|
Packit |
209cc3 |
between the time when the last bit of the packet is received by the
|
|
Packit |
209cc3 |
capture device and when the networking stack time-stamps the packet;
|
|
Packit |
209cc3 |
.IP
|
|
Packit |
209cc3 |
the timer used to generate the time stamps might have low resolution,
|
|
Packit |
209cc3 |
for example, it might be a timer updated once per host operating system
|
|
Packit |
209cc3 |
timer tick, with the host operating system timer ticking once every few
|
|
Packit |
209cc3 |
milliseconds;
|
|
Packit |
209cc3 |
.IP
|
|
Packit |
209cc3 |
a high-resolution timer might use a counter that runs at a rate
|
|
Packit |
209cc3 |
dependent on the processor clock speed, and that clock speed might be
|
|
Packit |
209cc3 |
adjusted upwards or downwards over time and the timer might not be able
|
|
Packit |
209cc3 |
to compensate for all those adjustments;
|
|
Packit |
209cc3 |
.IP
|
|
Packit |
209cc3 |
the host operating system's clock might be adjusted over time to match a
|
|
Packit |
209cc3 |
time standard to which the host is being synchronized, which might be
|
|
Packit |
209cc3 |
done by temporarily slowing down or speeding up the clock or by making a
|
|
Packit |
209cc3 |
single adjustment;
|
|
Packit |
209cc3 |
.IP
|
|
Packit |
209cc3 |
different CPU cores on a multi-core or multi-processor system might be
|
|
Packit |
209cc3 |
running at different speeds, or might not have time counters all
|
|
Packit |
209cc3 |
synchronized, so packets time-stamped by different cores might not have
|
|
Packit |
209cc3 |
consistent time stamps.
|
|
Packit |
209cc3 |
.LP
|
|
Packit |
209cc3 |
In addition, packets time-stamped by different cores might be
|
|
Packit |
209cc3 |
time-stamped in one order and added to the queue of packets for libpcap
|
|
Packit |
209cc3 |
to read in another order, so time stamps might not be monotonically
|
|
Packit |
209cc3 |
increasing.
|
|
Packit |
209cc3 |
.LP
|
|
Packit |
209cc3 |
Some capture devices on some platforms can provide time stamps for
|
|
Packit |
209cc3 |
packets; those time stamps are usually high-resolution time stamps, and
|
|
Packit |
209cc3 |
are usually applied to the packet when the first or last bit of the
|
|
Packit |
209cc3 |
packet arrives, and are thus more accurate than time stamps provided by
|
|
Packit |
209cc3 |
the host operating system. Those time stamps might not, however, be
|
|
Packit |
209cc3 |
synchronized with the host operating system's clock, so that, for
|
|
Packit |
209cc3 |
example, the time stamp of a packet might not correspond to the time
|
|
Packit |
209cc3 |
stamp of an event on the host triggered by the arrival of that packet.
|
|
Packit |
209cc3 |
.LP
|
|
Packit |
209cc3 |
Depending on the capture device and the software on the host, libpcap
|
|
Packit |
209cc3 |
might allow different types of time stamp to be used. The
|
|
Packit |
209cc3 |
.BR pcap_list_tstamp_types (3PCAP)
|
|
Packit |
209cc3 |
routine provides, for a packet capture handle created by
|
|
Packit |
209cc3 |
.BR pcap_create (3PCAP)
|
|
Packit |
209cc3 |
but not yet activated by
|
|
Packit |
209cc3 |
.BR pcap_activate (3PCAP),
|
|
Packit |
209cc3 |
a list of time stamp types supported by the capture device for that
|
|
Packit |
209cc3 |
handle.
|
|
Packit |
209cc3 |
The list might be empty, in which case no choice of time stamp type is
|
|
Packit |
209cc3 |
offered for that capture device. If the list is not empty, the
|
|
Packit |
209cc3 |
.BR pcap_set_tstamp_type (3PCAP)
|
|
Packit |
209cc3 |
routine can be used after a
|
|
Packit |
209cc3 |
.B pcap_create()
|
|
Packit |
209cc3 |
call and before a
|
|
Packit |
209cc3 |
.B pcap_activate()
|
|
Packit |
209cc3 |
call to specify the type of time stamp to be used on the device.
|
|
Packit |
209cc3 |
The time stamp types are listed here; the first value is the #define to
|
|
Packit |
209cc3 |
use in code, the second value is the value returned by
|
|
Packit |
209cc3 |
.B pcap_tstamp_type_val_to_name(3PCAP)
|
|
Packit |
209cc3 |
and accepted by
|
|
Packit |
209cc3 |
.BR pcap_tstamp_type_name_to_val(3PCAP) .
|
|
Packit |
209cc3 |
.RS 5
|
|
Packit |
209cc3 |
.TP 5
|
|
Packit |
209cc3 |
.BR PCAP_TSTAMP_HOST " - " host
|
|
Packit |
209cc3 |
Time stamp provided by the host on which the capture is being done. The
|
|
Packit |
209cc3 |
precision of this time stamp is unspecified; it might or might not be
|
|
Packit |
209cc3 |
synchronized with the host operating system's clock.
|
|
Packit |
209cc3 |
.TP 5
|
|
Packit |
209cc3 |
.BR PCAP_TSTAMP_HOST_LOWPREC " - " host_lowprec
|
|
Packit |
209cc3 |
Time stamp provided by the host on which the capture is being done.
|
|
Packit |
209cc3 |
This is a low-precision time stamp, synchronized with the host operating
|
|
Packit |
209cc3 |
system's clock.
|
|
Packit |
209cc3 |
.TP 5
|
|
Packit |
209cc3 |
.BR PCAP_TSTAMP_HOST_HIPREC " - " host_hiprec
|
|
Packit |
209cc3 |
Time stamp provided by the host on which the capture is being done.
|
|
Packit |
209cc3 |
This is a high-precision time stamp; it might or might not be
|
|
Packit |
209cc3 |
synchronized with the host operating system's clock. It might be more
|
|
Packit |
209cc3 |
expensive to fetch than
|
|
Packit |
209cc3 |
.BR PCAP_TSTAMP_HOST_LOWPREC .
|
|
Packit |
209cc3 |
.TP 5
|
|
Packit |
209cc3 |
.BR PCAP_TSTAMP_ADAPTER " - " adapter
|
|
Packit |
209cc3 |
Time stamp provided by the network adapter on which the capture is being
|
|
Packit |
209cc3 |
done. This is a high-precision time stamp, synchronized with the host
|
|
Packit |
209cc3 |
operating system's clock.
|
|
Packit |
209cc3 |
.TP 5
|
|
Packit |
209cc3 |
.BR PCAP_TSTAMP_ADAPTER_UNSYNCED " - " adapter_unsynced
|
|
Packit |
209cc3 |
Time stamp provided by the network adapter on which the capture is being
|
|
Packit |
209cc3 |
done. This is a high-precision time stamp; it is not synchronized with
|
|
Packit |
209cc3 |
the host operating system's clock.
|
|
Packit |
209cc3 |
.RE
|
|
Packit |
209cc3 |
.LP
|
|
Packit |
209cc3 |
By default, when performing a live capture or reading from a savefile,
|
|
Packit |
209cc3 |
time stamps are supplied as seconds since January 1, 1970, 00:00:00 UTC,
|
|
Packit |
209cc3 |
and microseconds since that seconds value, even if higher-resolution
|
|
Packit |
209cc3 |
time stamps are available from the capture device or in the savefile.
|
|
Packit |
209cc3 |
If, when reading a savefile, the time stamps in the file have a higher
|
|
Packit |
209cc3 |
resolution than one microsecond, the additional digits of resolution are
|
|
Packit |
209cc3 |
discarded.
|
|
Packit |
209cc3 |
.LP
|
|
Packit |
209cc3 |
The
|
|
Packit |
209cc3 |
.BR pcap_set_tstamp_precision (3PCAP)
|
|
Packit |
209cc3 |
routine can be used after a
|
|
Packit |
209cc3 |
.B pcap_create()
|
|
Packit |
209cc3 |
call and after a
|
|
Packit |
209cc3 |
.B pcap_activate()
|
|
Packit |
209cc3 |
call to specify the resolution of the time stamps to get for the device.
|
|
Packit |
209cc3 |
If the hardware or software cannot supply a higher-resolution time
|
|
Packit |
209cc3 |
stamp, the
|
|
Packit |
209cc3 |
.B pcap_set_tstamp_precision()
|
|
Packit |
209cc3 |
call will fail, and the time stamps supplied after the
|
|
Packit |
209cc3 |
.B pcap_activate()
|
|
Packit |
209cc3 |
call will have microsecond resolution.
|
|
Packit |
209cc3 |
.LP
|
|
Packit |
209cc3 |
When opening a savefile, the
|
|
Packit |
209cc3 |
.BR \%pcap_open_offline_with_tstamp_precision (3PCAP)
|
|
Packit |
209cc3 |
and
|
|
Packit |
209cc3 |
.BR \%pcap_fopen_offline_with_tstamp_precision (3PCAP)
|
|
Packit |
209cc3 |
routines can be used to specify the resolution of time stamps to be read
|
|
Packit |
209cc3 |
from the file; if the time stamps in the file have a lower resolution,
|
|
Packit |
209cc3 |
the fraction-of-a-second portion of the time stamps will be scaled to
|
|
Packit |
209cc3 |
the specified resolution.
|
|
Packit |
209cc3 |
.LP
|
|
Packit |
209cc3 |
The
|
|
Packit |
209cc3 |
.BR pcap_get_tstamp_precision (3PCAP)
|
|
Packit |
209cc3 |
routine returns the resolution of time stamps that will be supplied;
|
|
Packit |
209cc3 |
when capturing packets, this does not reflect the actual precision of
|
|
Packit |
209cc3 |
the time stamp supplied by the hardware or operating system and, when
|
|
Packit |
209cc3 |
reading a savefile, this does not indicate the actual precision of time
|
|
Packit |
209cc3 |
stamps in the file.
|
|
Packit |
209cc3 |
.SH SEE ALSO
|
|
Packit |
209cc3 |
pcap(3PCAP)
|