Permalink
Browse files

Document the new API's, move a bunch of information about libpcap

concepts to the pcap(3PCAP) man page, refer people to the pcap(3PCAP)
man page from the man pages for libpcap functions, and clean up some
errors.
  • Loading branch information...
1 parent 3734017 commit f84d077e075d7e976be9d2334bf0f68e83cb95a5 @yuguy yuguy committed Apr 6, 2008
View
@@ -1,4 +1,4 @@
-.\" @(#) $Header: /tcpdump/master/libpcap/Attic/pcap.3pcap,v 1.2 2008-04-05 20:26:56 guy Exp $
+.\" @(#) $Header: /tcpdump/master/libpcap/Attic/pcap.3pcap,v 1.3 2008-04-06 02:53:21 guy Exp $
.\"
.\" Copyright (c) 1994, 1996, 1997
.\" The Regents of the University of California. All rights reserved.
@@ -38,16 +38,145 @@ through this mechanism.
It also supports saving captured packets to a ``savefile'', and reading
packets from a ``savefile''.
.PP
-To open a live capture stream, call
-.BR pcap_open_live() ,
-and to open a ``savefile'' to read the packets in that file, call
+To open a handle for a live capture, call
+.BR pcap_create() ,
+set the appropriate options on the handle, and then activate it with
+.BR pcap_activate() .
+To open a handle for a ``savefile'' with captured packets, call
.BR pcap_open_offline() .
-Both routines return a pointer to a
+Both
+.B pcap_create()
+and
+.B pcap_open_offline()
+return a pointer to a
.BR pcap_t ,
which is the handle used for reading packets from the capture stream or
the ``savefile'', and for finding out information about the capture
stream or ``savefile''.
.PP
+The options that can be set on a capture handle include
+.IP "snapshot length"
+If, when capturing, you capture the entire contents of the packet, that
+requires more CPU time to copy the packet to your application, more disk
+and possibly network bandwidth to write the packet data to a file, and
+more disk space to save the packet. If you don't need the entire
+contents of the packet - for example, if you are only interested in the
+TCP headers of packets - you can set the "snapshot length" for the
+capture to an appropriate value. If the snapshot length is set to
+.IR snaplen ,
+and
+.I snaplen
+is less
+than the size of a packet that is captured, only the first
+.I snaplen
+bytes of that packet will be captured and provided as packet data.
+.IP
+A snapshot length of 65535 should be sufficient, on most if not all
+networks, to capture all the data available from the packet.
+.IP
+The snapshot length is set with
+.BR pcap_set_snaplen() .
+.IP "promiscuous mode"
+On broadcast LANs such as Ethernet, if the network isn't switched, or if
+the adapter is connected to a "mirror port" on a switch to which all
+packets passing through the switch are sent, a network adapter receives
+all packets on the LAN, including unicast or multicast packets not sent
+to a network address that the network adapter isn't configured to
+recognize.
+.IP
+Normally, the adapter will discard those packets; however, many network
+adapters support "promiscuous mode", which is a mode in which all
+packets, even if they are not sent to an address that the adapter
+recognizes, are provided to the host. This is useful for passively
+capturing traffic between two or more other hosts for analysis.
+.IP
+Note that even if an application does not set promiscuous mode, the
+adapter could well be in promiscuous mode for some other reason.
+.IP
+For now, this doesn't work on the "any" device; if an argument of "any"
+or NULL is supplied, the setting of promiscuous mode is ignored.
+.IP
+Promiscuous mode is set with
+.BR pcap_set_promisc() .
+.IP "monitor mode"
+On IEEE 802.11 wireless LANs, even if an adapter is in promiscuous mode,
+it will supply to the host only frames for the network with which it's
+associated. It might also supply only data frames, not management or
+control frames, and might not provide the 802.11 header or radio
+information pseudo-header for those frames.
+.IP
+In "monitor mode", sometimes also called "rfmon mode" (for "Radio
+Frequency MONitor"), the adapter will supply all frames that it
+receives, with 802.11 headers, and might supply a pseudo-header with
+radio information about the frame as well.
+.IP
+Note that in monitor mode the adapter might disassociate from the
+network with which it's associated, so that you will not be able to use
+any wireless networks with that adapter. This could prevent accessing
+files on a network server, or resolving host names or network addresses,
+if you are capturing in monitor mode and are not connected to another
+network with another adapter.
+.IP
+Monitor mode is set with
+.BR pcap_set_rfmon() ,
+and
+.B pcap_can_set_rfmon()
+can be used to determine whether an adapter can be put into monitor
+mode.
+.IP "read timeout"
+If, when capturing, packets are delivered as soon as they arrive, the
+application capturing the packets will be woken up for each packet as it
+arrives, and might have to make one or more calls to the operating
+system to fetch each packet.
+.IP
+If, instead, packets are not delivered as soon as they arrive, but are
+delivered after a short delay (called a "read timeout"), more than one
+packet can be accumulated before the packets are delivered, so that a
+single wakeup would be done for multiple packets, and each set of calls
+made to the operating system would supply multiple packets, rather than
+a single packet. This reduces the per-packet CPU overhead if packets
+are arriving at a high rate, increasing the number of packets per second
+that can be captured.
+.IP
+The read timeout is required so that an application won't wait for the
+operating system's capture buffer to fill up before packets are
+delivered; if packets are arriving slowly, that wait could take an
+arbitrarily long period of time.
+.IP
+Not all platforms support a read timeout; on platforms that
+don't, the read timeout is ignored. A zero value for the timeout,
+on platforms that support a read timeout,
+will cause a read to wait forever to allow enough packets to
+arrive, with no timeout.
+.IP
+.BR NOTE :
+the read timeout cannot be used to cause calls that read
+packets to return within a limited period of time, because, on some
+platforms, the read timeout isn't supported, and, on other platforms,
+the timer doesn't start until at least one packet arrives. This means
+that the read timeout should
+.B NOT
+be used, for example, in an interactive application to allow the packet
+capture loop to ``poll'' for user input periodically, as there's no
+guarantee that a call reading packets will return after the timeout
+expires even if no packets have arrived.
+.IP
+The read timeout is set with
+.BR pcap_set_timeout() .
+.IP "buffer size"
+Packets that arrive for a capture are stored in a buffer, so that they
+do not have to be read by the application as soon as they arrive. On
+some platforms, the buffer's size can be set; a size that's too small
+could mean that, if too many packets are being captured and the snapshot
+length doesn't limit the amount of data that's buffered, packets could
+be dropped if the buffer fills up before the application can read
+packets from it, while a size that's too large could use more
+non-pageable operating system memory than is necessary to prevent
+packets from being dropped.
+.IP
+The buffer size is set with
+.BR pcap_set_buffer_size() .
+.PP
To open a ``savefile`` to which to write packets, call
.BR pcap_dump_open() .
It returns a pointer to a
@@ -69,7 +198,7 @@ The callback for
and
.BR pcap_loop()
is supplied a pointer to a
-.IR struct pcap_pkthdr ,
+.IR "struct pcap_pkthdr" ,
which includes the following members:
.RS
.TP
@@ -120,9 +249,38 @@ performed will limit the amount of packet data available.
returns that pointer;
.B pcap_next_ex()
supplies that pointer through a pointer argument.
-.SH ROUTINES
+.SH BACKWARDS COMPATIBILITY
+.PP
+In versions of libpcap prior to 1.0, the
+.B pcap.h
+header file was not in a
+.B pcap
+directory on most platforms; if you are writing an application that must
+work on versions of libpcap prior to 1.0, include
+.BR <pcap.h> ,
+which will include
+.B <pcap/pcap.h>
+for you, rather than including
+.BR <pcap/pcap.h> .
+.PP
+.B pcap_create()
+and
+.B pcap_activate()
+were not available in versions of libpcap prior to 1.0; if you are
+writing an application that must work on versions of libpcap prior to
+1.0, either use
+.B pcap_open_live()
+to get a handle for a live capture or, if you want to be able to use the
+additional capabilities offered by using
+.B pcap_create()
+and
+.BR pcap_activate() ,
+use an
+.BR autoconf (1)
+script or some other configuration script to check whether the libpcap
+1.0 APIs are available and use them only if they are.
.SH SEE ALSO
-tcpdump(1), tcpslice(1), pcap-filter(4)
+autoconf(1), tcpdump(1), tcpslice(1), pcap-filter(4)
.SH AUTHORS
The original authors of libpcap are:
.LP
View
@@ -0,0 +1,62 @@
+.\" @(#) $Header: /tcpdump/master/libpcap/pcap_activate.3pcap,v 1.1 2008-04-06 02:53:21 guy Exp $
+.\"
+.\" 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_ACTIVATE 3PCAP "5 April 2008"
+.SH NAME
+pcap_activate \- activate a capture handle
+.SH SYNOPSIS
+.nf
+.ft B
+#include <pcap/pcap.h>
+.ft
+.LP
+.ft B
+int pcap_activate(pcap_t *p);
+.ft
+.fi
+.SH DESCRIPTION
+.B pcap_activate()
+is used to activate a packet capture handle to look
+at packets on the network, with the options that were set on the handle
+being in effect.
+.SH RETURN VALUE
+.B pcap_activate()
+returns 0 on success,
+.B PCAP_ERROR_ACTIVATED
+if the handle has already been activated,
+.B PCAP_ERROR_NO_SUCH_DEVICE
+if the capture source specified when the handle was created doesn't exist,
+.B PCAP_ERROR_RFMON_NOTSUP
+if monitor mode was specified but the capture source doesn't support
+monitor mode, and
+.B PCAP_ERROR
+if an error occurred.
+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)
@@ -1,4 +1,4 @@
-.\" @(#) $Header: /tcpdump/master/libpcap/pcap_breakloop.3pcap,v 1.2 2008-04-05 20:26:56 guy Exp $
+.\" @(#) $Header: /tcpdump/master/libpcap/pcap_breakloop.3pcap,v 1.3 2008-04-06 02:53:21 guy Exp $
.\"
.\" Copyright (c) 1994, 1996, 1997
.\" The Regents of the University of California. All rights reserved.
@@ -19,7 +19,7 @@
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\"
-.TH PCAP_BREAKLOOP 3PCAP "4 April 2008"
+.TH PCAP_BREAKLOOP 3PCAP "5 April 2008"
.SH NAME
pcap_breakloop \- force a pcap_dispatch() or pcap_loop() call to return
.SH SYNOPSIS
@@ -102,4 +102,4 @@ the flag is cleared, so a subsequent call will resume reading packets.
If a positive number is returned, the flag is not cleared, so a
subsequent call will return \-2 and clear the flag.
.SH SEE ALSO
-pcap_loop(3PCAP), pcap_next_ex(3PCAP)
+pcap(3PCAP), pcap_loop(3PCAP), pcap_next_ex(3PCAP)
@@ -0,0 +1,60 @@
+.\" @(#) $Header: /tcpdump/master/libpcap/pcap_can_set_rfmon.3pcap,v 1.1 2008-04-06 02:53:21 guy Exp $
+.\"
+.\" 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_CAN_SET_RFMON 3PCAP "5 April 2008"
+.SH NAME
+pcap_can_set_rfmon \- check whether monitor mode can be set for a
+not-yet-activated capture handle
+.SH SYNOPSIS
+.nf
+.ft B
+#include <pcap/pcap.h>
+.LP
+.ft B
+int pcap_can_set_rfmon(pcap_t *p);
+.ft
+.fi
+.SH DESCRIPTION
+.B pcap_can_set_rfmon()
+checks whether monitor mode could be set on a capture handle when
+the handle is activated.
+.SH RETURN VALUE
+.B pcap_set_rfmon()
+returns 0 if monitor mode could not be set,
+1 if monitor mode could be set,
+.B PCAP_ERROR_NO_SUCH_DEVICE
+if the device specified when the handle was created doesn't exist,
+.B PCAP_ERROR_ACTIVATED
+if called on a capture handle that has been activated, or
+.B PCAP_ERROR
+if an error occurred.
+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_create(3PCAP), pcap_activate(3PCAP),
+pcap_set_rfmon(3PCAP)
View
@@ -1,4 +1,4 @@
-.\" @(#) $Header: /tcpdump/master/libpcap/pcap_close.3pcap,v 1.2 2008-04-05 20:26:56 guy Exp $
+.\" @(#) $Header: /tcpdump/master/libpcap/pcap_close.3pcap,v 1.3 2008-04-06 02:53:21 guy Exp $
.\"
.\" Copyright (c) 1994, 1996, 1997
.\" The Regents of the University of California. All rights reserved.
@@ -19,7 +19,7 @@
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\"
-.TH PCAP_CLOSE 3PCAP "4 April 2008"
+.TH PCAP_CLOSE 3PCAP "5 April 2008"
.SH NAME
pcap_close \- close a capture device or savefile
.SH SYNOPSIS
@@ -37,3 +37,5 @@ void pcap_close(pcap_t *p);
closes the files associated with
.I p
and deallocates resources.
+.SH SEE ALSO
+pcap(3PCAP)
View
@@ -1,4 +1,4 @@
-.\" @(#) $Header: /tcpdump/master/libpcap/Attic/pcap_compile.3pcap,v 1.2 2008-04-05 20:26:56 guy Exp $
+.\" @(#) $Header: /tcpdump/master/libpcap/Attic/pcap_compile.3pcap,v 1.3 2008-04-06 02:53:21 guy Exp $
.\"
.\" Copyright (c) 1994, 1996, 1997
.\" The Regents of the University of California. All rights reserved.
@@ -19,7 +19,7 @@
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\"
-.TH PCAP_COMPILE 3PCAP "4 April 2008"
+.TH PCAP_COMPILE 3PCAP "5 April 2008"
.SH NAME
pcap_compile \- compile a filter expression
.SH SYNOPSIS
@@ -68,5 +68,5 @@ may be called with
.I p
as an argument to fetch or display the error text.
.SH SEE ALSO
-pcap_setfilter(3PCAP), pcap_freecode(3PCAP), pcap_geterr(3PCAP),
-pcap-filter(4)
+pcap(3PCAP), pcap_setfilter(3PCAP), pcap_freecode(3PCAP),
+pcap_geterr(3PCAP), pcap-filter(4)
Oops, something went wrong.

0 comments on commit f84d077

Please sign in to comment.