1 .\" @(#) $Header: /tcpdump/master/libpcap/Attic/pcap.3,v 1.23 2001-10-08 01:06:21 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 "3 January 2001"
24 pcap \- Packet Capture library
33 char errbuf[PCAP_ERRBUF_SIZE];
37 pcap_t *pcap_open_live(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(char *fname, char *errbuf)
42 pcap_dumper_t *pcap_dump_open(pcap_t *p, char *fname)
46 int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf)
47 void pcap_freealldevs(pcap_if_t *)
48 char *pcap_lookupdev(char *errbuf)
49 int pcap_lookupnet(char *device, bpf_u_int32 *netp,
51 bpf_u_int32 *maskp, char *errbuf)
55 int pcap_dispatch(pcap_t *p, int cnt,
57 pcap_handler callback, u_char *user)
58 int pcap_loop(pcap_t *p, int cnt,
60 pcap_handler callback, u_char *user)
61 void pcap_dump(u_char *user, struct pcap_pkthdr *h,
67 int pcap_compile(pcap_t *p, struct bpf_program *fp,
69 char *str, int optimize, bpf_u_int32 netmask)
70 int pcap_setfilter(pcap_t *p, struct bpf_program *fp)
71 void pcap_freecode(struct bpf_program *);
75 u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)
79 int pcap_datalink(pcap_t *p)
80 int pcap_snapshot(pcap_t *p)
81 int pcap_is_swapped(pcap_t *p)
82 int pcap_major_version(pcap_t *p)
83 int pcap_minor_version(pcap_t *p)
84 int pcap_stats(pcap_t *p, struct pcap_stat *ps)
85 FILE *pcap_file(pcap_t *p)
86 int pcap_fileno(pcap_t *p)
87 void pcap_perror(pcap_t *p, char *prefix)
88 char *pcap_geterr(pcap_t *p)
89 char *pcap_strerror(int error)
93 void pcap_close(pcap_t *p)
94 void pcap_dump_close(pcap_dumper_t *p)
98 The Packet Capture library
99 provides a high level interface to packet capture systems. All packets
100 on the network, even those destined for other hosts, are accessible
101 through this mechanism.
109 .B pcap_open_offline(),
110 .B pcap_findalldevs(),
114 is assumed to be able to hold at least
119 is used to obtain a packet capture descriptor to look
120 at packets on the network.
122 is a string that specifies the network device to open; on Linux systems
123 with 2.2 or later kernels, a
127 can be used to capture packets from all interfaces.
129 specifies the maximum number of bytes to capture.
131 specifies if the interface is to be put into promiscuous mode.
132 (Note that even if this parameter is false, the interface
133 could well be in promiscuous mode for some other reason.) For now, this
134 doesn't work on the "any" device; if an argument of "any" or NULL is
139 specifies the read timeout in milliseconds. The read timeout is used to
140 arrange that the read not necessarily return immediately when a packet
141 is seen, but that it wait for some amount of time to allow more packets
142 to arrive and to read multiple packets from the OS kernel in one
143 operation. Not all platforms support a read timeout; on platforms that
144 don't, the read timeout is ignored.
146 is used to return error or warning text. It will be set to error text when
151 may also be set to warning text when
153 succeds; to detect this case the caller should store a zero-length string in
157 and display the warning to the user if
159 is no longer a zero-length string.
162 is used for creating a
164 structure to use when calling the other functions in libpcap. It is
165 typically used when just using libpcap for compiling BPF code.
167 .B pcap_open_offline()
168 is called to open a ``savefile'' for reading.
170 specifies the name of the file to open. The file has
171 the same format as those used by
175 The name "-" in a synonym for
178 is used to return error text and is only set when
179 .B pcap_open_offline()
184 is called to open a ``savefile'' for writing. The name "-" in a synonym
188 is returned on failure.
192 struct as returned by
193 .B pcap_open_offline()
195 .BR pcap_open_live() .
197 specifies the name of the file to open.
202 can be used to get the error text.
204 .B pcap_findalldevs()
205 constructs a list of network devices that can be opened with
206 .BR pcap_open_live() .
207 (Note that there may be network devices that cannot be opened with
211 .BR pcap_findalldevs() ,
212 because, for example, that process might not have sufficient privileges
213 to open them for capturing; if so, those devices will not appear on the
216 is set to point to the first element of the list; each element of the
219 and has the following members:
225 a pointer to the next element in the list;
227 for the last element of the list
230 a pointer to a string giving a name for the device to pass to
236 a pointer to a string giving a human-readable description of the device
239 a pointer to the first element of a list of addresses for the interface
242 non-zero if the interface is a loopback interface
245 Each element of the list of addresses is of type
247 and has the following members:
253 a pointer to the next element in the list;
255 for the last element of the list
260 containing an address
267 that contains the netmask corresponding to the address pointed to by
275 that contains the broadcast address corresponding to the address pointed
278 may be null if the interface doesn't support broadcasts
285 that contains the destination address corresponding to the address pointed
288 may be null if the interface isn't a point-to-point interface
291 .B pcap_freealldevs()
292 is used to free a list allocated by
293 .BR pcap_findalldevs() .
296 returns a pointer to a network device suitable for use with
299 .BR pcap_lookupnet() .
300 If there is an error,
304 is filled in with an appropriate error message.
307 is used to determine the network number and mask
308 associated with the network device
317 A return of \-1 indicates an error in which case
319 is filled in with an appropriate error message.
322 is used to collect and process packets.
324 specifies the maximum number of packets to process before returning.
325 This is not a minimum number; when reading a live capture, only one
326 bufferful of packets is read at a time, so fewer than
328 packets may be processed. A
330 of \-1 processes all the packets received in one buffer when reading a
331 live capture, or all the packets in the file when reading a
334 specifies a routine to be called with three arguments:
337 pointer which is passed in from
338 .BR pcap_dispatch() ,
341 struct (which precede the actual network headers and data),
344 pointer to the packet data.
346 The number of packets read is returned.
347 0 is returned if no packets were read from a live capture (if, for
348 example, they were discarded because they didn't pass the packet filter,
349 or if, on platforms that support a read timeout that starts before any
350 packets arrive, the timeout expires before any packets arrive, or if the
351 file descriptor for the capture device is in non-blocking mode and no
352 packets were available to be read) or if no more packets are available
353 in a ``savefile.'' A return of \-1 indicates
354 an error in which case
358 may be used to display the error text.
361 when reading a live capture,
363 will not necessarily return when the read times out; on some platforms,
364 the read timeout isn't supported, and, on other platforms, the timer
365 doesn't start until at least one packet arrives. This means that the
368 be used in, for example, an interactive application, to allow the packet
369 capture loop to ``poll'' for user input periodically, as there's no
372 will return after the timeout expires.
377 except it keeps reading packets until
379 packets are processed or an error occurs.
382 return when live read timeouts occur.
383 Rather, specifying a non-zero read timeout to
387 allows the reception and processing of any packets that arrive when the
393 to loop forever (or at least until an error occurs).
396 reads the next packet (by calling
402 pointer to the data in that packet. (The
404 struct for that packet is not supplied.)
407 outputs a packet to the ``savefile'' opened with
408 .BR pcap_dump_open() .
409 Note that its calling arguments are suitable for use with
415 is used to compile the string
417 into a filter program.
421 struct and is filled in by
424 controls whether optimization on the resulting code is performed.
426 specifies the netmask of the local net.
427 A return of \-1 indicates an error in which case
429 may be used to display the error text.
431 .B pcap_compile_nopcap()
434 except that instead of passing a pcap structure, one passes the
435 snaplen and linktype explicitly. It is intended to be used for
436 compiling filters for direct BPF usage, without necessarily having
439 A return of \-1 indicates an error; the error text is unavailable.
440 .RB ( pcap_compile_nopcap()
442 .BR pcap_open_dead() ,
446 the latter three routines can be used directly in order to get the error
447 text for a compilation error.)
451 is used to specify a filter program.
455 struct, usually the result of a call to
458 is returned on failure, in which case
460 may be used to display the error text;
462 is returned on success.
465 is used to free up allocated memory pointed to by a
469 when that BPF program is no longer needed, for example after it
470 has been made the filter program for a pcap structure by a call to
471 .BR pcap_setfilter() .
474 returns the link layer type, e.g.
478 returns the snapshot length specified when
483 returns true if the current ``savefile'' uses a different byte order
484 than the current system.
486 .B pcap_major_version()
487 returns the major number of the version of the pcap used to write the
490 .B pcap_minor_version()
491 returns the minor number of the version of the pcap used to write the
495 returns the standard I/O stream of the ``savefile,'' if a ``savefile''
497 .BR pcap_open_offline() ,
498 or NULL, if a network device was opened with
499 .BR pcap_open_live() .
502 returns 0 and fills in a
504 struct. The values represent packet statistics from the start of the
505 run to the time of the call. If there is an error or the underlying
506 packet capture doesn't support packet statistics, \-1 is returned and
507 the error text can be obtained with
513 returns the file descriptor number from which captured packets are read,
514 if a network device was opened with
515 .BR pcap_open_live() ,
516 or \-1, if a ``savefile'' was opened with
517 .BR pcap_open_offline() .
520 prints the text of the last pcap library error on
526 returns the error text pertaining to the last pcap library error.
528 the pointer it returns will no longer point to a valid error message
531 passed to it is closed; you must use or copy the string before closing
541 closes the files associated with
543 and deallocates resources.
546 closes the ``savefile.''
549 tcpdump(1), tcpslice(1)
551 The original authors are:
555 Steven McCanne, all of the
556 Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.
558 The current version is available from "The Tcpdump Group"'s Web site at
561 .I http://www.tcpdump.org/
564 Please send problems, bugs, questions, desirable enhancements, etc. to:
567 tcpdump-workers@tcpdump.org
570 Please send source code contributions, etc. to:
projects / libpcap / blob