diff --git a/pcap-tstamp.manmisc.in b/pcap-tstamp.manmisc.in new file mode 100644 index 0000000..dd63087 --- /dev/null +++ b/pcap-tstamp.manmisc.in @@ -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) diff --git a/pcap_list_tstamp_types.3pcap.in b/pcap_list_tstamp_types.3pcap.in new file mode 100644 index 0000000..66d3d66 --- /dev/null +++ b/pcap_list_tstamp_types.3pcap.in @@ -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 +.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@) diff --git a/pcap_set_tstamp_type.3pcap.in b/pcap_set_tstamp_type.3pcap.in new file mode 100644 index 0000000..a9b7e48 --- /dev/null +++ b/pcap_set_tstamp_type.3pcap.in @@ -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 +.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@) diff --git a/pcap_tstamp_type_name_to_val.3pcap b/pcap_tstamp_type_name_to_val.3pcap new file mode 100644 index 0000000..8fcc4d7 --- /dev/null +++ b/pcap_tstamp_type_name_to_val.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_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 +.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) diff --git a/pcap_tstamp_type_val_to_name.3pcap b/pcap_tstamp_type_val_to_name.3pcap new file mode 100644 index 0000000..5d8d754 --- /dev/null +++ b/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 +.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)