Permalink
Browse files

Add support for setting the time stamp type for a capture.

Based on a patch from Scott Mcmillan <scott.a.mcmillan@intel.com>.
  • Loading branch information...
1 parent 0ba94d1 commit 951f99bbbd4e1fcf44cc9ad82880abdeac82eb78 @guyharris guyharris committed Aug 22, 2010
View
@@ -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)

0 comments on commit 951f99b

Please sign in to comment.