1 .\" @(#) $Header: /tcpdump/master/libpcap/pcap.3,v 1.64 2004/12/17 21:27:54 guy Exp $
3 .\" Copyright (c) 1994, 1996, 1997
4 .\" The Regents of the University of California. All rights reserved.
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.
24 .TH PCAP 3 "27 February 2004"
26 pcap \- Packet Capture library
35 char errbuf[PCAP_ERRBUF_SIZE];
39 pcap_t *pcap_open_live(const char *device, int snaplen,
41 int promisc, int to_ms, char *errbuf)
42 pcap_t *pcap_open_dead(int linktype, int snaplen)
43 pcap_t *pcap_open_offline(const char *fname, char *errbuf)
44 pcap_t *pcap_fopen_offline(FILE *fp, char *errbuf)
45 pcap_dumper_t *pcap_dump_open(pcap_t *p, const char *fname)
46 pcap_dumper_t *pcap_dump_fopen(pcap_t *p, FILE *fp)
50 int pcap_setnonblock(pcap_t *p, int nonblock, char *errbuf);
51 int pcap_getnonblock(pcap_t *p, char *errbuf);
55 int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf)
56 void pcap_freealldevs(pcap_if_t *alldevs)
57 char *pcap_lookupdev(char *errbuf)
58 int pcap_lookupnet(const char *device, bpf_u_int32 *netp,
60 bpf_u_int32 *maskp, char *errbuf)
64 int pcap_dispatch(pcap_t *p, int cnt,
66 pcap_handler callback, u_char *user)
67 int pcap_loop(pcap_t *p, int cnt,
69 pcap_handler callback, u_char *user)
70 void pcap_dump(u_char *user, struct pcap_pkthdr *h,
76 int pcap_compile(pcap_t *p, struct bpf_program *fp,
78 char *str, int optimize, bpf_u_int32 netmask)
79 int pcap_setfilter(pcap_t *p, struct bpf_program *fp)
80 void pcap_freecode(struct bpf_program *);
84 const u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)
85 int pcap_next_ex(pcap_t *p, struct pcap_pkthdr **pkt_header,
87 const u_char **pkt_data)
91 void pcap_breakloop(pcap_t *)
95 int pcap_inject(pcap_t *p, const void *buf, size_t size)
96 int pcap_sendpacket(pcap_t *p, const u_char *buf, int size)
100 int pcap_datalink(pcap_t *p)
101 int pcap_list_datalinks(pcap_t *p, int **dlt_buf);
102 int pcap_set_datalink(pcap_t *p, int dlt);
103 int pcap_datalink_name_to_val(const char *name);
104 const char *pcap_datalink_val_to_name(int dlt);
105 const char *pcap_datalink_val_to_description(int dlt);
106 int pcap_snapshot(pcap_t *p)
107 int pcap_is_swapped(pcap_t *p)
108 int pcap_major_version(pcap_t *p)
109 int pcap_minor_version(pcap_t *p)
110 int pcap_stats(pcap_t *p, struct pcap_stat *ps)
111 FILE *pcap_file(pcap_t *p)
112 int pcap_fileno(pcap_t *p)
113 int pcap_get_selectable_fd(pcap_t *p);
114 void pcap_perror(pcap_t *p, char *prefix)
115 char *pcap_geterr(pcap_t *p)
116 char *pcap_strerror(int error)
117 const char *pcap_lib_version(void)
121 void pcap_close(pcap_t *p)
122 int pcap_dump_flush(pcap_dumper_t *p)
123 FILE *pcap_dump_file(pcap_dumper_t *p)
124 void pcap_dump_close(pcap_dumper_t *p)
128 The Packet Capture library
129 provides a high level interface to packet capture systems. All packets
130 on the network, even those destined for other hosts, are accessible
131 through this mechanism.
137 .BR pcap_open_live() ,
138 .BR pcap_open_dead() ,
139 .BR pcap_open_offline() ,
140 .BR pcap_fopen_offline() ,
141 .BR pcap_setnonblock() ,
142 .BR pcap_getnonblock() ,
143 .BR pcap_findalldevs() ,
144 .BR pcap_lookupdev() ,
147 is assumed to be able to hold at least
152 is used to obtain a packet capture descriptor to look
153 at packets on the network.
155 is a string that specifies the network device to open; on Linux systems
156 with 2.2 or later kernels, a
160 can be used to capture packets from all interfaces.
162 specifies the maximum number of bytes to capture. If this value is less
163 than the size of a packet that is captured, only the first
165 bytes of that packet will be captured and provided as packet data. A
166 value of 65535 should be sufficient, on most if not all networks, to
167 capture all the data available from the packet.
169 specifies if the interface is to be put into promiscuous mode.
170 (Note that even if this parameter is false, the interface
171 could well be in promiscuous mode for some other reason.) For now, this
172 doesn't work on the "any" device; if an argument of "any" or NULL is
177 specifies the read timeout in milliseconds. The read timeout is used to
178 arrange that the read not necessarily return immediately when a packet
179 is seen, but that it wait for some amount of time to allow more packets
180 to arrive and to read multiple packets from the OS kernel in one
181 operation. Not all platforms support a read timeout; on platforms that
182 don't, the read timeout is ignored. A zero value for
184 on platforms that support a read timeout,
185 will cause a read to wait forever to allow enough packets to
186 arrive, with no timeout.
188 is used to return error or warning text. It will be set to error text when
193 may also be set to warning text when
195 succeds; to detect this case the caller should store a zero-length string in
199 and display the warning to the user if
201 is no longer a zero-length string.
204 is used for creating a
206 structure to use when calling the other functions in libpcap. It is
207 typically used when just using libpcap for compiling BPF code.
209 .B pcap_open_offline()
210 is called to open a ``savefile'' for reading.
212 specifies the name of the file to open. The file has
213 the same format as those used by
217 The name "-" in a synonym for
219 Alternatively, you may call
220 .B pcap_fopen_offline()
221 to read dumped data from an existing open stream
223 Note that on Windows, that stream should be opened in binary mode.
225 is used to return error text and is only set when
226 .B pcap_open_offline()
228 .B pcap_fopen_offline()
233 is called to open a ``savefile'' for writing. The name "-" in a synonym
237 is returned on failure.
241 struct as returned by
242 .B pcap_open_offline()
244 .BR pcap_open_live() .
246 specifies the name of the file to open. Alternatively, you may call
248 to write data to an existing open stream
250 Note that on Windows, that stream should be opened in binary mode.
255 can be used to get the error text.
258 .B pcap_setnonblock()
259 puts a capture descriptor, opened with
260 .BR pcap_open_live() ,
261 into ``non-blocking'' mode, or takes it out of ``non-blocking'' mode,
262 depending on whether the
264 argument is non-zero or zero. It has no effect on ``savefiles''.
265 If there is an error, \-1 is returned and
267 is filled in with an appropriate error message; otherwise, 0 is
270 ``non-blocking'' mode, an attempt to read from the capture descriptor
273 will, if no packets are currently available to be read, return 0
274 immediately rather than blocking waiting for packets to arrive.
278 will not work in ``non-blocking'' mode.
280 .B pcap_getnonblock()
281 returns the current ``non-blocking'' state of the capture descriptor; it
282 always returns 0 on ``savefiles''.
283 If there is an error, \-1 is returned and
285 is filled in with an appropriate error message.
287 .B pcap_findalldevs()
288 constructs a list of network devices that can be opened with
289 .BR pcap_open_live() .
290 (Note that there may be network devices that cannot be opened with
294 .BR pcap_findalldevs() ,
295 because, for example, that process might not have sufficient privileges
296 to open them for capturing; if so, those devices will not appear on the
299 is set to point to the first element of the list; each element of the
302 and has the following members:
308 a pointer to the next element in the list;
310 for the last element of the list
313 a pointer to a string giving a name for the device to pass to
319 a pointer to a string giving a human-readable description of the device
322 a pointer to the first element of a list of addresses for the interface
329 set if the interface is a loopback interface
333 Each element of the list of addresses is of type
335 and has the following members:
341 a pointer to the next element in the list;
343 for the last element of the list
348 containing an address
355 that contains the netmask corresponding to the address pointed to by
363 that contains the broadcast address corresponding to the address pointed
366 may be null if the interface doesn't support broadcasts
373 that contains the destination address corresponding to the address pointed
376 may be null if the interface isn't a point-to-point interface
379 Note that not all the addresses in the list of addresses are
380 necessarily IPv4 or IPv6 addresses - you must check the
384 before interpreting the contents of the address.
387 is returned on failure, in which case
389 is filled in with an appropriate error message;
391 is returned on success.
393 .B pcap_freealldevs()
394 is used to free a list allocated by
395 .BR pcap_findalldevs() .
398 returns a pointer to a network device suitable for use with
401 .BR pcap_lookupnet() .
402 If there is an error,
406 is filled in with an appropriate error message.
409 is used to determine the network number and mask
410 associated with the network device
419 A return of \-1 indicates an error in which case
421 is filled in with an appropriate error message.
424 is used to collect and process packets.
426 specifies the maximum number of packets to process before returning.
427 This is not a minimum number; when reading a live capture, only one
428 bufferful of packets is read at a time, so fewer than
430 packets may be processed. A
432 of \-1 processes all the packets received in one buffer when reading a
433 live capture, or all the packets in the file when reading a
436 specifies a routine to be called with three arguments:
439 pointer which is passed in from
440 .BR pcap_dispatch() ,
442 .I const struct pcap_pkthdr
443 pointer to a structure with the following members:
449 containing the time when the packet was captured
454 giving the number of bytes of the packet that are available from the
460 giving the length of the packet, in bytes (which might be more than the
461 number of bytes available from the capture, if the length of the packet
462 is larger than the maximum number of bytes to capture)
470 .I struct pcap_pkthdr
471 a pointer to which is passed to the callback routine)
472 bytes of data from the packet (which won't necessarily be the entire
473 packet; to capture the entire packet, you will have to provide a value
478 that is sufficiently large to get all of the packet's data - a value of
479 65535 should be sufficient on most if not all networks).
481 The number of packets read is returned.
482 0 is returned if no packets were read from a live capture (if, for
483 example, they were discarded because they didn't pass the packet filter,
484 or if, on platforms that support a read timeout that starts before any
485 packets arrive, the timeout expires before any packets arrive, or if the
486 file descriptor for the capture device is in non-blocking mode and no
487 packets were available to be read) or if no more packets are available
488 in a ``savefile.'' A return of \-1 indicates
489 an error in which case
493 may be used to display the error text.
494 A return of \-2 indicates that the loop terminated due to a call to
496 before any packets were processed.
498 If your application uses pcap_breakloop(),
499 make sure that you explicitly check for \-1 and \-2, rather than just
500 checking for a return value < 0.
504 when reading a live capture,
506 will not necessarily return when the read times out; on some platforms,
507 the read timeout isn't supported, and, on other platforms, the timer
508 doesn't start until at least one packet arrives. This means that the
511 be used in, for example, an interactive application, to allow the packet
512 capture loop to ``poll'' for user input periodically, as there's no
515 will return after the timeout expires.
520 except it keeps reading packets until
522 packets are processed or an error occurs.
525 return when live read timeouts occur.
526 Rather, specifying a non-zero read timeout to
530 allows the reception and processing of any packets that arrive when the
536 to loop forever (or at least until an error occurs). \-1 is returned on
537 an error; 0 is returned if
539 is exhausted; \-2 is returned if the loop terminated due to a call to
541 before any packets were processed.
543 If your application uses pcap_breakloop(),
544 make sure that you explicitly check for \-1 and \-2, rather than just
545 checking for a return value < 0.
549 reads the next packet (by calling
555 pointer to the data in that packet. (The
557 struct for that packet is not supplied.)
559 is returned if an error occured, or if no packets were read from a live
560 capture (if, for example, they were discarded because they didn't pass
561 the packet filter, or if, on platforms that support a read timeout that
562 starts before any packets arrive, the timeout expires before any packets
563 arrive, or if the file descriptor for the capture device is in
564 non-blocking mode and no packets were available to be read), or if no
565 more packets are available in a ``savefile.'' Unfortunately, there is
566 no way to determine whether an error occured or not.
569 reads the next packet and returns a success/failure indication:
573 the packet was read without problems
576 packets are being read from a live capture, and the timeout expired
579 an error occurred while reading the packet
582 packets are being read from a ``savefile'', and there are no more
583 packets to read from the savefile.
586 If the packet was read without problems, the pointer pointed to by the
588 argument is set to point to the
590 struct for the packet, and the
591 pointer pointed to by the
593 argument is set to point to the data in the packet.
596 sets a flag that will force
600 to return rather than looping; they will return the number of packets
601 that have been processed so far, or \-2 if no packets have been
604 This routine is safe to use inside a signal handler on UNIX or a console
605 control handler on Windows, as it merely sets a flag that is checked
608 The flag is checked in loops reading packets from the OS - a signal by
609 itself will not necessarily terminate those loops - as well as in loops
610 processing a set of packets returned by the OS.
612 Note that if you are catching signals on UNIX systems that support
613 restarting system calls after a signal, and calling pcap_breakloop()
614 in the signal handler, you must specify, when catching those signals,
615 that system calls should NOT be restarted by that signal. Otherwise,
616 if the signal interrupted a call reading packets in a live capture,
617 when your signal handler returns after calling pcap_breakloop(), the
618 call will be restarted, and the loop will not terminate until more
619 packets arrive and the call completes.
621 Note also that, in a multi-threaded application, if one thread is
623 .BR pcap_dispatch() ,
630 in a different thread will not unblock that thread; you will need to use
631 whatever mechanism the OS provides for breaking a thread out of blocking
632 calls in order to unblock the thread, such as thread cancellation in
633 systems that support POSIX threads.
638 will, on some platforms, loop reading packets from the OS; that loop
639 will not necessarily be terminated by a signal, so
641 should be used to terminate packet processing even if
646 does not guarantee that no further packets will be processed by
650 after it is called; at most one more packet might be processed.
652 If \-2 is returned from
656 the flag is cleared, so a subsequent call will resume reading packets.
657 If a positive number is returned, the flag is not cleared, so a
658 subsequent call will return \-2 and clear the flag.
661 sends a raw packet through the network interface;
663 points to the data of the packet, including the link-layer header, and
665 is the number of bytes in the packet.
666 It returns the number of bytes written on success. A return of \-1
667 indicates an error in which case
671 may be used to display the error text.
672 Note that, even if you successfully open the network interface, you
673 might not have permission to send packets on it, or it might not support
676 doesn't have a flag to indicate whether to open for capturing, sending,
677 or capturing and sending, you cannot request an open that supports
678 sending and be notified at open time whether sending will be possible.
679 Note also that some devices might not support sending packets.
681 Note that, on some platforms, the link-layer header of the packet that's
682 sent might not be the same as the link-layer header of the packet
685 as the source link-layer address, if the header contains such an
686 address, might be changed to be the address assigned to the interface on
687 which the packet it sent, if the platform doesn't support sending
688 completely raw and unchanged packets.
693 but it returns 0 on success and \-1 on failure.
697 comes from WinPcap. Both are provided for compatibility.)
700 outputs a packet to the ``savefile'' opened with
701 .BR pcap_dump_open() .
702 Note that its calling arguments are suitable for use with
706 If called directly, the
711 .BR pcap_dump_open() .
714 is used to compile the string
716 into a filter program.
720 struct and is filled in by
723 controls whether optimization on the resulting code is performed.
725 specifies the IPv4 netmask of the network on which packets are being
726 captured; it is used only when checking for IPv4 broadcast addresses in
727 the filter program. If the netmask of the network on which packets are
728 being captured isn't known to the program, or if packets are being
729 captured on the Linux "any" pseudo-interface that can capture on more
730 than one network, a value of 0 can be supplied; tests for IPv4 broadcast
731 addreses won't be done correctly, but all other tests in the filter
732 program will be OK. A return of \-1 indicates an error in which case
734 may be used to display the error text.
736 .B pcap_compile_nopcap()
739 except that instead of passing a pcap structure, one passes the
740 snaplen and linktype explicitly. It is intended to be used for
741 compiling filters for direct BPF usage, without necessarily having
744 A return of \-1 indicates an error; the error text is unavailable.
745 .RB ( pcap_compile_nopcap()
747 .BR pcap_open_dead() ,
751 the latter three routines can be used directly in order to get the error
752 text for a compilation error.)
756 is used to specify a filter program.
760 struct, usually the result of a call to
763 is returned on failure, in which case
765 may be used to display the error text;
767 is returned on success.
770 is used to free up allocated memory pointed to by a
774 when that BPF program is no longer needed, for example after it
775 has been made the filter program for a pcap structure by a call to
776 .BR pcap_setfilter() .
779 returns the link layer type; link layer types it can return include:
784 BSD loopback encapsulation; the link layer header is a 4-byte field, in
786 byte order, containing a PF_ value from
788 for the network-layer protocol of the packet.
790 Note that ``host byte order'' is the byte order of the machine on which
791 the packets are captured, and the PF_ values are for the OS of the
792 machine on which the packets are captured; if a live capture is being
793 done, ``host byte order'' is the byte order of the machine capturing the
794 packets, and the PF_ values are those of the OS of the machine capturing
795 the packets, but if a ``savefile'' is being read, the byte order and PF_
798 necessarily those of the machine reading the capture file.
801 Ethernet (10Mb, 100Mb, 1000Mb, and up)
804 IEEE 802.5 Token Ring
810 SLIP; the link layer header contains, in order:
813 a 1-byte flag, which is 0 for packets received by the machine and 1 for
814 packets sent by the machine;
816 a 1-byte field, the upper 4 bits of which indicate the type of packet,
821 an unmodified IP datagram (TYPE_IP);
824 an uncompressed-TCP IP datagram (UNCOMPRESSED_TCP), with that byte being
825 the first byte of the raw IP header on the wire, containing the
826 connection number in the protocol field;
829 a compressed-TCP IP datagram (COMPRESSED_TCP), with that byte being the
830 first byte of the compressed TCP/IP datagram header;
833 for UNCOMPRESSED_TCP, the rest of the modified IP header, and for
834 COMPRESSED_TCP, the compressed TCP/IP datagram header;
838 for a total of 16 bytes; the uncompressed IP datagram follows the header.
842 PPP; if the first 2 bytes are 0xff and 0x03, it's PPP in HDLC-like
843 framing, with the PPP header following those two bytes, otherwise it's
844 PPP without framing, and the packet begins with the PPP header.
850 RFC 1483 LLC/SNAP-encapsulated ATM; the packet begins with an IEEE 802.2
854 raw IP; the packet begins with an IP header.
857 PPP in HDLC-like framing, as per RFC 1662, or Cisco PPP with HDLC
858 framing, as per section 4.3.1 of RFC 1547; the first byte will be 0xFF
859 for PPP in HDLC-like framing, and will be 0x0F or 0x8F for Cisco PPP
863 PPPoE; the packet begins with a PPPoE header, as per RFC 2516.
866 Cisco PPP with HDLC framing, as per section 4.3.1 of RFC 1547.
869 IEEE 802.11 wireless LAN
875 OpenBSD loopback encapsulation; the link layer header is a 4-byte field, in
877 byte order, containing a PF_ value from OpenBSD's
879 for the network-layer protocol of the packet.
881 Note that, if a ``savefile'' is being read, those PF_ values are
883 necessarily those of the machine reading the capture file.
886 Linux "cooked" capture encapsulation; the link layer header contains, in
890 a 2-byte "packet type", in network byte order, which is one of:
894 packet was sent to us by somebody else
897 packet was broadcast by somebody else
900 packet was multicast, but not broadcast, by somebody else
903 packet was sent by somebody else to somebody else
906 packet was sent by us
909 a 2-byte field, in network byte order, containing a Linux ARPHRD_ value
910 for the link layer device type;
912 a 2-byte field, in network byte order, containing the length of the
913 link layer address of the sender of the packet (which could be 0);
915 an 8-byte field containing that number of bytes of the link layer header
916 (if there are more than 8 bytes, only the first 8 are present);
918 a 2-byte field containing an Ethernet protocol type, in network byte
919 order, or containing 1 for Novell 802.3 frames without an 802.2 LLC
920 header or 4 for frames beginning with an 802.2 LLC header.
924 Apple LocalTalk; the packet begins with an AppleTalk LLAP header.
927 OpenBSD pflog; the link layer header contains, in order:
930 a 1-byte header length, in host byte order;
932 a 4-byte PF_ value, in host byte order;
934 a 2-byte action code, in network byte order, which is one of:
947 a 2-byte reason code, in network byte order, which is one of:
969 a 16-character interface name;
971 a 16-character ruleset name (only meaningful if subrule is set);
973 a 4-byte rule number, in network byte order;
975 a 4-byte subrule number, in network byte order;
977 a 1-byte direction, in network byte order, which is one of:
992 Prism monitor mode information followed by an 802.11 header.
995 RFC 2625 IP-over-Fibre Channel, with the link-layer header being the
996 Network_Header as described in that RFC.
999 SunATM devices; the link layer header contains, in order:
1002 a 1-byte flag field, containing a direction flag in the uppermost bit,
1003 which is set for packets transmitted by the machine and clear for
1004 packets received by the machine, and a 4-byte traffic type in the
1005 low-order 4 bits, which is one of:
1015 LLC-encapsulated traffic
1032 a 2-byte VCI field, in network byte order.
1035 .B DLT_IEEE802_11_RADIO
1036 link-layer information followed by an 802.11 header - see
1037 http://www.shaftnet.org/~pizza/software/capturefrm.txt for a description
1038 of the link-layer information.
1041 ARCNET, with no exception frames, reassembled packets rather than raw
1042 frames, and an extra 16-bit offset field between the destination host
1046 Linux-IrDA packets, with a
1048 header followed by the IrLAP header.
1051 .B pcap_list_datalinks()
1052 is used to get a list of the supported data link types of the interface
1053 associated with the pcap descriptor.
1054 .B pcap_list_datalinks()
1055 allocates an array to hold the list and sets
1057 The caller is responsible for freeing the array.
1059 is returned on failure;
1060 otherwise, the number of data link types in the array is returned.
1062 .B pcap_set_datalink()
1063 is used to set the current data link type of the pcap descriptor
1064 to the type specified by
1067 is returned on failure.
1069 .B pcap_datalink_name_to_val()
1070 translates a data link type name, which is a
1074 removed, to the corresponding data link type value. The translation
1075 is case-insensitive.
1077 is returned on failure.
1079 .B pcap_datalink_val_to_name()
1080 translates a data link type value to the corresponding data link type
1081 name. NULL is returned on failure.
1083 .B pcap_datalink_val_to_description()
1084 translates a data link type value to a short description of that data
1085 link type. NULL is returned on failure.
1087 .B pcap_list_datalinks()
1088 is used to get a list of the supported data link types of the interface
1089 associated with the pcap descriptor.
1090 .B pcap_list_datalinks()
1091 allocates an array to hold the list and sets
1093 The caller is responsible for freeing the array.
1095 is returned on failure;
1096 otherwise, the number of data link types in the array is returned.
1098 .B pcap_set_datalink()
1099 is used to set the current data link type of the pcap descriptor
1100 to the type specified by
1103 is returned on failure.
1106 returns the snapshot length specified when
1110 .B pcap_is_swapped()
1111 returns true if the current ``savefile'' uses a different byte order
1112 than the current system.
1114 .B pcap_major_version()
1115 returns the major number of the file format of the savefile;
1116 .B pcap_minor_version()
1117 returns the minor number of the file format of the savefile. The
1118 version number is stored in the header of the savefile.
1121 returns the standard I/O stream of the ``savefile,'' if a ``savefile''
1123 .BR pcap_open_offline() ,
1124 or NULL, if a network device was opened with
1125 .BR pcap_open_live() .
1128 returns 0 and fills in a
1130 struct. The values represent packet statistics from the start of the
1131 run to the time of the call. If there is an error or the underlying
1132 packet capture doesn't support packet statistics, \-1 is returned and
1133 the error text can be obtained with
1138 is supported only on live captures, not on ``savefiles''; no statistics
1139 are stored in ``savefiles'', so no statistics are available when reading
1140 from a ``savefile''.
1143 returns the file descriptor number from which captured packets are read,
1144 if a network device was opened with
1145 .BR pcap_open_live() ,
1146 or \-1, if a ``savefile'' was opened with
1147 .BR pcap_open_offline() .
1149 .B pcap_get_selectable_fd()
1150 returns, on UNIX, a file descriptor number for a file descriptor on
1156 to wait for it to be possible to read packets without blocking, if such
1157 a descriptor exists, or \-1, if no such descriptor exists. Some network
1164 (for example, regular network devices on FreeBSD 4.3 and 4.4, and Endace
1165 DAG devices), so \-1 is returned for those devices.
1167 Note that on most versions of most BSDs (including Mac OS X)
1171 do not work correctly on BPF devices;
1172 .B pcap_get_selectable_fd()
1173 will return a file descriptor on most of those versions (the exceptions
1174 being FreeBSD 4.3 and 4.4), a simple
1178 will not return even after a timeout specified in
1180 expires. To work around this, an application that uses
1184 to wait for packets to arrive must put the
1186 in non-blocking mode, and must arrange that the
1190 have a timeout less than or equal to the timeout specified in
1191 .BR pcap_open_live() ,
1192 and must try to read packets after that timeout expires, regardless of
1197 indicated that the file descriptor for the
1199 is ready to be read or not. (That workaround will not work in FreeBSD
1200 4.3 and later; however, in FreeBSD 4.6 and later,
1204 work correctly on BPF devices, so the workaround isn't necessary,
1205 although it does no harm.)
1207 .B pcap_get_selectable_fd()
1208 is not available on Windows.
1211 prints the text of the last pcap library error on
1217 returns the error text pertaining to the last pcap library error.
1219 the pointer it returns will no longer point to a valid error message
1222 passed to it is closed; you must use or copy the string before closing
1231 .B pcap_lib_version()
1232 returns a pointer to a string giving information about the version of
1233 the libpcap library being used; note that it contains more information
1234 than just a version number.
1237 closes the files associated with
1239 and deallocates resources.
1242 returns the standard I/O stream of the ``savefile'' opened by
1243 .BR pcap_dump_open().
1245 .B pcap_dump_flush()
1246 flushes the output buffer to the ``savefile,'' so that any packets
1249 but not yet written to the ``savefile'' will be written.
1251 is returned on error, 0 on success.
1253 .B pcap_dump_close()
1254 closes the ``savefile.''
1257 tcpdump(1), tcpslice(1)
1259 The original authors are:
1263 Steven McCanne, all of the
1264 Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.
1266 The current version is available from "The Tcpdump Group"'s Web site at
1269 .I http://www.tcpdump.org/
1272 Please send problems, bugs, questions, desirable enhancements, etc. to:
1275 tcpdump-workers@tcpdump.org
1278 Please send source code contributions, etc. to:
projects / FreeBSD / FreeBSD.git / blob