414 lines
9.9 KiB
Groff
414 lines
9.9 KiB
Groff
.\" $NetBSD: pcap.3,v 1.18 2003/01/07 16:51:20 pooka 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.
|
|
.\"
|
|
.Dd September 25, 2002
|
|
.Os
|
|
.Dt PCAP 3
|
|
.Sh NAME
|
|
.Nm pcap
|
|
.Nd packet capture library
|
|
.Sh LIBRARY
|
|
.Lb libpcap
|
|
.Sh SYNOPSIS
|
|
.Fd #include \*[Lt]pcap.h\*[Gt]
|
|
.Ft pcap_t *
|
|
.Fn pcap_open_live "char *device" "int snaplen" "int promisc" \
|
|
"int to_ms" "char *ebuf"
|
|
.Ft pcap_t *
|
|
.Fn pcap_open_offline "char *fname" "char *ebuf"
|
|
.Ft pcap_dumper_t *
|
|
.Fn pcap_dump_open "pcap_t *p" "char *fname"
|
|
.Ft char
|
|
.Dv errbuf[PCAP_ERRBUF_SIZE];
|
|
.Ft char *
|
|
.Fn pcap_lookupdev "char *errbuf"
|
|
.Ft int
|
|
.Fn pcap_lookupnet "char *device" "bpf_u_int32 *netp" \
|
|
"bpf_u_int32 *maskp" "char *errbuf"
|
|
.Ft int
|
|
.Fn pcap_dispatch "pcap_t *p" "int cnt" \
|
|
"pcap_handler callback" "u_char *user"
|
|
.Ft int
|
|
.Fn pcap_loop "pcap_t *p" "int cnt" \
|
|
"pcap_handler callback" "u_char *user"
|
|
.Ft void
|
|
.Fn pcap_dump "u_char *user" "struct pcap_pkthdr *h" \
|
|
"u_char *sp"
|
|
.Ft int
|
|
.Fn pcap_compile "pcap_t *p" "struct bpf_program *fp" \
|
|
"char *str" "int optimize" "bpf_u_int32 netmask"
|
|
.Ft int
|
|
.Fn pcap_compile_nopcap "int snaplen" "int linktype" \
|
|
"struct bpf_program *fp" "char *str" "int optimize" \
|
|
"bpf_uint32 netmask" "char *errbuf"
|
|
.Ft int
|
|
.Fn pcap_setfilter "pcap_t *p" "struct bpf_program *fp"
|
|
.Ft int
|
|
.Fn pcap_set_datalink "pcap_t *p" "int dlt"
|
|
.Ft int
|
|
.Fn pcap_list_datalinks "pcap_t *p" "int **dlt_buf"
|
|
.Ft const u_char *
|
|
.Fn pcap_next "pcap_t *p" "struct pcap_pkthdr *h"
|
|
.Ft int
|
|
.Fn pcap_datalink "pcap_t *p"
|
|
.Ft int
|
|
.Fn pcap_snapshot "pcap_t *p"
|
|
.Ft int
|
|
.Fn pcap_is_swapped "pcap_t *p"
|
|
.Ft int
|
|
.Fn pcap_major_version "pcap_t *p"
|
|
.Ft int
|
|
.Fn pcap_minor_version "pcap_t *p"
|
|
.Ft int
|
|
.Fn pcap_stats "pcap_t *p" "struct pcap_stat *ps"
|
|
.Ft FILE *
|
|
.Fn pcap_file "pcap_t *p"
|
|
.Ft int
|
|
.Fn pcap_fileno "pcap_t *p"
|
|
.Ft void
|
|
.Fn pcap_perror "pcap_t *p" "char *prefix"
|
|
.Ft char *
|
|
.Fn pcap_geterr "pcap_t *p"
|
|
.Ft char *
|
|
.Fn pcap_strerror "int error"
|
|
.Ft void
|
|
.Fn pcap_close "pcap_t *p"
|
|
.Ft void
|
|
.Fn pcap_dump_close "pcap_dumper_t *p"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
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.
|
|
.Sh ROUTINES
|
|
.Fn pcap_open_live
|
|
is used to obtain a packet capture descriptor to look at packets on
|
|
the network.
|
|
.Fa device
|
|
is a string that specifies the network device to open.
|
|
.Fa snaplen
|
|
specifies the maximum number of bytes to capture.
|
|
.Fa 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.)
|
|
.Fa to_ms
|
|
specifies the read timeout in milliseconds.
|
|
.Fa ebuf
|
|
is used to return error text and is only set when
|
|
.Fn pcap_open_live
|
|
fails and returns
|
|
.Em NULL .
|
|
.Pp
|
|
.Fn pcap_open_offline
|
|
is called to open a
|
|
.Dq savefile
|
|
for reading.
|
|
.Fa fname
|
|
specifies the name of the file to open.
|
|
The file has the same format as those used by
|
|
.Xr tcpdump 8 .
|
|
The name
|
|
.Dq \&-
|
|
is a synonym for
|
|
.Em stdin .
|
|
.Fa ebuf
|
|
is used to return error text and is only set when
|
|
.Fn pcap_open_offline
|
|
fails and returns
|
|
.Em NULL .
|
|
.Pp
|
|
.Fn pcap_dump_open
|
|
is called to open a
|
|
.Dq savefile
|
|
for writing.
|
|
The name
|
|
.Dq \&-
|
|
is a synonym
|
|
for
|
|
.Em stdout .
|
|
.Em NULL
|
|
is returned on failure.
|
|
.Fa p
|
|
is a
|
|
.Fa pcap
|
|
struct as returned by
|
|
.Fn pcap_open_offline
|
|
or
|
|
.Fn pcap_open_live .
|
|
.Fa fname
|
|
specifies the name of the file to open.
|
|
If
|
|
.Em NULL
|
|
is returned,
|
|
.Fn pcap_geterr
|
|
can be used to get the error text.
|
|
.Pp
|
|
.Fn pcap_lookupdev
|
|
returns a pointer to a network device suitable for use with
|
|
.Fn pcap_open_live
|
|
and
|
|
.Fn pcap_lookupnet .
|
|
If there is an error,
|
|
.Em NULL
|
|
is returned and
|
|
.Fa errbuf
|
|
is filled in with an appropriate error message.
|
|
.Pp
|
|
.Fn pcap_lookupnet
|
|
is used to determine the network number and mask
|
|
associated with the network device
|
|
.Em device .
|
|
Both
|
|
.Fa netp
|
|
and
|
|
.Fa maskp
|
|
are
|
|
.Fa bpf_u_int32
|
|
pointers.
|
|
A return of -1 indicates an error in which case
|
|
.Fa errbuf
|
|
is filled in with an appropriate error message.
|
|
.Pp
|
|
.Fn pcap_dispatch
|
|
is used to collect and process packets.
|
|
.Fa cnt
|
|
specifies the maximum number of packets to process before returning.
|
|
A
|
|
.Fa cnt
|
|
of -1 processes all the packets received in one buffer.
|
|
A
|
|
.Fa cnt
|
|
of 0 processes all packets until an error occurs (or
|
|
.Em EOF
|
|
is reached).
|
|
.Fa callback
|
|
specifies a routine to be called with three arguments:
|
|
a
|
|
.Fa u_char
|
|
pointer which is passed in from
|
|
.Fn pcap_dispatch ,
|
|
a pointer to the
|
|
.Fa pcap_pkthdr
|
|
struct (which precede the actual network headers and data),
|
|
and a
|
|
.Fa u_char
|
|
pointer to the packet data.
|
|
The number of packets read is returned.
|
|
Zero is returned when
|
|
.Em EOF
|
|
is reached in a
|
|
.Dq savefile .
|
|
A return of -1 indicates an error in which case
|
|
.Fn pcap_perror
|
|
or
|
|
.Fn pcap_geterr
|
|
may be used to display the error text.
|
|
.Pp
|
|
.Fn pcap_dump
|
|
outputs a packet to the
|
|
.Dq savefile
|
|
opened with
|
|
.Fn pcap_dump_open .
|
|
Note that its calling arguments are suitable for use with
|
|
.Fn pcap_dispatch .
|
|
.Pp
|
|
.Fn pcap_compile
|
|
is used to compile the string
|
|
.Fa str
|
|
into a filter program.
|
|
.Fa program
|
|
is a pointer to a
|
|
.Fa bpf_program
|
|
struct and is filled in by
|
|
.Fn pcap_compile .
|
|
.Fa optimize
|
|
controls whether optimization on the resulting code is performed.
|
|
.Fa netmask
|
|
specifies the netmask of the local net.
|
|
.Pp
|
|
.Fn pcap_compile_nopcap
|
|
is similar to
|
|
.Fn pcap_compile
|
|
except that instead of passing a pcap descriptor, one passes the
|
|
snaplen, linktype, and error buffer (which must be
|
|
.Em PCAP_ERRBUF_SIZE
|
|
in length) explicitly.
|
|
It is intended to be used for compiling filters for direct
|
|
bpf usage, without necessarily having called
|
|
.Fn pcap_open .
|
|
.Pp
|
|
.Fn pcap_setfilter
|
|
is used to specify a filter program.
|
|
.Fa fp
|
|
is a pointer to an array of
|
|
.Fa bpf_program
|
|
struct, usually the result of a call to
|
|
.Fn pcap_compile .
|
|
.Em \-1
|
|
is returned on failure;
|
|
.Em 0
|
|
is returned on success.
|
|
.Pp
|
|
.Fn pcap_set_datalink
|
|
is used to set the current data link type of the pcap descriptor
|
|
to the type specified by
|
|
.Fa dlt .
|
|
This operation is supported only of the interface associated with
|
|
the pcap descriptor supports multiple data link types.
|
|
.Em \-1
|
|
is return on failure;
|
|
.Em 0
|
|
is returned on success.
|
|
.Pp
|
|
.Fn pcap_list_datalinks
|
|
is used to get a list of the support data link types of the interface
|
|
associated with the pcap descriptor.
|
|
.Fn pcap_list_datalinks
|
|
allocates an array to hold the list and sets
|
|
.Fa *dlt_buf .
|
|
The caller is responsible for freeing the array.
|
|
.Em \-1
|
|
is returned on failure;
|
|
otherwise, the number of data link types in the array is returned.
|
|
.Pp
|
|
.Fn pcap_loop
|
|
is similar to
|
|
.Fn pcap_dispatch
|
|
except it keeps reading packets until
|
|
.Fa cnt
|
|
packets are processed or an error occurs.
|
|
A negative
|
|
.Fa cnt
|
|
causes
|
|
.Fn pcap_loop
|
|
to loop forever (or at least until an error occurs).
|
|
.Pp
|
|
.Fn pcap_next
|
|
returns a
|
|
.Fa u_char
|
|
pointer to the next packet.
|
|
.Pp
|
|
.Fn pcap_datalink
|
|
returns the link layer type, e.g.
|
|
.Em DLT_EN10MB .
|
|
.Pp
|
|
.Fn pcap_snapshot
|
|
returns the snapshot length specified when
|
|
.Fn pcap_open_live
|
|
was called.
|
|
.Pp
|
|
.Fn pcap_is_swapped
|
|
returns true if the current
|
|
.Dq savefile
|
|
uses a different byte order than the current system.
|
|
.Pp
|
|
.Fn pcap_major_version
|
|
returns the major number of the version of the pcap used to write the
|
|
savefile.
|
|
.Pp
|
|
.Fn pcap_minor_version
|
|
returns the minor number of the version of the pcap used to write the
|
|
savefile.
|
|
.Pp
|
|
.Fn pcap_file
|
|
returns the standard I/O stream of the
|
|
.Dq savefile ,
|
|
if a
|
|
.Dq savefile
|
|
was opened with
|
|
.Fn pcap_open_offline ,
|
|
or NULL, if a network device was opened with
|
|
.Fn pcap_open_live .
|
|
.Pp
|
|
.Fn pcap_stats
|
|
returns 0 and fills in a
|
|
.Fa 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
|
|
.Fn pcap_perror
|
|
or
|
|
.Fn pcap_geterr .
|
|
.Pp
|
|
.Fn pcap_fileno
|
|
returns the file descriptor number from which captured packets are read
|
|
if a network device was opened with
|
|
.Fn pcap_open_live ,
|
|
or \-1, if a
|
|
.Dq savefile
|
|
was opened with
|
|
.Fn pcap_open_offline .
|
|
.Pp
|
|
.Fn pcap_perror
|
|
prints the text of the last pcap library error on
|
|
.Em stderr ,
|
|
prefixed by
|
|
.Em prefix .
|
|
.Pp
|
|
.Fn pcap_geterr
|
|
returns the error text pertaining to the last pcap library error.
|
|
.Pp
|
|
.Fn pcap_strerror
|
|
is provided in case
|
|
.Xr strerror 3
|
|
isn't available.
|
|
.Pp
|
|
.Fn pcap_close
|
|
closes the files associated with
|
|
.Fa p
|
|
and deallocates resources.
|
|
.Pp
|
|
.Fn pcap_dump_close
|
|
closes the
|
|
.Dq savefile .
|
|
.Sh SEE ALSO
|
|
.Xr tcpdump 8
|
|
.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
|
|
.\" .Em 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
|