| .\" @(#) $Header: /tcpdump/master/libpcap/Attic/pcap.3,v 1.17.2.3 2001-03-26 10:23:33 guy Exp $ |
| .\" |
| .\" Copyright (c) 1994, 1996, 1997 |
| .\" The Regents of the University of California. All rights reserved. |
| .\" |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that: (1) source code distributions |
| .\" retain the above copyright notice and this paragraph in its entirety, (2) |
| .\" distributions including binary code include the above copyright notice and |
| .\" this paragraph in its entirety in the documentation or other materials |
| .\" provided with the distribution, and (3) all advertising materials mentioning |
| .\" features or use of this software display the following acknowledgement: |
| .\" ``This product includes software developed by the University of California, |
| .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of |
| .\" the University nor the names of its contributors may be used to endorse |
| .\" or promote products derived from this software without specific prior |
| .\" written permission. |
| .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED |
| .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF |
| .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| .\" |
| .TH PCAP 3 "3 January 2001" |
| .SH NAME |
| pcap \- Packet Capture library |
| .SH SYNOPSIS |
| .nf |
| .ft B |
| #include <pcap.h> |
| .ft |
| .LP |
| .ft B |
| pcap_t *pcap_open_live(char *device, int snaplen, |
| .ti +8 |
| int promisc, int to_ms, char *ebuf) |
| pcap_t *pcap_open_dead(int linktype, int snaplen) |
| pcap_t *pcap_open_offline(char *fname, char *ebuf) |
| pcap_dumper_t *pcap_dump_open(pcap_t *p, char *fname) |
| .ft |
| .LP |
| .ft B |
| char errbuf[PCAP_ERRBUF_SIZE]; |
| char *pcap_lookupdev(char *errbuf) |
| int pcap_lookupnet(char *device, bpf_u_int32 *netp, |
| .ti +8 |
| bpf_u_int32 *maskp, char *errbuf) |
| .ft |
| .LP |
| .ft B |
| int pcap_dispatch(pcap_t *p, int cnt, |
| .ti +8 |
| pcap_handler callback, u_char *user) |
| int pcap_loop(pcap_t *p, int cnt, |
| .ti +8 |
| pcap_handler callback, u_char *user) |
| void pcap_dump(u_char *user, struct pcap_pkthdr *h, |
| .ti +8 |
| u_char *sp) |
| .ft |
| .LP |
| .ft B |
| int pcap_compile(pcap_t *p, struct bpf_program *fp, |
| .ti +8 |
| char *str, int optimize, bpf_u_int32 netmask) |
| int pcap_setfilter(pcap_t *p, struct bpf_program *fp) |
| void pcap_freecode(struct bpf_program *); |
| .ft |
| .LP |
| .ft B |
| u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h) |
| .ft |
| .LP |
| .ft B |
| int pcap_datalink(pcap_t *p) |
| int pcap_snapshot(pcap_t *p) |
| int pcap_is_swapped(pcap_t *p) |
| int pcap_major_version(pcap_t *p) |
| int pcap_minor_version(pcap_t *p) |
| int pcap_stats(pcap_t *p, struct pcap_stat *ps) |
| FILE *pcap_file(pcap_t *p) |
| int pcap_fileno(pcap_t *p) |
| void pcap_perror(pcap_t *p, char *prefix) |
| char *pcap_geterr(pcap_t *p) |
| char *pcap_strerror(int error) |
| .ft |
| .LP |
| .ft B |
| void pcap_close(pcap_t *p) |
| void pcap_dump_close(pcap_dumper_t *p) |
| .ft |
| .fi |
| .SH DESCRIPTION |
| The Packet Capture library |
| provides a high level interface to packet capture systems. All packets |
| on the network, even those destined for other hosts, are accessible |
| through this mechanism. |
| .PP |
| .SH ROUTINES |
| NOTE: |
| .I errbuf |
| in |
| .B pcap_open_live(), |
| .B pcap_open_offline(), |
| .B pcap_lookupdev(), |
| and |
| .B pcap_lookupnet() |
| is assumed to be able to hold at least |
| .B PCAP_ERRBUF_SIZE |
| chars. |
| .PP |
| .B pcap_open_live() |
| is used to obtain a packet capture descriptor to look |
| at packets on the network. |
| .I device |
| is a string that specifies the network device to open; on Linux systems |
| with 2.2 or later kernels, a |
| .I device |
| argument of "any" or |
| .B NULL |
| can be used to capture packets from all interfaces. |
| .I snaplen |
| specifies the maximum number of bytes to capture. |
| .I promisc |
| specifies if the interface is to be put into promiscuous mode. |
| (Note that even if this parameter is false, the interface |
| could well be in promiscuous mode for some other reason.) For now, this |
| doesn't work on the "any" device; if an argument of "any" or NULL is |
| supplied, the |
| .I promisc |
| flag is ignored. |
| .I to_ms |
| specifies the read timeout in milliseconds. The read timeout is used to |
| arrange that the read not necessarily return immediately when a packet |
| is seen, but that it wait for some amount of time to allow more packets |
| to arrive and to read multiple packets from the OS kernel in one |
| operation. Not all platforms support a read timeout; on platforms that |
| don't, the read timeout is ignored. |
| .I ebuf |
| is used to return error text and is only set when |
| .B pcap_open_live() |
| fails and returns |
| .BR NULL . |
| .PP |
| .B pcap_open_dead() |
| is used for creating a |
| .B pcap_t |
| structure to use when calling the other functions in libpcap. It is |
| typically used when just using libpcap for compiling BPF code. |
| .PP |
| .B pcap_open_offline() |
| is called to open a ``savefile'' for reading. |
| .I fname |
| specifies the name of the file to open. The file has |
| the same format as those used by |
| .B tcpdump(1) |
| and |
| .BR tcpslice(1) . |
| The name "-" in a synonym for |
| .BR stdin . |
| .I ebuf |
| is used to return error text and is only set when |
| .B pcap_open_offline() |
| fails and returns |
| .BR NULL . |
| .PP |
| .B pcap_dump_open() |
| is called to open a ``savefile'' for writing. The name "-" in a synonym |
| for |
| .BR stdout . |
| .B NULL |
| is returned on failure. |
| .I p |
| is a |
| .I pcap |
| struct as returned by |
| .B pcap_open_offline() |
| or |
| .BR pcap_open_live() . |
| .I fname |
| specifies the name of the file to open. |
| If |
| .B NULL |
| is returned, |
| .B pcap_geterr() |
| can be used to get the error text. |
| .PP |
| .B pcap_lookupdev() |
| returns a pointer to a network device suitable for use with |
| .B pcap_open_live() |
| and |
| .BR pcap_lookupnet() . |
| If there is an error, |
| .B NULL |
| is returned and |
| .I errbuf |
| is filled in with an appropriate error message. |
| .PP |
| .B pcap_lookupnet() |
| is used to determine the network number and mask |
| associated with the network device |
| .BR device . |
| Both |
| .I netp |
| and |
| .I maskp |
| are |
| .I bpf_u_int32 |
| pointers. |
| A return of \-1 indicates an error in which case |
| .I errbuf |
| is filled in with an appropriate error message. |
| .PP |
| .B pcap_dispatch() |
| is used to collect and process packets. |
| .I cnt |
| specifies the maximum number of packets to process before returning. |
| This is not a minimum number; when reading a live capture, only one |
| bufferful of packets is read at a time, so fewer than |
| .I cnt |
| packets may be processed. A |
| .I cnt |
| of \-1 processes all the packets received in one buffer when reading a |
| live capture, or all the packets in the file when reading a |
| ``savefile''. |
| .I callback |
| specifies a routine to be called with three arguments: |
| a |
| .I u_char |
| pointer which is passed in from |
| .BR pcap_dispatch() , |
| a pointer to the |
| .I pcap_pkthdr |
| struct (which precede the actual network headers and data), |
| and a |
| .I u_char |
| pointer to the packet data. |
| .PP |
| The number of packets read is returned. |
| 0 is returned if no packets were read from a live capture (if, for |
| example, they were discarded because they didn't pass the packet filter, |
| or if, on platforms that support a read timeout that starts before any |
| packets arrive, the timeout expires before any packets arrive, or if the |
| file descriptor for the capture device is in non-blocking mode and no |
| packets were available to be read) or if no more packets are available |
| in a ``savefile.'' A return of \-1 indicates |
| an error in which case |
| .B pcap_perror() |
| or |
| .B pcap_geterr() |
| may be used to display the error text. |
| .PP |
| .BR NOTE : |
| when reading a live capture, |
| .B pcap_dispatch() |
| will not necessarily return when the read times out; on some platforms, |
| the read timeout isn't supported, and, on other platforms, the timer |
| doesn't start until at least one packet arrives. This means that the |
| read timeout should |
| .B NOT |
| be used in, for example, an interactive application, to allow the packet |
| capture loop to ``poll'' for user input periodically, as there's no |
| guarantee that |
| .B pcap_dispatch() |
| will return after the timeout expires. |
| .PP |
| .B pcap_loop() |
| is similar to |
| .B pcap_dispatch() |
| except it keeps reading packets until |
| .I cnt |
| packets are processed or an error occurs. |
| It does |
| .B not |
| return when live read timeouts occur. |
| Rather, specifying a non-zero read timeout to |
| .B pcap_open_live() |
| and then calling |
| .B pcap_dispatch() |
| allows the reception and processing of any packets that arrive when the |
| timeout occurs. |
| A negative |
| .I cnt |
| causes |
| .B pcap_loop() |
| to loop forever (or at least until an error occurs). |
| .PP |
| .B pcap_next() |
| reads the next packet (by calling |
| .B pcap_dispatch() |
| with a |
| .I cnt |
| of 1) and returns a |
| .I u_char |
| pointer to the data in that packet. (The |
| .I pcap_pkthdr |
| struct for that packet is not supplied.) |
| .PP |
| .B pcap_dump() |
| outputs a packet to the ``savefile'' opened with |
| .BR pcap_dump_open() . |
| Note that its calling arguments are suitable for use with |
| .B pcap_dispatch() |
| or |
| .BR pcap_loop() . |
| .PP |
| .B pcap_compile() |
| is used to compile the string |
| .I str |
| into a filter program. |
| .I program |
| is a pointer to a |
| .I bpf_program |
| struct and is filled in by |
| .BR pcap_compile() . |
| .I optimize |
| controls whether optimization on the resulting code is performed. |
| .I netmask |
| specifies the netmask of the local net. |
| A return of \-1 indicates an error in which case |
| .BR pcap_geterr() |
| may be used to display the error text. |
| .PP |
| .B pcap_compile_nopcap() |
| is similar to |
| .B pcap_compile() |
| except that instead of passing a pcap structure, one passes the |
| snaplen and linktype explicitly. It is intended to be used for |
| compiling filters for direct BPF usage, without necessarily having |
| called |
| .BR pcap_open() . |
| A return of \-1 indicates an error; the error text is unavailable. |
| .RB ( pcap_compile_nopcap() |
| is a wrapper around |
| .BR pcap_open_dead() , |
| .BR pcap_compile() , |
| and |
| .BR pcap_close() ; |
| the latter three routines can be used directly in order to get the error |
| text for a compilation error.) |
| .B |
| .PP |
| .B pcap_setfilter() |
| is used to specify a filter program. |
| .I fp |
| is a pointer to a |
| .I bpf_program |
| struct, usually the result of a call to |
| .BR pcap_compile() . |
| .B \-1 |
| is returned on failure, in which case |
| .BR pcap_geterr() |
| may be used to display the error text; |
| .B 0 |
| is returned on success. |
| .PP |
| .B pcap_freecode() |
| is used to free up allocated memory pointed to by a |
| .I bpf_program |
| struct generated by |
| .B pcap_compile() |
| when that BPF program is no longer needed, for example after it |
| has been made the filter program for a pcap structure by a call to |
| .BR pcap_setfilter() . |
| .PP |
| .B pcap_datalink() |
| returns the link layer type, e.g. |
| .BR DLT_EN10MB . |
| .PP |
| .B pcap_snapshot() |
| returns the snapshot length specified when |
| .B pcap_open_live |
| was called. |
| .PP |
| .B pcap_is_swapped() |
| returns true if the current ``savefile'' uses a different byte order |
| than the current system. |
| .PP |
| .B pcap_major_version() |
| returns the major number of the version of the pcap used to write the |
| savefile. |
| .PP |
| .B pcap_minor_version() |
| returns the minor number of the version of the pcap used to write the |
| savefile. |
| .PP |
| .B pcap_file() |
| returns the standard I/O stream of the ``savefile,'' if a ``savefile'' |
| was opened with |
| .BR pcap_open_offline() , |
| or NULL, if a network device was opened with |
| .BR pcap_open_live() . |
| .PP |
| .B pcap_stats() |
| returns 0 and fills in a |
| .B pcap_stat |
| struct. The values represent packet statistics from the start of the |
| run to the time of the call. If there is an error or the under lying |
| packet capture doesn't support packet statistics, \-1 is returned and |
| the error text can be obtained with |
| .B pcap_perror() |
| or |
| .BR pcap_geterr() . |
| .PP |
| .B pcap_fileno() |
| returns the file descriptor number from which captured packets are read, |
| if a network device was opened with |
| .BR pcap_open_live() , |
| or \-1, if a ``savefile'' was opened with |
| .BR pcap_open_offline() . |
| .PP |
| .B pcap_perror() |
| prints the text of the last pcap library error on |
| .BR stderr , |
| prefixed by |
| .IR prefix . |
| .PP |
| .B pcap_geterr() |
| returns the error text pertaining to the last pcap library error. |
| .BR NOTE : |
| the pointer it returns will no longer point to a valid error message |
| string after the |
| .B pcap_t |
| passed to it is closed; you must use or copy the string before closing |
| the |
| .BR pcap_t . |
| .PP |
| .B pcap_strerror() |
| is provided in case |
| .BR strerror (1) |
| isn't available. |
| .PP |
| .B pcap_close() |
| closes the files associated with |
| .I p |
| and deallocates resources. |
| .PP |
| .B pcap_dump_close() |
| closes the ``savefile.'' |
| .PP |
| .SH SEE ALSO |
| tcpdump(1), tcpslice(1) |
| .SH AUTHORS |
| The original authors are: |
| .LP |
| Van Jacobson, |
| Craig Leres and |
| Steven McCanne, all of the |
| Lawrence Berkeley National Laboratory, University of California, Berkeley, CA. |
| .LP |
| The current version is available from "The Tcpdump Group"'s Web site at |
| .LP |
| .RS |
| .I http://www.tcpdump.org/ |
| .RE |
| .SH BUGS |
| Please send problems, bugs, questions, desirable enhancements, etc. to: |
| .LP |
| .RS |
| tcpdump-workers@tcpdump.org |
| .RE |
| .LP |
| Please send source code contributions, etc. to: |
| .LP |
| .RS |
| patches@tcpdump.org |
| .RE |