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