Add support for setting the time stamp type for a capture.
Based on a patch from Scott Mcmillan <scott.a.mcmillan@intel.com>.
This commit is contained in:
parent
0ba94d1cfa
commit
951f99bbbd
|
@ -0,0 +1,126 @@
|
||||||
|
.\"
|
||||||
|
.\" Copyright (c) 1987, 1988, 1989, 1990, 1991, 1992, 1994, 1995, 1996, 1997
|
||||||
|
.\" The Regents of the University of California. All rights reserved.
|
||||||
|
.\" All rights reserved.
|
||||||
|
.\"
|
||||||
|
.\" Redistribution and use in source and binary forms, with or without
|
||||||
|
.\" modification, are permitted provided that: (1) source code distributions
|
||||||
|
.\" retain the above copyright notice and this paragraph in its entirety, (2)
|
||||||
|
.\" distributions including binary code include the above copyright notice and
|
||||||
|
.\" this paragraph in its entirety in the documentation or other materials
|
||||||
|
.\" provided with the distribution, and (3) all advertising materials mentioning
|
||||||
|
.\" features or use of this software display the following acknowledgement:
|
||||||
|
.\" ``This product includes software developed by the University of California,
|
||||||
|
.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
|
||||||
|
.\" the University nor the names of its contributors may be used to endorse
|
||||||
|
.\" or promote products derived from this software without specific prior
|
||||||
|
.\" written permission.
|
||||||
|
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
|
||||||
|
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
||||||
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
.\"
|
||||||
|
.TH PCAP-TSTAMP @MAN_MISC_INFO@ "22 August 2010"
|
||||||
|
.SH NAME
|
||||||
|
pcap-tstamp \- packet time stamps in libpcap
|
||||||
|
.SH DESCRIPTION
|
||||||
|
When capturing traffic, each packet is given a time stamp representing,
|
||||||
|
for incoming packets, the arrival time of the packet and, for outgoing
|
||||||
|
packets, the transmission time of the packet. This time is an
|
||||||
|
approximation of the arrival or transmission time. If it is supplied by
|
||||||
|
the operating system running on the host on which the capture is being
|
||||||
|
done, there are several reasons why it might not precisely represent the
|
||||||
|
arrival or transmission time:
|
||||||
|
.IP
|
||||||
|
if the time stamp is applied to the packet when the networking stack
|
||||||
|
receives the packet, the networking stack might not see the packet until
|
||||||
|
an interrupt is delivered for the packet or a timer event causes the
|
||||||
|
networking device driver to poll for packets, and the time stamp might
|
||||||
|
not be applied until the packet has had some processing done by other
|
||||||
|
code in the networking stack, so there might be a significant delay
|
||||||
|
between the time when the last bit of the packet is received by the
|
||||||
|
capture device and when the networking stack time-stamps the packet;
|
||||||
|
.IP
|
||||||
|
the timer used to generate the time stamps might have low resolution,
|
||||||
|
for example, it might be a timer updated once per host operating system
|
||||||
|
timer tick, with the host operating system timer ticking once every few
|
||||||
|
milliseconds;
|
||||||
|
.IP
|
||||||
|
a high-resolution timer might use a counter that runs at a rate
|
||||||
|
dependent on the processor clock speed, and that clock speed might be
|
||||||
|
adjusted upwards or downwards over time and the timer might not be able
|
||||||
|
to compensate for all those adjustments;
|
||||||
|
.IP
|
||||||
|
the host operating system's clock might be adjusted over time to match a
|
||||||
|
time standard to which the host is being synchronized, which might be
|
||||||
|
done by temporarily slowing down or speeding up the clock or by making a
|
||||||
|
single adjustment;
|
||||||
|
.IP
|
||||||
|
different CPU cores on a multi-core or multi-processor system might be
|
||||||
|
running at different speeds, or might not have time counters all
|
||||||
|
synchronized, so packets time-stamped by different cores might not have
|
||||||
|
consistent time stamps.
|
||||||
|
.LP
|
||||||
|
In addition, packets time-stamped by different cores might be
|
||||||
|
time-stamped in one order and added to the queue of packets for libpcap
|
||||||
|
to read in another order, so time stamps might not be monotonically
|
||||||
|
increasing.
|
||||||
|
.LP
|
||||||
|
Some capture devices on some platforms can provide time stamps for
|
||||||
|
packets; those time stamps are usually high-resolution time stamps, and
|
||||||
|
are usually applied to the packet when the first or last bit of the
|
||||||
|
packet arrives, and are thus more accurate than time stamps provided by
|
||||||
|
the host operating system. Those time stamps might not, however, be
|
||||||
|
synchronized with the host operating system's clock, so that, for
|
||||||
|
example, the time stamp of a packet might not correspond to the time
|
||||||
|
stamp of an event on the host triggered by the arrival of that packet.
|
||||||
|
.LP
|
||||||
|
Depending on the capture device and the software on the host, libpcap
|
||||||
|
might allow different types of time stamp to be used. The
|
||||||
|
.BR pcap_list_tstamp_types (3PCAP)
|
||||||
|
routine provides, for a packet capture handle created by
|
||||||
|
.BR pcap_create (3PCAP)
|
||||||
|
but not yet activated by
|
||||||
|
.BR pcap_activate (3PCAP),
|
||||||
|
a list of time stamp types supported by the capture device for that
|
||||||
|
handle.
|
||||||
|
The list might be empty, in which case no choice of time stamp type is
|
||||||
|
offered for that capture device. If the list is not empty, the
|
||||||
|
.BR pcap_set_tstamp_type (3PCAP)
|
||||||
|
routine can be used after a
|
||||||
|
.B pcap_create()
|
||||||
|
call and before a
|
||||||
|
.B pcap_activate()
|
||||||
|
call to specify the type of time stamp to be used on the device.
|
||||||
|
The time stamp types are:
|
||||||
|
.RS 5
|
||||||
|
.TP 5
|
||||||
|
.BR PCAP_TSTAMP_HOST
|
||||||
|
Time stamp provided by the host on which the capture is being done. The
|
||||||
|
precision of this time stamp is unspecified; it might or might not be
|
||||||
|
synchronized with the host operating system's clock.
|
||||||
|
.TP 5
|
||||||
|
.BR PCAP_TSTAMP_HOST_LOWPREC
|
||||||
|
Time stamp provided by the host on which the capture is being done.
|
||||||
|
This is a low-precision time stamp, synchronized with the host operating
|
||||||
|
system's clock.
|
||||||
|
.TP 5
|
||||||
|
.BR PCAP_TSTAMP_HOST_HIPREC
|
||||||
|
Time stamp provided by the host on which the capture is being done.
|
||||||
|
This is a high-precision time stamp; it might or might not be
|
||||||
|
synchronized with the host operating system's clock. It might be more
|
||||||
|
expensive to fetch than
|
||||||
|
.BR PCAP_TSTAMP_HOST_LOWPREC .
|
||||||
|
.TP 5
|
||||||
|
.BR PCAP_TSTAMP_ADAPTER
|
||||||
|
Time stamp provided by the network adapter on which the capture is being
|
||||||
|
done. This is a high-precision time stamp, synchronized with the host
|
||||||
|
operating system's clock.
|
||||||
|
.TP 5
|
||||||
|
.BR PCAP_TSTAMP_ADAPTER_UNSYNC
|
||||||
|
Time stamp provided by the network adapter on which the capture is being
|
||||||
|
done. This is a high-precision time stamp; it is not synchronized with
|
||||||
|
the host operating system's clock.
|
||||||
|
.RE
|
||||||
|
.SH SEE ALSO
|
||||||
|
pcap_set_tstamp_type(3PCAP),
|
||||||
|
pcap_list_tstamp_types(3PCAP)
|
|
@ -0,0 +1,70 @@
|
||||||
|
.\"
|
||||||
|
.\" Copyright (c) 1994, 1996, 1997
|
||||||
|
.\" The Regents of the University of California. All rights reserved.
|
||||||
|
.\"
|
||||||
|
.\" Redistribution and use in source and binary forms, with or without
|
||||||
|
.\" modification, are permitted provided that: (1) source code distributions
|
||||||
|
.\" retain the above copyright notice and this paragraph in its entirety, (2)
|
||||||
|
.\" distributions including binary code include the above copyright notice and
|
||||||
|
.\" this paragraph in its entirety in the documentation or other materials
|
||||||
|
.\" provided with the distribution, and (3) all advertising materials mentioning
|
||||||
|
.\" features or use of this software display the following acknowledgement:
|
||||||
|
.\" ``This product includes software developed by the University of California,
|
||||||
|
.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
|
||||||
|
.\" the University nor the names of its contributors may be used to endorse
|
||||||
|
.\" or promote products derived from this software without specific prior
|
||||||
|
.\" written permission.
|
||||||
|
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
|
||||||
|
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
||||||
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
.\"
|
||||||
|
.TH PCAP_LIST_TSTAMP_TYPES 3PCAP "21 August 2010"
|
||||||
|
.SH NAME
|
||||||
|
pcap_list_tstamp_types, pcap_free_tstamp_types \- get a list of time
|
||||||
|
stamp types supported by a capture device, and free that list
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.nf
|
||||||
|
.ft B
|
||||||
|
#include <pcap/pcap.h>
|
||||||
|
.ft
|
||||||
|
.LP
|
||||||
|
.ft B
|
||||||
|
int pcap_list_tstamp_types(pcap_t *p, int **tstamp_typesp);
|
||||||
|
void pcap_free_tstamp_types(int *tstamp_types);
|
||||||
|
.ft
|
||||||
|
.fi
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.B pcap_list_tstamp_types()
|
||||||
|
is used to get a list of the supported time stamp types of the interface
|
||||||
|
associated with the pcap descriptor.
|
||||||
|
.B pcap_list_tstamp_types()
|
||||||
|
allocates an array to hold the list and sets
|
||||||
|
.I *tstamp_typesp
|
||||||
|
to point to the array.
|
||||||
|
See
|
||||||
|
.BR pcap-tstamp (@MAN_MISC_INFO@)
|
||||||
|
for a list of all the time stamp types.
|
||||||
|
.PP
|
||||||
|
The caller is responsible for freeing the array with
|
||||||
|
.BR pcap_free_tstamp_types() ,
|
||||||
|
which frees the list pointed to by
|
||||||
|
.IR tstamp_types .
|
||||||
|
.SH RETURN VALUE
|
||||||
|
.B pcap_list_tstamp_types()
|
||||||
|
returns the number of time stamp types in the array on success and
|
||||||
|
.B PCAP_ERROR
|
||||||
|
on failure.
|
||||||
|
A return value of zero means that you cannot specify a time stamp type;
|
||||||
|
you are limited to the capture device's default time stamp type.
|
||||||
|
If
|
||||||
|
.B PCAP_ERROR
|
||||||
|
is returned,
|
||||||
|
.B pcap_geterr()
|
||||||
|
or
|
||||||
|
.B pcap_perror()
|
||||||
|
may be called with
|
||||||
|
.I p
|
||||||
|
as an argument to fetch or display the error text.
|
||||||
|
.SH SEE ALSO
|
||||||
|
pcap(3PCAP), pcap_geterr(3PCAP), pcap_tstamp_type_val_to_name(3PCAP),
|
||||||
|
pcap-tstamp(@MAN_MISC_INFO@)
|
|
@ -0,0 +1,63 @@
|
||||||
|
.\"
|
||||||
|
.\" Copyright (c) 1994, 1996, 1997
|
||||||
|
.\" The Regents of the University of California. All rights reserved.
|
||||||
|
.\"
|
||||||
|
.\" Redistribution and use in source and binary forms, with or without
|
||||||
|
.\" modification, are permitted provided that: (1) source code distributions
|
||||||
|
.\" retain the above copyright notice and this paragraph in its entirety, (2)
|
||||||
|
.\" distributions including binary code include the above copyright notice and
|
||||||
|
.\" this paragraph in its entirety in the documentation or other materials
|
||||||
|
.\" provided with the distribution, and (3) all advertising materials mentioning
|
||||||
|
.\" features or use of this software display the following acknowledgement:
|
||||||
|
.\" ``This product includes software developed by the University of California,
|
||||||
|
.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
|
||||||
|
.\" the University nor the names of its contributors may be used to endorse
|
||||||
|
.\" or promote products derived from this software without specific prior
|
||||||
|
.\" written permission.
|
||||||
|
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
|
||||||
|
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
||||||
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
.\"
|
||||||
|
.TH PCAP_SET_TSTAMP_TYPE 3PCAP "21 August 2010"
|
||||||
|
.SH NAME
|
||||||
|
pcap_set_tstamp_type \- set the time stamp type to be used by a
|
||||||
|
capture device
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.nf
|
||||||
|
.ft B
|
||||||
|
#include <pcap/pcap.h>
|
||||||
|
.ft
|
||||||
|
.LP
|
||||||
|
.ft B
|
||||||
|
int pcap_set_tstamp_type(pcap_t *p, int tstamp_type);
|
||||||
|
.ft
|
||||||
|
.fi
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.B pcap_set_tstamp_type()
|
||||||
|
sets the the type of time stamp desired for packets captured on the pcap
|
||||||
|
descriptor to the type specified by
|
||||||
|
.IR tstamp_type .
|
||||||
|
It must be called on a pcap descriptor created by
|
||||||
|
.B pcap_create()
|
||||||
|
that has not yet been activated by
|
||||||
|
.BR pcap_activate() .
|
||||||
|
.B pcap_list_tstamp_types()
|
||||||
|
will give a list of the time stamp types supported by a given capture
|
||||||
|
device.
|
||||||
|
See
|
||||||
|
.BR pcap-tstamp (@MAN_MISC_INFO@)
|
||||||
|
for a list of all the time stamp types.
|
||||||
|
.SH RETURN VALUE
|
||||||
|
.B pcap_set_tstamp_type()
|
||||||
|
returns 0 on success,
|
||||||
|
.B PCAP_ERROR_ACTIVATED
|
||||||
|
if called on a capture handle that has been activated,
|
||||||
|
.B PCAP_ERROR_CANTSET_TSTAMP_TYPE
|
||||||
|
if the capture device doesn't support setting the time stamp type, and
|
||||||
|
.B PCAP_ERROR_TSTAMP_TYPE_NOTSUP
|
||||||
|
if the specified time stamp type is not supported by the capture device.
|
||||||
|
.SH SEE ALSO
|
||||||
|
pcap(3PCAP),
|
||||||
|
pcap_list_tstamp_types(3PCAP),
|
||||||
|
pcap_tstamp_type_name_to_val(3PCAP),
|
||||||
|
pcap-tstamp(@MAN_MISC_INFO@)
|
|
@ -0,0 +1,45 @@
|
||||||
|
.\"
|
||||||
|
.\" Copyright (c) 1994, 1996, 1997
|
||||||
|
.\" The Regents of the University of California. All rights reserved.
|
||||||
|
.\"
|
||||||
|
.\" Redistribution and use in source and binary forms, with or without
|
||||||
|
.\" modification, are permitted provided that: (1) source code distributions
|
||||||
|
.\" retain the above copyright notice and this paragraph in its entirety, (2)
|
||||||
|
.\" distributions including binary code include the above copyright notice and
|
||||||
|
.\" this paragraph in its entirety in the documentation or other materials
|
||||||
|
.\" provided with the distribution, and (3) all advertising materials mentioning
|
||||||
|
.\" features or use of this software display the following acknowledgement:
|
||||||
|
.\" ``This product includes software developed by the University of California,
|
||||||
|
.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
|
||||||
|
.\" the University nor the names of its contributors may be used to endorse
|
||||||
|
.\" or promote products derived from this software without specific prior
|
||||||
|
.\" written permission.
|
||||||
|
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
|
||||||
|
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
||||||
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
.\"
|
||||||
|
.TH PCAP_TSTAMP_TYPE_NAME_TO_VAL 3PCAP "21 August 2010"
|
||||||
|
.SH NAME
|
||||||
|
pcap_tstamp_type_name_to_val \- get the time stamp type value
|
||||||
|
corresponding to a time stamp type name
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.nf
|
||||||
|
.ft B
|
||||||
|
#include <pcap/pcap.h>
|
||||||
|
.ft
|
||||||
|
.LP
|
||||||
|
.ft B
|
||||||
|
int pcap_tstamp_type_name_to_val(const char *name);
|
||||||
|
.ft
|
||||||
|
.fi
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.B pcap_tstamp_type_name_to_val()
|
||||||
|
translates a time stamp type name to the corresponding time stamp type
|
||||||
|
value. The translation is case-insensitive.
|
||||||
|
.SH RETURN VALUE
|
||||||
|
.B pcap_tstamp_type_name_to_val()
|
||||||
|
returns 0 on success and
|
||||||
|
.B PCAP_ERROR
|
||||||
|
on failure.
|
||||||
|
.SH SEE ALSO
|
||||||
|
pcap(3PCAP), pcap_tstamp_type_val_to_name(3PCAP)
|
|
@ -0,0 +1,45 @@
|
||||||
|
.\"
|
||||||
|
.\" Copyright (c) 1994, 1996, 1997
|
||||||
|
.\" The Regents of the University of California. All rights reserved.
|
||||||
|
.\"
|
||||||
|
.\" Redistribution and use in source and binary forms, with or without
|
||||||
|
.\" modification, are permitted provided that: (1) source code distributions
|
||||||
|
.\" retain the above copyright notice and this paragraph in its entirety, (2)
|
||||||
|
.\" distributions including binary code include the above copyright notice and
|
||||||
|
.\" this paragraph in its entirety in the documentation or other materials
|
||||||
|
.\" provided with the distribution, and (3) all advertising materials mentioning
|
||||||
|
.\" features or use of this software display the following acknowledgement:
|
||||||
|
.\" ``This product includes software developed by the University of California,
|
||||||
|
.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
|
||||||
|
.\" the University nor the names of its contributors may be used to endorse
|
||||||
|
.\" or promote products derived from this software without specific prior
|
||||||
|
.\" written permission.
|
||||||
|
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
|
||||||
|
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
||||||
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||||||
|
.\"
|
||||||
|
.TH PCAP_TSTAMP_TYPE_VAL_TO_NAME 3PCAP "21 August 2010"
|
||||||
|
.SH NAME
|
||||||
|
pcap_tstamp_type_val_to_name, pcap_tstamp_type_val_to_description \- get
|
||||||
|
a name or description for a time stamp type value
|
||||||
|
.SH SYNOPSIS
|
||||||
|
.nf
|
||||||
|
.ft B
|
||||||
|
#include <pcap.h>
|
||||||
|
.ft
|
||||||
|
.LP
|
||||||
|
.ft B
|
||||||
|
const char *pcap_tstamp_type_val_to_name(int tstamp_type);
|
||||||
|
const char *pcap_tstamp_type_val_to_description(int tstamp_type);
|
||||||
|
.ft
|
||||||
|
.fi
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.B pcap_tstamp_type_val_to_name()
|
||||||
|
translates a time stamp type value to the corresponding time stamp type
|
||||||
|
name. NULL is returned on failure.
|
||||||
|
.PP
|
||||||
|
.B pcap_tstamp_type_val_to_description()
|
||||||
|
translates a time stamp type value to a short description of that time
|
||||||
|
stamp type. NULL is returned on failure.
|
||||||
|
.SH SEE ALSO
|
||||||
|
pcap(3PCAP), pcap_tstamp_type_name_to_val(3PCAP)
|
Reference in New Issue