JP Abgrall | 511eca3 | 2014-02-12 13:46:45 -0800 | [diff] [blame] | 1 | .\" @(#) $Header: /tcpdump/master/libpcap/pcap.3pcap.in,v 1.1 2008-10-21 07:33:01 guy Exp $ |
| 2 | .\" |
| 3 | .\" Copyright (c) 1994, 1996, 1997 |
| 4 | .\" The Regents of the University of California. All rights reserved. |
| 5 | .\" |
| 6 | .\" Redistribution and use in source and binary forms, with or without |
| 7 | .\" modification, are permitted provided that: (1) source code distributions |
| 8 | .\" retain the above copyright notice and this paragraph in its entirety, (2) |
| 9 | .\" distributions including binary code include the above copyright notice and |
| 10 | .\" this paragraph in its entirety in the documentation or other materials |
| 11 | .\" provided with the distribution, and (3) all advertising materials mentioning |
| 12 | .\" features or use of this software display the following acknowledgement: |
| 13 | .\" ``This product includes software developed by the University of California, |
| 14 | .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of |
| 15 | .\" the University nor the names of its contributors may be used to endorse |
| 16 | .\" or promote products derived from this software without specific prior |
| 17 | .\" written permission. |
| 18 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED |
| 19 | .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF |
| 20 | .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| 21 | .\" |
| 22 | .TH PCAP 3PCAP "1 July 2013" |
| 23 | .SH NAME |
| 24 | pcap \- Packet Capture library |
| 25 | .SH SYNOPSIS |
| 26 | .nf |
| 27 | .ft B |
| 28 | #include <pcap/pcap.h> |
| 29 | .LP |
| 30 | .ft B |
| 31 | .ft |
| 32 | .fi |
| 33 | .SH DESCRIPTION |
| 34 | The Packet Capture library |
| 35 | provides a high level interface to packet capture systems. All packets |
| 36 | on the network, even those destined for other hosts, are accessible |
| 37 | through this mechanism. |
| 38 | It also supports saving captured packets to a ``savefile'', and reading |
| 39 | packets from a ``savefile''. |
| 40 | .SS Opening a capture handle for reading |
| 41 | To open a handle for a live capture, given the name of the network or |
| 42 | other interface on which the capture should be done, call |
| 43 | .BR pcap_create (), |
| 44 | set the appropriate options on the handle, and then activate it with |
| 45 | .BR pcap_activate (). |
| 46 | .PP |
| 47 | To obtain a list of devices that can be opened for a live capture, call |
| 48 | .BR pcap_findalldevs (); |
| 49 | to free the list returned by |
| 50 | .BR pcap_findalldevs (), |
| 51 | call |
| 52 | .BR pcap_freealldevs (). |
| 53 | .BR pcap_lookupdev () |
| 54 | will return the first device on that list that is not a ``loopback`` |
| 55 | network interface. |
| 56 | .PP |
| 57 | To open a handle for a ``savefile'' from which to read packets, given the |
| 58 | pathname of the ``savefile'', call |
| 59 | .BR pcap_open_offline (); |
| 60 | to set up a handle for a ``savefile'', given a |
| 61 | .B "FILE\ *" |
| 62 | referring to a file already opened for reading, call |
| 63 | .BR pcap_fopen_offline (). |
| 64 | .PP |
| 65 | In order to get a ``fake'' |
| 66 | .B pcap_t |
| 67 | for use in routines that require a |
| 68 | .B pcap_t |
| 69 | as an argument, such as routines to open a ``savefile'' for writing and |
| 70 | to compile a filter expression, call |
| 71 | .BR pcap_open_dead (). |
| 72 | .PP |
| 73 | .BR pcap_create (), |
| 74 | .BR pcap_open_offline (), |
| 75 | .BR pcap_fopen_offline (), |
| 76 | and |
| 77 | .BR pcap_open_dead () |
| 78 | return a pointer to a |
| 79 | .BR pcap_t , |
| 80 | which is the handle used for reading packets from the capture stream or |
| 81 | the ``savefile'', and for finding out information about the capture |
| 82 | stream or ``savefile''. |
| 83 | To close a handle, use |
| 84 | .BR pcap_close (). |
| 85 | .PP |
| 86 | The options that can be set on a capture handle include |
| 87 | .IP "snapshot length" |
| 88 | If, when capturing, you capture the entire contents of the packet, that |
| 89 | requires more CPU time to copy the packet to your application, more disk |
| 90 | and possibly network bandwidth to write the packet data to a file, and |
| 91 | more disk space to save the packet. If you don't need the entire |
| 92 | contents of the packet - for example, if you are only interested in the |
| 93 | TCP headers of packets - you can set the "snapshot length" for the |
| 94 | capture to an appropriate value. If the snapshot length is set to |
| 95 | .IR snaplen , |
| 96 | and |
| 97 | .I snaplen |
| 98 | is less |
| 99 | than the size of a packet that is captured, only the first |
| 100 | .I snaplen |
| 101 | bytes of that packet will be captured and provided as packet data. |
| 102 | .IP |
| 103 | A snapshot length of 65535 should be sufficient, on most if not all |
| 104 | networks, to capture all the data available from the packet. |
| 105 | .IP |
| 106 | The snapshot length is set with |
| 107 | .BR pcap_set_snaplen (). |
| 108 | .IP "promiscuous mode" |
| 109 | On broadcast LANs such as Ethernet, if the network isn't switched, or if |
| 110 | the adapter is connected to a "mirror port" on a switch to which all |
| 111 | packets passing through the switch are sent, a network adapter receives |
| 112 | all packets on the LAN, including unicast or multicast packets not sent |
| 113 | to a network address that the network adapter isn't configured to |
| 114 | recognize. |
| 115 | .IP |
| 116 | Normally, the adapter will discard those packets; however, many network |
| 117 | adapters support "promiscuous mode", which is a mode in which all |
| 118 | packets, even if they are not sent to an address that the adapter |
| 119 | recognizes, are provided to the host. This is useful for passively |
| 120 | capturing traffic between two or more other hosts for analysis. |
| 121 | .IP |
| 122 | Note that even if an application does not set promiscuous mode, the |
| 123 | adapter could well be in promiscuous mode for some other reason. |
| 124 | .IP |
| 125 | For now, this doesn't work on the "any" device; if an argument of "any" |
| 126 | or NULL is supplied, the setting of promiscuous mode is ignored. |
| 127 | .IP |
| 128 | Promiscuous mode is set with |
| 129 | .BR pcap_set_promisc (). |
| 130 | .IP "monitor mode" |
| 131 | On IEEE 802.11 wireless LANs, even if an adapter is in promiscuous mode, |
| 132 | it will supply to the host only frames for the network with which it's |
| 133 | associated. It might also supply only data frames, not management or |
| 134 | control frames, and might not provide the 802.11 header or radio |
| 135 | information pseudo-header for those frames. |
| 136 | .IP |
| 137 | In "monitor mode", sometimes also called "rfmon mode" (for "Radio |
| 138 | Frequency MONitor"), the adapter will supply all frames that it |
| 139 | receives, with 802.11 headers, and might supply a pseudo-header with |
| 140 | radio information about the frame as well. |
| 141 | .IP |
| 142 | Note that in monitor mode the adapter might disassociate from the |
| 143 | network with which it's associated, so that you will not be able to use |
| 144 | any wireless networks with that adapter. This could prevent accessing |
| 145 | files on a network server, or resolving host names or network addresses, |
| 146 | if you are capturing in monitor mode and are not connected to another |
| 147 | network with another adapter. |
| 148 | .IP |
| 149 | Monitor mode is set with |
| 150 | .BR pcap_set_rfmon (), |
| 151 | and |
| 152 | .BR pcap_can_set_rfmon () |
| 153 | can be used to determine whether an adapter can be put into monitor |
| 154 | mode. |
| 155 | .IP "read timeout" |
| 156 | If, when capturing, packets are delivered as soon as they arrive, the |
| 157 | application capturing the packets will be woken up for each packet as it |
| 158 | arrives, and might have to make one or more calls to the operating |
| 159 | system to fetch each packet. |
| 160 | .IP |
| 161 | If, instead, packets are not delivered as soon as they arrive, but are |
| 162 | delivered after a short delay (called a "read timeout"), more than one |
| 163 | packet can be accumulated before the packets are delivered, so that a |
| 164 | single wakeup would be done for multiple packets, and each set of calls |
| 165 | made to the operating system would supply multiple packets, rather than |
| 166 | a single packet. This reduces the per-packet CPU overhead if packets |
| 167 | are arriving at a high rate, increasing the number of packets per second |
| 168 | that can be captured. |
| 169 | .IP |
| 170 | The read timeout is required so that an application won't wait for the |
| 171 | operating system's capture buffer to fill up before packets are |
| 172 | delivered; if packets are arriving slowly, that wait could take an |
| 173 | arbitrarily long period of time. |
| 174 | .IP |
| 175 | Not all platforms support a read timeout; on platforms that |
| 176 | don't, the read timeout is ignored. A zero value for the timeout, |
| 177 | on platforms that support a read timeout, has platform-dependent |
| 178 | behavior that could cause a read to wait for an unlimited amount |
| 179 | of time until the capture buffer fills up or could cause a read timeout |
| 180 | of 1 millisecond to be used. We recommend that a value of zero not be |
| 181 | used. |
| 182 | .IP |
| 183 | .BR NOTE : |
| 184 | the read timeout cannot be used to cause calls that read |
| 185 | packets to return within a limited period of time, because, on some |
| 186 | platforms, the read timeout isn't supported, and, on other platforms, |
| 187 | the timer doesn't start until at least one packet arrives. This means |
| 188 | that the read timeout should |
| 189 | .B NOT |
| 190 | be used, for example, in an interactive application to allow the packet |
| 191 | capture loop to ``poll'' for user input periodically, as there's no |
| 192 | guarantee that a call reading packets will return after the timeout |
| 193 | expires even if no packets have arrived. |
| 194 | .IP |
| 195 | The read timeout is set with |
| 196 | .BR pcap_set_timeout (). |
| 197 | .IP "buffer size" |
| 198 | Packets that arrive for a capture are stored in a buffer, so that they |
| 199 | do not have to be read by the application as soon as they arrive. On |
| 200 | some platforms, the buffer's size can be set; a size that's too small |
| 201 | could mean that, if too many packets are being captured and the snapshot |
| 202 | length doesn't limit the amount of data that's buffered, packets could |
| 203 | be dropped if the buffer fills up before the application can read |
| 204 | packets from it, while a size that's too large could use more |
| 205 | non-pageable operating system memory than is necessary to prevent |
| 206 | packets from being dropped. |
| 207 | .IP |
| 208 | The buffer size is set with |
| 209 | .BR pcap_set_buffer_size (). |
| 210 | .IP "timestamp type" |
| 211 | On some platforms, the time stamp given to packets on live captures can |
| 212 | come from different sources that can have different resolutions or that |
| 213 | can have different relationships to the time values for the current time |
| 214 | supplied by routines on the native operating system. See |
| 215 | .BR pcap-tstamp (@MAN_MISC_INFO@) |
| 216 | for a list of time stamp types. |
| 217 | .IP |
| 218 | The time stamp type is set with |
| 219 | .BR pcap_set_tstamp_type (). |
| 220 | .PP |
| 221 | Reading packets from a network interface may require that you have |
| 222 | special privileges: |
| 223 | .TP |
| 224 | .B Under SunOS 3.x or 4.x with NIT or BPF: |
| 225 | You must have read access to |
| 226 | .I /dev/nit |
| 227 | or |
| 228 | .IR /dev/bpf* . |
| 229 | .TP |
| 230 | .B Under Solaris with DLPI: |
| 231 | You must have read/write access to the network pseudo device, e.g. |
| 232 | .IR /dev/le . |
| 233 | On at least some versions of Solaris, however, this is not sufficient to |
| 234 | allow |
| 235 | .I tcpdump |
| 236 | to capture in promiscuous mode; on those versions of Solaris, you must |
| 237 | be root, or the application capturing packets |
| 238 | must be installed setuid to root, in order to capture in promiscuous |
| 239 | mode. Note that, on many (perhaps all) interfaces, if you don't capture |
| 240 | in promiscuous mode, you will not see any outgoing packets, so a capture |
| 241 | not done in promiscuous mode may not be very useful. |
| 242 | .IP |
| 243 | In newer versions of Solaris, you must have been given the |
| 244 | .B net_rawaccess |
| 245 | privilege; this is both necessary and sufficient to give you access to the |
| 246 | network pseudo-device - there is no need to change the privileges on |
| 247 | that device. A user can be given that privilege by, for example, adding |
| 248 | that privilege to the user's |
| 249 | .B defaultpriv |
| 250 | key with the |
| 251 | .B usermod (1M) |
| 252 | command. |
| 253 | .TP |
| 254 | .B Under HP-UX with DLPI: |
| 255 | You must be root or the application capturing packets must be installed |
| 256 | setuid to root. |
| 257 | .TP |
| 258 | .B Under IRIX with snoop: |
| 259 | You must be root or the application capturing packets must be installed |
| 260 | setuid to root. |
| 261 | .TP |
| 262 | .B Under Linux: |
| 263 | You must be root or the application capturing packets must be installed |
| 264 | setuid to root (unless your distribution has a kernel |
| 265 | that supports capability bits such as CAP_NET_RAW and code to allow |
| 266 | those capability bits to be given to particular accounts and to cause |
| 267 | those bits to be set on a user's initial processes when they log in, in |
| 268 | which case you must have CAP_NET_RAW in order to capture and |
| 269 | CAP_NET_ADMIN to enumerate network devices with, for example, the |
| 270 | .B \-D |
| 271 | flag). |
| 272 | .TP |
| 273 | .B Under ULTRIX and Digital UNIX/Tru64 UNIX: |
| 274 | Any user may capture network traffic. |
| 275 | However, no user (not even the super-user) can capture in promiscuous |
| 276 | mode on an interface unless the super-user has enabled promiscuous-mode |
| 277 | operation on that interface using |
| 278 | .IR pfconfig (8), |
| 279 | and no user (not even the super-user) can capture unicast traffic |
| 280 | received by or sent by the machine on an interface unless the super-user |
| 281 | has enabled copy-all-mode operation on that interface using |
| 282 | .IR pfconfig , |
| 283 | so |
| 284 | .I useful |
| 285 | packet capture on an interface probably requires that either |
| 286 | promiscuous-mode or copy-all-mode operation, or both modes of |
| 287 | operation, be enabled on that interface. |
| 288 | .TP |
| 289 | .B Under BSD (this includes Mac OS X): |
| 290 | You must have read access to |
| 291 | .I /dev/bpf* |
| 292 | on systems that don't have a cloning BPF device, or to |
| 293 | .I /dev/bpf |
| 294 | on systems that do. |
| 295 | On BSDs with a devfs (this includes Mac OS X), this might involve more |
| 296 | than just having somebody with super-user access setting the ownership |
| 297 | or permissions on the BPF devices - it might involve configuring devfs |
| 298 | to set the ownership or permissions every time the system is booted, |
| 299 | if the system even supports that; if it doesn't support that, you might |
| 300 | have to find some other way to make that happen at boot time. |
| 301 | .PP |
| 302 | Reading a saved packet file doesn't require special privileges. |
| 303 | .PP |
| 304 | The packets read from the handle may include a ``pseudo-header'' |
| 305 | containing various forms of packet meta-data, and probably includes a |
| 306 | link-layer header whose contents can differ for different network |
| 307 | interfaces. To determine the format of the packets supplied by the |
| 308 | handle, call |
| 309 | .BR pcap_datalink (); |
| 310 | .I http://www.tcpdump.org/linktypes.html |
| 311 | lists the values it returns and describes the packet formats that |
| 312 | correspond to those values. |
| 313 | .PP |
| 314 | Do |
| 315 | .B NOT |
| 316 | assume that the packets for a given capture or ``savefile`` will have |
| 317 | any given link-layer header type, such as |
| 318 | .B DLT_EN10MB |
| 319 | for Ethernet. For example, the "any" device on Linux will have a |
| 320 | link-layer header type of |
| 321 | .B DLT_LINUX_SLL |
| 322 | even if all devices on the system at the time the "any" device is opened |
| 323 | have some other data link type, such as |
| 324 | .B DLT_EN10MB |
| 325 | for Ethernet. |
| 326 | .PP |
| 327 | To obtain the |
| 328 | .B "FILE\ *" |
| 329 | corresponding to a |
| 330 | .B pcap_t |
| 331 | opened for a ``savefile'', call |
| 332 | .BR pcap_file (). |
| 333 | .TP |
| 334 | .B Routines |
| 335 | .RS |
| 336 | .TP |
| 337 | .BR pcap_create (3PCAP) |
| 338 | get a |
| 339 | .B pcap_t |
| 340 | for live capture |
| 341 | .TP |
| 342 | .BR pcap_activate (3PCAP) |
| 343 | activate a |
| 344 | .B pcap_t |
| 345 | for live capture |
| 346 | .TP |
| 347 | .BR pcap_findalldevs (3PCAP) |
| 348 | get a list of devices that can be opened for a live capture |
| 349 | .TP |
| 350 | .BR pcap_freealldevs (3PCAP) |
| 351 | free list of devices |
| 352 | .TP |
| 353 | .BR pcap_lookupdev (3PCAP) |
| 354 | get first non-loopback device on that list |
| 355 | .TP |
| 356 | .BR pcap_open_offline (3PCAP) |
| 357 | open a |
| 358 | .B pcap_t |
| 359 | for a ``savefile'', given a pathname |
| 360 | .TP |
| 361 | .BR pcap_fopen_offline (3PCAP) |
| 362 | open a |
| 363 | .B pcap_t |
| 364 | for a ``savefile'', given a |
| 365 | .B "FILE\ *" |
| 366 | .TP |
| 367 | .BR pcap_open_dead (3PCAP) |
| 368 | create a ``fake'' |
| 369 | .B pcap_t |
| 370 | .TP |
| 371 | .BR pcap_close (3PCAP) |
| 372 | close a |
| 373 | .B pcap_t |
| 374 | .TP |
| 375 | .BR pcap_set_snaplen (3PCAP) |
| 376 | set the snapshot length for a not-yet-activated |
| 377 | .B pcap_t |
| 378 | for live capture |
| 379 | .TP |
| 380 | .BR pcap_snapshot (3PCAP) |
| 381 | get the snapshot length for a |
| 382 | .B pcap_t |
| 383 | .TP |
| 384 | .BR pcap_set_promisc (3PCAP) |
| 385 | set promiscuous mode for a not-yet-activated |
| 386 | .B pcap_t |
| 387 | for live capture |
| 388 | .TP |
| 389 | .BR pcap_set_rfmon (3PCAP) |
| 390 | set monitor mode for a not-yet-activated |
| 391 | .B pcap_t |
| 392 | for live capture |
| 393 | .TP |
| 394 | .BR pcap_can_set_rfmon (3PCAP) |
| 395 | determine whether monitor mode can be set for a |
| 396 | .B pcap_t |
| 397 | for live capture |
| 398 | .TP |
| 399 | .BR pcap_set_timeout (3PCAP) |
| 400 | set read timeout for a not-yet-activated |
| 401 | .B pcap_t |
| 402 | for live capture |
| 403 | .TP |
| 404 | .BR pcap_set_buffer_size (3PCAP) |
| 405 | set buffer size for a not-yet-activated |
| 406 | .B pcap_t |
| 407 | for live capture |
| 408 | .TP |
| 409 | .BR pcap_set_tstamp_type (3PCAP) |
| 410 | set time stamp type for a not-yet-activated |
| 411 | .B pcap_t |
| 412 | for live capture |
| 413 | .TP |
| 414 | .BR pcap_list_tstamp_types (3PCAP) |
| 415 | get list of available time stamp types for a not-yet-activated |
| 416 | .B pcap_t |
| 417 | for live capture |
| 418 | .TP |
| 419 | .BR pcap_free_tstamp_types (3PCAP) |
| 420 | free list of available time stamp types |
| 421 | .TP |
| 422 | .BR pcap_tstamp_type_val_to_name (3PCAP) |
| 423 | get name for a time stamp type |
| 424 | .TP |
| 425 | .BR pcap_tstamp_type_val_to_description (3PCAP) |
| 426 | get description for a time stamp type |
| 427 | .TP |
| 428 | .BR pcap_tstamp_name_to_val (3PCAP) |
| 429 | get time stamp type corresponding to a name |
| 430 | .TP |
| 431 | .BR pcap_datalink (3PCAP) |
| 432 | get link-layer header type for a |
| 433 | .B pcap_t |
| 434 | .TP |
| 435 | .BR pcap_file (3PCAP) |
| 436 | get the |
| 437 | .B "FILE\ *" |
| 438 | for a |
| 439 | .B pcap_t |
| 440 | opened for a ``savefile'' |
| 441 | .TP |
| 442 | .BR pcap_is_swapped (3PCAP) |
| 443 | determine whether a ``savefile'' being read came from a machine with the |
| 444 | opposite byte order |
| 445 | .TP |
| 446 | .BR pcap_major_version (3PCAP) |
| 447 | .PD 0 |
| 448 | .TP |
| 449 | .BR pcap_minor_version (3PCAP) |
| 450 | get the major and minor version of the file format version for a |
| 451 | ``savefile'' |
| 452 | .PD |
| 453 | .RE |
| 454 | .SS Selecting a link-layer header type for a live capture |
| 455 | Some devices may provide more than one link-layer header type. To |
| 456 | obtain a list of all link-layer header types provided by a device, call |
| 457 | .BR pcap_list_datalinks () |
| 458 | on an activated |
| 459 | .B pcap_t |
| 460 | for the device. |
| 461 | To free a list of link-layer header types, call |
| 462 | .BR pcap_free_datalinks (). |
| 463 | To set the link-layer header type for a device, call |
| 464 | .BR pcap_set_datalink (). |
| 465 | This should be done after the device has been activated but before any |
| 466 | packets are read and before any filters are compiled or installed. |
| 467 | .TP |
| 468 | .B Routines |
| 469 | .RS |
| 470 | .TP |
| 471 | .BR pcap_list_datalinks (3PCAP) |
| 472 | get a list of link-layer header types for a device |
| 473 | .TP |
| 474 | .BR pcap_free_datalinks (3PCAP) |
| 475 | free list of link-layer header types |
| 476 | .TP |
| 477 | .BR pcap_set_datalink (3PCAP) |
| 478 | set link-layer header type for a device |
| 479 | .TP |
| 480 | .BR pcap_datalink_val_to_name (3PCAP) |
| 481 | get name for a link-layer header type |
| 482 | .TP |
| 483 | .BR pcap_datalink_val_to_description (3PCAP) |
| 484 | get description for a link-layer header type |
| 485 | .TP |
| 486 | .BR pcap_datalink_name_to_val (3PCAP) |
| 487 | get link-layer header type corresponding to a name |
| 488 | .RE |
| 489 | .SS Reading packets |
| 490 | Packets are read with |
| 491 | .BR pcap_dispatch () |
| 492 | or |
| 493 | .BR pcap_loop (), |
| 494 | which process one or more packets, calling a callback routine for each |
| 495 | packet, or with |
| 496 | .BR pcap_next () |
| 497 | or |
| 498 | .BR pcap_next_ex (), |
| 499 | which return the next packet. |
| 500 | The callback for |
| 501 | .BR pcap_dispatch () |
| 502 | and |
| 503 | .BR pcap_loop () |
| 504 | is supplied a pointer to a |
| 505 | .IR "struct pcap_pkthdr" , |
| 506 | which includes the following members: |
| 507 | .RS |
| 508 | .TP |
| 509 | .B ts |
| 510 | a |
| 511 | .I struct timeval |
| 512 | containing the time when the packet was captured |
| 513 | .TP |
| 514 | .B caplen |
| 515 | a |
| 516 | .I bpf_u_int32 |
| 517 | giving the number of bytes of the packet that are available from the |
| 518 | capture |
| 519 | .TP |
| 520 | .B len |
| 521 | a |
| 522 | .I bpf_u_int32 |
| 523 | giving the length of the packet, in bytes (which might be more than the |
| 524 | number of bytes available from the capture, if the length of the packet |
| 525 | is larger than the maximum number of bytes to capture). |
| 526 | .RE |
| 527 | .PP |
| 528 | The callback is also supplied a |
| 529 | .I const u_char |
| 530 | pointer to the first |
| 531 | .B caplen |
| 532 | (as given in the |
| 533 | .I struct pcap_pkthdr |
| 534 | mentioned above) |
| 535 | bytes of data from the packet. This won't necessarily be the entire |
| 536 | packet; to capture the entire packet, you will have to provide a value |
| 537 | for |
| 538 | .I snaplen |
| 539 | in your call to |
| 540 | .BR pcap_set_snaplen () |
| 541 | that is sufficiently large to get all of the packet's data - a value of |
| 542 | 65535 should be sufficient on most if not all networks). When reading |
| 543 | from a ``savefile'', the snapshot length specified when the capture was |
| 544 | performed will limit the amount of packet data available. |
| 545 | .PP |
| 546 | .BR pcap_next () |
| 547 | is passed an argument that points to a |
| 548 | .I struct pcap_pkthdr |
| 549 | structure, and fills it in with the time stamp and length values for the |
| 550 | packet. It returns a |
| 551 | .I const u_char |
| 552 | to the first |
| 553 | .B caplen |
| 554 | bytes of the packet on success, and NULL on error. |
| 555 | .PP |
| 556 | .BR pcap_next_ex () |
| 557 | is passed two pointer arguments, one of which points to a |
| 558 | .IR struct pcap_pkthdr * |
| 559 | and one of which points to a |
| 560 | .IR "const u_char" *. |
| 561 | It sets the first pointer to point to a |
| 562 | .I struct pcap_pkthdr |
| 563 | structure with the time stamp and length values for the packet, and sets |
| 564 | the second pointer to point to the first |
| 565 | .B caplen |
| 566 | bytes of the packet. |
| 567 | .PP |
| 568 | To force the loop in |
| 569 | .BR pcap_dispatch () |
| 570 | or |
| 571 | .BR pcap_loop () |
| 572 | to terminate, call |
| 573 | .BR pcap_breakloop (). |
| 574 | .PP |
| 575 | By default, when reading packets from an interface opened for a live |
| 576 | capture, |
| 577 | .BR pcap_dispatch (), |
| 578 | .BR pcap_next (), |
| 579 | and |
| 580 | .BR pcap_next_ex () |
| 581 | will, if no packets are currently available to be read, block waiting |
| 582 | for packets to become available. On some, but |
| 583 | .I not |
| 584 | all, platforms, if a read timeout was specified, the wait will terminate |
| 585 | after the read timeout expires; applications should be prepared for |
| 586 | this, as it happens on some platforms, but should not rely on it, as it |
| 587 | does not happen on other platforms. |
| 588 | .PP |
| 589 | A handle can be put into ``non-blocking mode'', so that those routines |
| 590 | will, rather than blocking, return an indication that no packets are |
| 591 | available to read. Call |
| 592 | .BR pcap_setnonblock () |
| 593 | to put a handle into non-blocking mode or to take it out of non-blocking |
| 594 | mode; call |
| 595 | .BR pcap_getnonblock () |
| 596 | to determine whether a handle is in non-blocking mode. Note that |
| 597 | non-blocking mode does not work correctly in Mac OS X 10.6. |
| 598 | .PP |
| 599 | Non-blocking mode is often combined with routines such as |
| 600 | .BR select (2) |
| 601 | or |
| 602 | .BR poll (2) |
| 603 | or other routines a platform offers to wait for the availability of data |
| 604 | on any of a set of descriptors. To obtain, for a handle, a descriptor |
| 605 | that can be used in those routines, call |
| 606 | .BR pcap_get_selectable_fd (). |
| 607 | Not all handles have such a descriptor available; |
| 608 | .BR pcap_get_selectable_fd () |
| 609 | will return \-1 if no such descriptor exists. In addition, for various |
| 610 | reasons, one or more of those routines will not work properly with the |
| 611 | descriptor; the documentation for |
| 612 | .BR pcap_get_selectable_fd () |
| 613 | gives details. |
| 614 | .TP |
| 615 | .B Routines |
| 616 | .RS |
| 617 | .TP |
| 618 | .BR pcap_dispatch (3PCAP) |
| 619 | read a bufferful of packets from a |
| 620 | .B pcap_t |
| 621 | open for a live capture or the full set of packets from a |
| 622 | .B pcap_t |
| 623 | open for a ``savefile'' |
| 624 | .TP |
| 625 | .BR pcap_loop (3PCAP) |
| 626 | read packets from a |
| 627 | .B pcap_t |
| 628 | until an interrupt or error occurs |
| 629 | .TP |
| 630 | .BR pcap_next (3PCAP) |
| 631 | read the next packet from a |
| 632 | .B pcap_t |
| 633 | without an indication whether an error occurred |
| 634 | .TP |
| 635 | .BR pcap_next_ex (3PCAP) |
| 636 | read the next packet from a |
| 637 | .B pcap_t |
| 638 | with an error indication on an error |
| 639 | .TP |
| 640 | .BR pcap_breakloop (3PCAP) |
| 641 | prematurely terminate the loop in |
| 642 | .BR pcap_dispatch () |
| 643 | or |
| 644 | .BR pcap_loop () |
| 645 | .TP |
| 646 | .BR pcap_setnonblock (3PCAP) |
| 647 | set or clear non-blocking mode on a |
| 648 | .B pcap_t |
| 649 | .TP |
| 650 | .BR pcap_getnonblock (3PCAP) |
| 651 | get the state of non-blocking mode for a |
| 652 | .B pcap_t |
| 653 | .TP |
| 654 | .BR pcap_get_selectable_fd (3PCAP) |
| 655 | attempt to get a descriptor for a |
| 656 | .B pcap_t |
| 657 | that can be used in calls such as |
| 658 | .BR select (2) |
| 659 | and |
| 660 | .BR poll (2) |
| 661 | .RE |
| 662 | .SS Filters |
| 663 | In order to cause only certain packets to be returned when reading |
| 664 | packets, a filter can be set on a handle. For a live capture, the |
| 665 | filtering will be performed in kernel mode, if possible, to avoid |
| 666 | copying ``uninteresting'' packets from the kernel to user mode. |
| 667 | .PP |
| 668 | A filter can be specified as a text string; the syntax and semantics of |
| 669 | the string are as described by |
| 670 | .BR pcap-filter (@MAN_MISC_INFO@). |
| 671 | A filter string is compiled into a program in a pseudo-machine-language |
| 672 | by |
| 673 | .BR pcap_compile () |
| 674 | and the resulting program can be made a filter for a handle with |
| 675 | .BR pcap_setfilter (). |
| 676 | The result of |
| 677 | .BR pcap_compile () |
| 678 | can be freed with a call to |
| 679 | .BR pcap_freecode (). |
| 680 | .BR pcap_compile () |
| 681 | may require a network mask for certain expressions in the filter string; |
| 682 | .BR pcap_lookupnet () |
| 683 | can be used to find the network address and network mask for a given |
| 684 | capture device. |
| 685 | .PP |
| 686 | A compiled filter can also be applied directly to a packet that has been |
| 687 | read using |
| 688 | .BR pcap_offline_filter (). |
| 689 | .TP |
| 690 | .B Routines |
| 691 | .RS |
| 692 | .TP |
| 693 | .BR pcap_compile (3PCAP) |
| 694 | compile filter expression to a pseudo-machine-language code program |
| 695 | .TP |
| 696 | .BR pcap_freecode (3PCAP) |
| 697 | free a filter program |
| 698 | .TP |
| 699 | .BR pcap_setfilter (3PCAP) |
| 700 | set filter for a |
| 701 | .B pcap_t |
| 702 | .TP |
| 703 | .BR pcap_lookupnet (3PCAP) |
| 704 | get network address and network mask for a capture device |
| 705 | .TP |
| 706 | .BR pcap_offline_filter (3PCAP) |
| 707 | apply a filter program to a packet |
| 708 | .RE |
| 709 | .SS Incoming and outgoing packets |
| 710 | By default, libpcap will attempt to capture both packets sent by the |
| 711 | machine and packets received by the machine. To limit it to capturing |
| 712 | only packets received by the machine or, if possible, only packets sent |
| 713 | by the machine, call |
| 714 | .BR pcap_setdirection (). |
| 715 | .TP |
| 716 | .BR Routines |
| 717 | .RS |
| 718 | .TP |
| 719 | .BR pcap_setdirection (3PCAP) |
| 720 | specify whether to capture incoming packets, outgoing packets, or both |
| 721 | .RE |
| 722 | .SS Capture statistics |
| 723 | To get statistics about packets received and dropped in a live capture, |
| 724 | call |
| 725 | .BR pcap_stats (). |
| 726 | .TP |
| 727 | .B Routines |
| 728 | .RS |
| 729 | .TP |
| 730 | .BR pcap_stats (3PCAP) |
| 731 | get capture statistics |
| 732 | .RE |
| 733 | .SS Opening a handle for writing captured packets |
| 734 | To open a ``savefile`` to which to write packets, given the pathname the |
| 735 | ``savefile'' should have, call |
| 736 | .BR pcap_dump_open (). |
| 737 | To open a ``savefile`` to which to write packets, given the pathname the |
| 738 | ``savefile'' should have, call |
| 739 | .BR pcap_dump_open (); |
| 740 | to set up a handle for a ``savefile'', given a |
| 741 | .B "FILE\ *" |
| 742 | referring to a file already opened for writing, call |
| 743 | .BR pcap_dump_fopen (). |
| 744 | They each return pointers to a |
| 745 | .BR pcap_dumper_t , |
| 746 | which is the handle used for writing packets to the ``savefile''. If it |
| 747 | succeeds, it will have created the file if it doesn't exist and |
| 748 | truncated the file if it does exist. |
| 749 | To close a |
| 750 | .BR pcap_dumper_t , |
| 751 | call |
| 752 | .BR pcap_dump_close (). |
| 753 | .TP |
| 754 | .B Routines |
| 755 | .RS |
| 756 | .TP |
| 757 | .BR pcap_dump_open (3PCAP) |
| 758 | open a |
| 759 | .B pcap_dumper_t |
| 760 | for a ``savefile``, given a pathname |
| 761 | .TP |
| 762 | .BR pcap_dump_fopen (3PCAP) |
| 763 | open a |
| 764 | .B pcap_dumper_t |
| 765 | for a ``savefile``, given a |
| 766 | .B "FILE\ *" |
| 767 | .TP |
| 768 | .BR pcap_dump_close (3PCAP) |
| 769 | close a |
| 770 | .B pcap_dumper_t |
| 771 | .TP |
| 772 | .BR pcap_dump_file (3PCAP) |
| 773 | get the |
| 774 | .B "FILE\ *" |
| 775 | for a |
| 776 | .B pcap_dumper_t |
| 777 | opened for a ``savefile'' |
| 778 | .RE |
| 779 | .SS Writing packets |
| 780 | To write a packet to a |
| 781 | .BR pcap_dumper_t , |
| 782 | call |
| 783 | .BR pcap_dump (). |
| 784 | Packets written with |
| 785 | .BR pcap_dump () |
| 786 | may be buffered, rather than being immediately written to the |
| 787 | ``savefile''. Closing the |
| 788 | .B pcap_dumper_t |
| 789 | will cause all buffered-but-not-yet-written packets to be written to the |
| 790 | ``savefile''. |
| 791 | To force all packets written to the |
| 792 | .BR pcap_dumper_t , |
| 793 | and not yet written to the ``savefile'' because they're buffered by the |
| 794 | .BR pcap_dumper_t , |
| 795 | to be written to the ``savefile'', without closing the |
| 796 | .BR pcap_dumper_t , |
| 797 | call |
| 798 | .BR pcap_dump_flush (). |
| 799 | .TP |
| 800 | .B Routines |
| 801 | .RS |
| 802 | .TP |
| 803 | .BR pcap_dump (3PCAP) |
| 804 | write packet to a |
| 805 | .B pcap_dumper_t |
| 806 | .TP |
| 807 | .BR pcap_dump_flush (3PCAP) |
| 808 | flush buffered packets written to a |
| 809 | .B pcap_dumper_t |
| 810 | to the ``savefile'' |
| 811 | .TP |
| 812 | .BR pcap_dump_ftell (3PCAP) |
| 813 | get current file position for a |
| 814 | .B pcap_dumper_t |
| 815 | .RE |
| 816 | .SS Injecting packets |
| 817 | If you have the required privileges, you can inject packets onto a |
| 818 | network with a |
| 819 | .B pcap_t |
| 820 | for a live capture, using |
| 821 | .BR pcap_inject () |
| 822 | or |
| 823 | .BR pcap_sendpacket (). |
| 824 | (The two routines exist for compatibility with both OpenBSD and WinPcap; |
| 825 | they perform the same function, but have different return values.) |
| 826 | .TP |
| 827 | .B Routines |
| 828 | .RS |
| 829 | .TP |
| 830 | .BR pcap_inject (3PCAP) |
| 831 | .PD 0 |
| 832 | .TP |
| 833 | .BR pcap_sendpacket (3PCAP) |
| 834 | transmit a packet |
| 835 | .PD |
| 836 | .RE |
| 837 | .SS Reporting errors |
| 838 | Some routines return error or warning status codes; to convert them to a |
| 839 | string, use |
| 840 | .BR pcap_statustostr (). |
| 841 | .TP |
| 842 | .B Routines |
| 843 | .RS |
| 844 | .TP |
| 845 | .BR pcap_statustostr (3PCAP) |
| 846 | get a string for an error or warning status code |
| 847 | .RE |
| 848 | .SS Getting library version information |
| 849 | To get a string giving version information about libpcap, call |
| 850 | .BR pcap_library_version (). |
| 851 | .TP |
| 852 | .B Routines |
| 853 | .RS |
| 854 | .TP |
| 855 | .BR pcap_library_version (3PCAP) |
| 856 | get library version string |
| 857 | .RE |
| 858 | .SH BACKWARDS COMPATIBILITY |
| 859 | .PP |
| 860 | In versions of libpcap prior to 1.0, the |
| 861 | .B pcap.h |
| 862 | header file was not in a |
| 863 | .B pcap |
| 864 | directory on most platforms; if you are writing an application that must |
| 865 | work on versions of libpcap prior to 1.0, include |
| 866 | .BR <pcap.h> , |
| 867 | which will include |
| 868 | .B <pcap/pcap.h> |
| 869 | for you, rather than including |
| 870 | .BR <pcap/pcap.h> . |
| 871 | .PP |
| 872 | .BR pcap_create () |
| 873 | and |
| 874 | .BR pcap_activate () |
| 875 | were not available in versions of libpcap prior to 1.0; if you are |
| 876 | writing an application that must work on versions of libpcap prior to |
| 877 | 1.0, either use |
| 878 | .BR pcap_open_live () |
| 879 | to get a handle for a live capture or, if you want to be able to use the |
| 880 | additional capabilities offered by using |
| 881 | .BR pcap_create () |
| 882 | and |
| 883 | .BR pcap_activate (), |
| 884 | use an |
| 885 | .BR autoconf (1) |
| 886 | script or some other configuration script to check whether the libpcap |
| 887 | 1.0 APIs are available and use them only if they are. |
| 888 | .SH SEE ALSO |
| 889 | autoconf(1), tcpdump(1), tcpslice(1), pcap-filter(@MAN_MISC_INFO@), pfconfig(8), |
| 890 | usermod(1M) |
| 891 | .SH AUTHORS |
| 892 | The original authors of libpcap are: |
| 893 | .LP |
| 894 | Van Jacobson, |
| 895 | Craig Leres and |
| 896 | Steven McCanne, all of the |
| 897 | Lawrence Berkeley National Laboratory, University of California, Berkeley, CA. |
| 898 | .LP |
| 899 | The current version is available from "The Tcpdump Group"'s Web site at |
| 900 | .LP |
| 901 | .RS |
| 902 | .I http://www.tcpdump.org/ |
| 903 | .RE |
| 904 | .SH BUGS |
| 905 | Please send problems, bugs, questions, desirable enhancements, etc. to: |
| 906 | .LP |
| 907 | .RS |
| 908 | tcpdump-workers@lists.tcpdump.org |
| 909 | .RE |