1 .\" @(#) $Header: /tcpdump/master/libpcap/pcap.3,v 1.64.2.11 2007/06/11 09:52:05 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.
22 .TH PCAP 3 "27 February 2004"
24 pcap \- Packet Capture library
33 char errbuf[PCAP_ERRBUF_SIZE];
37 pcap_t *pcap_open_live(const char *device, int snaplen,
39 int promisc, int to_ms, char *errbuf)
40 pcap_t *pcap_open_dead(int linktype, int snaplen)
41 pcap_t *pcap_open_offline(const char *fname, char *errbuf)
42 pcap_t *pcap_fopen_offline(FILE *fp, char *errbuf)
43 pcap_dumper_t *pcap_dump_open(pcap_t *p, const char *fname)
44 pcap_dumper_t *pcap_dump_fopen(pcap_t *p, FILE *fp)
48 int pcap_setnonblock(pcap_t *p, int nonblock, char *errbuf);
49 int pcap_getnonblock(pcap_t *p, char *errbuf);
53 int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf)
54 void pcap_freealldevs(pcap_if_t *alldevs)
55 char *pcap_lookupdev(char *errbuf)
56 int pcap_lookupnet(const char *device, bpf_u_int32 *netp,
58 bpf_u_int32 *maskp, char *errbuf)
62 typedef void (*pcap_handler)(u_char *user, const struct pcap_pkthdr *h,
66 int pcap_dispatch(pcap_t *p, int cnt,
68 pcap_handler callback, u_char *user)
69 int pcap_loop(pcap_t *p, int cnt,
71 pcap_handler callback, u_char *user)
72 void pcap_dump(u_char *user, struct pcap_pkthdr *h,
78 int pcap_compile(pcap_t *p, struct bpf_program *fp,
80 const char *str, int optimize, bpf_u_int32 netmask)
81 int pcap_setfilter(pcap_t *p, struct bpf_program *fp)
82 void pcap_freecode(struct bpf_program *)
83 int pcap_setdirection(pcap_t *p, pcap_direction_t d)
87 const u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)
88 int pcap_next_ex(pcap_t *p, struct pcap_pkthdr **pkt_header,
90 const u_char **pkt_data)
94 void pcap_breakloop(pcap_t *)
98 int pcap_inject(pcap_t *p, const void *buf, size_t size)
99 int pcap_sendpacket(pcap_t *p, const u_char *buf, int size)
103 int pcap_datalink(pcap_t *p)
104 int pcap_list_datalinks(pcap_t *p, int **dlt_buf);
105 int pcap_set_datalink(pcap_t *p, int dlt);
106 int pcap_datalink_name_to_val(const char *name);
107 const char *pcap_datalink_val_to_name(int dlt);
108 const char *pcap_datalink_val_to_description(int dlt);
109 int pcap_snapshot(pcap_t *p)
110 int pcap_is_swapped(pcap_t *p)
111 int pcap_major_version(pcap_t *p)
112 int pcap_minor_version(pcap_t *p)
113 int pcap_stats(pcap_t *p, struct pcap_stat *ps)
114 FILE *pcap_file(pcap_t *p)
115 int pcap_fileno(pcap_t *p)
116 int pcap_get_selectable_fd(pcap_t *p);
117 void pcap_perror(pcap_t *p, char *prefix)
118 char *pcap_geterr(pcap_t *p)
119 const char *pcap_strerror(int error)
120 const char *pcap_lib_version(void)
124 void pcap_close(pcap_t *p)
125 int pcap_dump_flush(pcap_dumper_t *p)
126 long pcap_dump_ftell(pcap_dumper_t *p)
127 FILE *pcap_dump_file(pcap_dumper_t *p)
128 void pcap_dump_close(pcap_dumper_t *p)
132 The Packet Capture library
133 provides a high level interface to packet capture systems. All packets
134 on the network, even those destined for other hosts, are accessible
135 through this mechanism.
141 .BR pcap_open_live() ,
142 .BR pcap_open_dead() ,
143 .BR pcap_open_offline() ,
144 .BR pcap_fopen_offline() ,
145 .BR pcap_setnonblock() ,
146 .BR pcap_getnonblock() ,
147 .BR pcap_findalldevs() ,
148 .BR pcap_lookupdev() ,
151 is assumed to be able to hold at least
156 is used to obtain a packet capture descriptor to look
157 at packets on the network.
159 is a string that specifies the network device to open; on Linux systems
160 with 2.2 or later kernels, a
164 can be used to capture packets from all interfaces.
166 specifies the maximum number of bytes to capture. If this value is less
167 than the size of a packet that is captured, only the first
169 bytes of that packet will be captured and provided as packet data. A
170 value of 65535 should be sufficient, on most if not all networks, to
171 capture all the data available from the packet.
173 specifies if the interface is to be put into promiscuous mode.
174 (Note that even if this parameter is false, the interface
175 could well be in promiscuous mode for some other reason.) For now, this
176 doesn't work on the "any" device; if an argument of "any" or NULL is
181 specifies the read timeout in milliseconds. The read timeout is used to
182 arrange that the read not necessarily return immediately when a packet
183 is seen, but that it wait for some amount of time to allow more packets
184 to arrive and to read multiple packets from the OS kernel in one
185 operation. Not all platforms support a read timeout; on platforms that
186 don't, the read timeout is ignored. A zero value for
188 on platforms that support a read timeout,
189 will cause a read to wait forever to allow enough packets to
190 arrive, with no timeout.
192 is used to return error or warning text. It will be set to error text when
197 may also be set to warning text when
199 succeds; to detect this case the caller should store a zero-length string in
203 and display the warning to the user if
205 is no longer a zero-length string.
208 is used for creating a
210 structure to use when calling the other functions in libpcap. It is
211 typically used when just using libpcap for compiling BPF code.
213 .B pcap_open_offline()
214 is called to open a ``savefile'' for reading.
216 specifies the name of the file to open. The file has
217 the same format as those used by
221 The name "-" in a synonym for
223 Alternatively, you may call
224 .B pcap_fopen_offline()
225 to read dumped data from an existing open stream
227 Note that on Windows, that stream should be opened in binary mode.
229 is used to return error text and is only set when
230 .B pcap_open_offline()
232 .B pcap_fopen_offline()
237 is called to open a ``savefile'' for writing. The name "-" in a synonym
241 is returned on failure.
245 struct as returned by
246 .B pcap_open_offline()
248 .BR pcap_open_live() .
250 specifies the name of the file to open. Alternatively, you may call
252 to write data to an existing open stream
254 Note that on Windows, that stream should be opened in binary mode.
259 can be used to get the error text.
262 .B pcap_setnonblock()
263 puts a capture descriptor, opened with
264 .BR pcap_open_live() ,
265 into ``non-blocking'' mode, or takes it out of ``non-blocking'' mode,
266 depending on whether the
268 argument is non-zero or zero. It has no effect on ``savefiles''.
269 If there is an error, \-1 is returned and
271 is filled in with an appropriate error message; otherwise, 0 is
274 ``non-blocking'' mode, an attempt to read from the capture descriptor
277 will, if no packets are currently available to be read, return 0
278 immediately rather than blocking waiting for packets to arrive.
282 will not work in ``non-blocking'' mode.
284 .B pcap_getnonblock()
285 returns the current ``non-blocking'' state of the capture descriptor; it
286 always returns 0 on ``savefiles''.
287 If there is an error, \-1 is returned and
289 is filled in with an appropriate error message.
291 .B pcap_findalldevs()
292 constructs a list of network devices that can be opened with
293 .BR pcap_open_live() .
294 (Note that there may be network devices that cannot be opened with
298 .BR pcap_findalldevs() ,
299 because, for example, that process might not have sufficient privileges
300 to open them for capturing; if so, those devices will not appear on the
303 is set to point to the first element of the list; each element of the
306 and has the following members:
312 a pointer to the next element in the list;
314 for the last element of the list
317 a pointer to a string giving a name for the device to pass to
323 a pointer to a string giving a human-readable description of the device
326 a pointer to the first element of a list of addresses for the interface
333 set if the interface is a loopback interface
337 Each element of the list of addresses is of type
339 and has the following members:
345 a pointer to the next element in the list;
347 for the last element of the list
352 containing an address
359 that contains the netmask corresponding to the address pointed to by
367 that contains the broadcast address corresponding to the address pointed
370 may be null if the interface doesn't support broadcasts
377 that contains the destination address corresponding to the address pointed
380 may be null if the interface isn't a point-to-point interface
383 Note that not all the addresses in the list of addresses are
384 necessarily IPv4 or IPv6 addresses - you must check the
388 before interpreting the contents of the address.
391 is returned on failure, in which case
393 is filled in with an appropriate error message;
395 is returned on success.
397 .B pcap_freealldevs()
398 is used to free a list allocated by
399 .BR pcap_findalldevs() .
402 returns a pointer to a network device suitable for use with
405 .BR pcap_lookupnet() .
406 If there is an error,
410 is filled in with an appropriate error message.
413 is used to determine the network number and mask
414 associated with the network device
423 A return of \-1 indicates an error in which case
425 is filled in with an appropriate error message.
428 is used to collect and process packets.
430 specifies the maximum number of packets to process before returning.
431 This is not a minimum number; when reading a live capture, only one
432 bufferful of packets is read at a time, so fewer than
434 packets may be processed. A
436 of \-1 processes all the packets received in one buffer when reading a
437 live capture, or all the packets in the file when reading a
440 specifies a routine to be called with three arguments:
443 pointer which is passed in from
444 .BR pcap_dispatch() ,
446 .I const struct pcap_pkthdr
447 pointer to a structure with the following members:
453 containing the time when the packet was captured
458 giving the number of bytes of the packet that are available from the
464 giving the length of the packet, in bytes (which might be more than the
465 number of bytes available from the capture, if the length of the packet
466 is larger than the maximum number of bytes to capture)
474 .I struct pcap_pkthdr
475 a pointer to which is passed to the callback routine)
476 bytes of data from the packet (which won't necessarily be the entire
477 packet; to capture the entire packet, you will have to provide a value
482 that is sufficiently large to get all of the packet's data - a value of
483 65535 should be sufficient on most if not all networks).
485 The number of packets read is returned.
486 0 is returned if no packets were read from a live capture (if, for
487 example, they were discarded because they didn't pass the packet filter,
488 or if, on platforms that support a read timeout that starts before any
489 packets arrive, the timeout expires before any packets arrive, or if the
490 file descriptor for the capture device is in non-blocking mode and no
491 packets were available to be read) or if no more packets are available
492 in a ``savefile.'' A return of \-1 indicates
493 an error in which case
497 may be used to display the error text.
498 A return of \-2 indicates that the loop terminated due to a call to
500 before any packets were processed.
502 If your application uses pcap_breakloop(),
503 make sure that you explicitly check for \-1 and \-2, rather than just
504 checking for a return value < 0.
508 when reading a live capture,
510 will not necessarily return when the read times out; on some platforms,
511 the read timeout isn't supported, and, on other platforms, the timer
512 doesn't start until at least one packet arrives. This means that the
515 be used in, for example, an interactive application, to allow the packet
516 capture loop to ``poll'' for user input periodically, as there's no
519 will return after the timeout expires.
524 except it keeps reading packets until
526 packets are processed or an error occurs.
529 return when live read timeouts occur.
530 Rather, specifying a non-zero read timeout to
534 allows the reception and processing of any packets that arrive when the
540 to loop forever (or at least until an error occurs). \-1 is returned on
541 an error; 0 is returned if
543 is exhausted; \-2 is returned if the loop terminated due to a call to
545 before any packets were processed.
547 If your application uses pcap_breakloop(),
548 make sure that you explicitly check for \-1 and \-2, rather than just
549 checking for a return value < 0.
553 reads the next packet (by calling
559 pointer to the data in that packet. (The
561 struct for that packet is not supplied.)
563 is returned if an error occured, or if no packets were read from a live
564 capture (if, for example, they were discarded because they didn't pass
565 the packet filter, or if, on platforms that support a read timeout that
566 starts before any packets arrive, the timeout expires before any packets
567 arrive, or if the file descriptor for the capture device is in
568 non-blocking mode and no packets were available to be read), or if no
569 more packets are available in a ``savefile.'' Unfortunately, there is
570 no way to determine whether an error occured or not.
573 reads the next packet and returns a success/failure indication:
577 the packet was read without problems
580 packets are being read from a live capture, and the timeout expired
583 an error occurred while reading the packet
586 packets are being read from a ``savefile'', and there are no more
587 packets to read from the savefile.
590 If the packet was read without problems, the pointer pointed to by the
592 argument is set to point to the
594 struct for the packet, and the
595 pointer pointed to by the
597 argument is set to point to the data in the packet.
600 sets a flag that will force
604 to return rather than looping; they will return the number of packets
605 that have been processed so far, or \-2 if no packets have been
608 This routine is safe to use inside a signal handler on UNIX or a console
609 control handler on Windows, as it merely sets a flag that is checked
612 The flag is checked in loops reading packets from the OS - a signal by
613 itself will not necessarily terminate those loops - as well as in loops
614 processing a set of packets returned by the OS.
616 Note that if you are catching signals on UNIX systems that support
617 restarting system calls after a signal, and calling pcap_breakloop()
618 in the signal handler, you must specify, when catching those signals,
619 that system calls should NOT be restarted by that signal. Otherwise,
620 if the signal interrupted a call reading packets in a live capture,
621 when your signal handler returns after calling pcap_breakloop(), the
622 call will be restarted, and the loop will not terminate until more
623 packets arrive and the call completes.
625 Note also that, in a multi-threaded application, if one thread is
627 .BR pcap_dispatch() ,
634 in a different thread will not unblock that thread; you will need to use
635 whatever mechanism the OS provides for breaking a thread out of blocking
636 calls in order to unblock the thread, such as thread cancellation in
637 systems that support POSIX threads.
642 will, on some platforms, loop reading packets from the OS; that loop
643 will not necessarily be terminated by a signal, so
645 should be used to terminate packet processing even if
650 does not guarantee that no further packets will be processed by
654 after it is called; at most one more packet might be processed.
656 If \-2 is returned from
660 the flag is cleared, so a subsequent call will resume reading packets.
661 If a positive number is returned, the flag is not cleared, so a
662 subsequent call will return \-2 and clear the flag.
665 sends a raw packet through the network interface;
667 points to the data of the packet, including the link-layer header, and
669 is the number of bytes in the packet.
670 It returns the number of bytes written on success. A return of \-1
671 indicates an error in which case
675 may be used to display the error text.
676 Note that, even if you successfully open the network interface, you
677 might not have permission to send packets on it, or it might not support
680 doesn't have a flag to indicate whether to open for capturing, sending,
681 or capturing and sending, you cannot request an open that supports
682 sending and be notified at open time whether sending will be possible.
683 Note also that some devices might not support sending packets.
685 Note that, on some platforms, the link-layer header of the packet that's
686 sent might not be the same as the link-layer header of the packet
689 as the source link-layer address, if the header contains such an
690 address, might be changed to be the address assigned to the interface on
691 which the packet it sent, if the platform doesn't support sending
692 completely raw and unchanged packets. Even worse, some drivers on some
693 platforms might change the link-layer type field to whatever value
694 libpcap used when attaching to the device, even on platforms that
696 nominally support sending completely raw and unchanged packets.
701 but it returns 0 on success and \-1 on failure.
705 comes from WinPcap. Both are provided for compatibility.)
708 outputs a packet to the ``savefile'' opened with
709 .BR pcap_dump_open() .
710 Note that its calling arguments are suitable for use with
714 If called directly, the
719 .BR pcap_dump_open() .
722 is used to compile the string
724 into a filter program.
728 struct and is filled in by
731 controls whether optimization on the resulting code is performed.
733 specifies the IPv4 netmask of the network on which packets are being
734 captured; it is used only when checking for IPv4 broadcast addresses in
735 the filter program. If the netmask of the network on which packets are
736 being captured isn't known to the program, or if packets are being
737 captured on the Linux "any" pseudo-interface that can capture on more
738 than one network, a value of 0 can be supplied; tests for IPv4 broadcast
739 addreses won't be done correctly, but all other tests in the filter
740 program will be OK. A return of \-1 indicates an error in which case
742 may be used to display the error text.
744 .B pcap_compile_nopcap()
747 except that instead of passing a pcap structure, one passes the
748 snaplen and linktype explicitly. It is intended to be used for
749 compiling filters for direct BPF usage, without necessarily having
752 A return of \-1 indicates an error; the error text is unavailable.
753 .RB ( pcap_compile_nopcap()
755 .BR pcap_open_dead() ,
759 the latter three routines can be used directly in order to get the error
760 text for a compilation error.)
764 is used to specify a filter program.
768 struct, usually the result of a call to
771 is returned on failure, in which case
773 may be used to display the error text;
775 is returned on success.
778 is used to free up allocated memory pointed to by a
782 when that BPF program is no longer needed, for example after it
783 has been made the filter program for a pcap structure by a call to
784 .BR pcap_setfilter() .
786 .B pcap_setdirection()
787 is used to specify a direction that packets will be captured.
789 is one of the constants
795 will only capture packets received by the device,
797 will only capture packets sent by the device and
799 will capture packets received by or sent by the device.
801 is the default setting if this function is not called. This isn't
802 necessarily supported on all platforms; some platforms might return an
803 error, and some other platforms might not support
805 This operation is not supported if a ``savefile'' is being read.
807 is returned on failure,
809 is returned on success.
812 returns the link layer type; link layer types it can return include:
817 BSD loopback encapsulation; the link layer header is a 4-byte field, in
819 byte order, containing a PF_ value from
821 for the network-layer protocol of the packet.
823 Note that ``host byte order'' is the byte order of the machine on which
824 the packets are captured, and the PF_ values are for the OS of the
825 machine on which the packets are captured; if a live capture is being
826 done, ``host byte order'' is the byte order of the machine capturing the
827 packets, and the PF_ values are those of the OS of the machine capturing
828 the packets, but if a ``savefile'' is being read, the byte order and PF_
831 necessarily those of the machine reading the capture file.
834 Ethernet (10Mb, 100Mb, 1000Mb, and up)
837 IEEE 802.5 Token Ring
843 SLIP; the link layer header contains, in order:
846 a 1-byte flag, which is 0 for packets received by the machine and 1 for
847 packets sent by the machine;
849 a 1-byte field, the upper 4 bits of which indicate the type of packet,
854 an unmodified IP datagram (TYPE_IP);
857 an uncompressed-TCP IP datagram (UNCOMPRESSED_TCP), with that byte being
858 the first byte of the raw IP header on the wire, containing the
859 connection number in the protocol field;
862 a compressed-TCP IP datagram (COMPRESSED_TCP), with that byte being the
863 first byte of the compressed TCP/IP datagram header;
866 for UNCOMPRESSED_TCP, the rest of the modified IP header, and for
867 COMPRESSED_TCP, the compressed TCP/IP datagram header;
871 for a total of 16 bytes; the uncompressed IP datagram follows the header.
875 PPP; if the first 2 bytes are 0xff and 0x03, it's PPP in HDLC-like
876 framing, with the PPP header following those two bytes, otherwise it's
877 PPP without framing, and the packet begins with the PPP header.
883 RFC 1483 LLC/SNAP-encapsulated ATM; the packet begins with an IEEE 802.2
887 raw IP; the packet begins with an IP header.
890 PPP in HDLC-like framing, as per RFC 1662, or Cisco PPP with HDLC
891 framing, as per section 4.3.1 of RFC 1547; the first byte will be 0xFF
892 for PPP in HDLC-like framing, and will be 0x0F or 0x8F for Cisco PPP
896 PPPoE; the packet begins with a PPPoE header, as per RFC 2516.
899 Cisco PPP with HDLC framing, as per section 4.3.1 of RFC 1547.
902 IEEE 802.11 wireless LAN
908 OpenBSD loopback encapsulation; the link layer header is a 4-byte field, in
910 byte order, containing a PF_ value from OpenBSD's
912 for the network-layer protocol of the packet.
914 Note that, if a ``savefile'' is being read, those PF_ values are
916 necessarily those of the machine reading the capture file.
919 Linux "cooked" capture encapsulation; the link layer header contains, in
923 a 2-byte "packet type", in network byte order, which is one of:
927 packet was sent to us by somebody else
930 packet was broadcast by somebody else
933 packet was multicast, but not broadcast, by somebody else
936 packet was sent by somebody else to somebody else
939 packet was sent by us
942 a 2-byte field, in network byte order, containing a Linux ARPHRD_ value
943 for the link layer device type;
945 a 2-byte field, in network byte order, containing the length of the
946 link layer address of the sender of the packet (which could be 0);
948 an 8-byte field containing that number of bytes of the link layer header
949 (if there are more than 8 bytes, only the first 8 are present);
951 a 2-byte field containing an Ethernet protocol type, in network byte
952 order, or containing 1 for Novell 802.3 frames without an 802.2 LLC
953 header or 4 for frames beginning with an 802.2 LLC header.
957 Apple LocalTalk; the packet begins with an AppleTalk LLAP header.
960 OpenBSD pflog; the link layer header contains, in order:
963 a 1-byte header length, in host byte order;
965 a 4-byte PF_ value, in host byte order;
967 a 2-byte action code, in network byte order, which is one of:
980 a 2-byte reason code, in network byte order, which is one of:
1002 a 16-character interface name;
1004 a 16-character ruleset name (only meaningful if subrule is set);
1006 a 4-byte rule number, in network byte order;
1008 a 4-byte subrule number, in network byte order;
1010 a 1-byte direction, in network byte order, which is one of:
1014 incoming or outgoing
1025 Prism monitor mode information followed by an 802.11 header.
1028 RFC 2625 IP-over-Fibre Channel, with the link-layer header being the
1029 Network_Header as described in that RFC.
1032 SunATM devices; the link layer header contains, in order:
1035 a 1-byte flag field, containing a direction flag in the uppermost bit,
1036 which is set for packets transmitted by the machine and clear for
1037 packets received by the machine, and a 4-byte traffic type in the
1038 low-order 4 bits, which is one of:
1048 LLC-encapsulated traffic
1065 a 2-byte VCI field, in network byte order.
1068 .B DLT_IEEE802_11_RADIO
1069 link-layer information followed by an 802.11 header - see
1070 http://www.shaftnet.org/~pizza/software/capturefrm.txt for a description
1071 of the link-layer information.
1074 ARCNET, with no exception frames, reassembled packets rather than raw
1075 frames, and an extra 16-bit offset field between the destination host
1079 Linux-IrDA packets, with a
1081 header followed by the IrLAP header.
1084 LAPD (Q.921) frames, with a
1086 header captured via vISDN.
1089 .B pcap_list_datalinks()
1090 is used to get a list of the supported data link types of the interface
1091 associated with the pcap descriptor.
1092 .B pcap_list_datalinks()
1093 allocates an array to hold the list and sets
1095 The caller is responsible for freeing the array.
1097 is returned on failure;
1098 otherwise, the number of data link types in the array is returned.
1100 .B pcap_set_datalink()
1101 is used to set the current data link type of the pcap descriptor
1102 to the type specified by
1105 is returned on failure.
1107 .B pcap_datalink_name_to_val()
1108 translates a data link type name, which is a
1112 removed, to the corresponding data link type value. The translation
1113 is case-insensitive.
1115 is returned on failure.
1117 .B pcap_datalink_val_to_name()
1118 translates a data link type value to the corresponding data link type
1119 name. NULL is returned on failure.
1121 .B pcap_datalink_val_to_description()
1122 translates a data link type value to a short description of that data
1123 link type. NULL is returned on failure.
1126 returns the snapshot length specified when
1130 .B pcap_is_swapped()
1131 returns true if the current ``savefile'' uses a different byte order
1132 than the current system.
1134 .B pcap_major_version()
1135 returns the major number of the file format of the savefile;
1136 .B pcap_minor_version()
1137 returns the minor number of the file format of the savefile. The
1138 version number is stored in the header of the savefile.
1141 returns the standard I/O stream of the ``savefile,'' if a ``savefile''
1143 .BR pcap_open_offline() ,
1144 or NULL, if a network device was opened with
1145 .BR pcap_open_live() .
1148 returns 0 and fills in the
1150 structure pointed to by its second argument. The values represent
1151 packet statistics from the start of the run to the time of the call. If
1152 there is an error or the underlying packet capture doesn't support
1153 packet statistics, \-1 is returned and the error text can be obtained
1159 is supported only on live captures, not on ``savefiles''; no statistics
1160 are stored in ``savefiles'', so no statistics are available when reading
1161 from a ``savefile''.
1164 returns the file descriptor number from which captured packets are read,
1165 if a network device was opened with
1166 .BR pcap_open_live() ,
1167 or \-1, if a ``savefile'' was opened with
1168 .BR pcap_open_offline() .
1170 .B pcap_get_selectable_fd()
1171 returns, on UNIX, a file descriptor number for a file descriptor on
1177 to wait for it to be possible to read packets without blocking, if such
1178 a descriptor exists, or \-1, if no such descriptor exists. Some network
1185 (for example, regular network devices on FreeBSD 4.3 and 4.4, and Endace
1186 DAG devices), so \-1 is returned for those devices.
1188 Note that on most versions of most BSDs (including Mac OS X)
1192 do not work correctly on BPF devices;
1193 .B pcap_get_selectable_fd()
1194 will return a file descriptor on most of those versions (the exceptions
1195 being FreeBSD 4.3 and 4.4), a simple
1199 will not return even after a timeout specified in
1201 expires. To work around this, an application that uses
1205 to wait for packets to arrive must put the
1207 in non-blocking mode, and must arrange that the
1211 have a timeout less than or equal to the timeout specified in
1212 .BR pcap_open_live() ,
1213 and must try to read packets after that timeout expires, regardless of
1218 indicated that the file descriptor for the
1220 is ready to be read or not. (That workaround will not work in FreeBSD
1221 4.3 and later; however, in FreeBSD 4.6 and later,
1225 work correctly on BPF devices, so the workaround isn't necessary,
1226 although it does no harm.)
1228 .B pcap_get_selectable_fd()
1229 is not available on Windows.
1232 prints the text of the last pcap library error on
1238 returns the error text pertaining to the last pcap library error.
1240 the pointer it returns will no longer point to a valid error message
1243 passed to it is closed; you must use or copy the string before closing
1252 .B pcap_lib_version()
1253 returns a pointer to a string giving information about the version of
1254 the libpcap library being used; note that it contains more information
1255 than just a version number.
1258 closes the files associated with
1260 and deallocates resources.
1263 returns the standard I/O stream of the ``savefile'' opened by
1264 .BR pcap_dump_open().
1266 .B pcap_dump_flush()
1267 flushes the output buffer to the ``savefile,'' so that any packets
1270 but not yet written to the ``savefile'' will be written.
1272 is returned on error, 0 on success.
1274 .B pcap_dump_ftell()
1275 returns the current file position for the ``savefile'', representing the
1276 number of bytes written by
1281 is returned on error.
1283 .B pcap_dump_close()
1284 closes the ``savefile.''
1287 tcpdump(1), tcpslice(1)
1289 The original authors are:
1293 Steven McCanne, all of the
1294 Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.
1296 The current version is available from "The Tcpdump Group"'s Web site at
1299 .I http://www.tcpdump.org/
1302 Please send problems, bugs, questions, desirable enhancements, etc. to:
1305 tcpdump-workers@tcpdump.org
1308 Please send source code contributions, etc. to:
projects / dragonfly.git / blob