contrib/libpcap/pcap.3

   1 .\" @(#) $Header: /tcpdump/master/libpcap/pcap.3,v 1.17.2.1 2001/01/18 04:42:11 guy Exp $
   2 .\"
   3 .\" Copyright (c) 1994, 1996, 1997
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   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.
  21 .\"
  22 .\" $FreeBSD$
  23 .\"
  24 .TH PCAP 3 "3 January 2001"
  25 .SH NAME
  26 pcap \- Packet Capture library
  27 .SH SYNOPSIS
  28 .nf
  29 .ft B
  30 #include <pcap.h>
  31 .ft
  32 .LP
  33 .ft B
  34 pcap_t *pcap_open_live(char *device, int snaplen,
  35 .ti +8
  36 int promisc, int to_ms, char *ebuf)
  37 pcap_t *pcap_open_dead(int linktype, int snaplen)
  38 pcap_t *pcap_open_offline(char *fname, char *ebuf)
  39 pcap_dumper_t *pcap_dump_open(pcap_t *p, char *fname)
  40 .ft
  41 .LP
  42 .ft B
  43 char errbuf[PCAP_ERRBUF_SIZE];
  44 char *pcap_lookupdev(char *errbuf)
  45 int pcap_lookupnet(char *device, bpf_u_int32 *netp,
  46 .ti +8
  47 bpf_u_int32 *maskp, char *errbuf)
  48 .ft
  49 .LP
  50 .ft B
  51 int pcap_dispatch(pcap_t *p, int cnt,
  52 .ti +8
  53 pcap_handler callback, u_char *user)
  54 int pcap_loop(pcap_t *p, int cnt,
  55 .ti +8
  56 pcap_handler callback, u_char *user)
  57 void pcap_dump(u_char *user, struct pcap_pkthdr *h,
  58 .ti +8
  59 u_char *sp)
  60 .ft
  61 .LP
  62 .ft B
  63 int pcap_compile(pcap_t *p, struct bpf_program *fp,
  64 .ti +8
  65 char *str, int optimize, bpf_u_int32 netmask)
  66 int pcap_setfilter(pcap_t *p, struct bpf_program *fp)
  67 void pcap_freecode(struct bpf_program *);
  68 .ft
  69 .LP
  70 .ft B
  71 u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)
  72 .ft
  73 .LP
  74 .ft B
  75 int pcap_datalink(pcap_t *p)
  76 int pcap_snapshot(pcap_t *p)
  77 int pcap_is_swapped(pcap_t *p)
  78 int pcap_major_version(pcap_t *p)
  79 int pcap_minor_version(pcap_t *p)
  80 int pcap_stats(pcap_t *p, struct pcap_stat *ps)
  81 FILE *pcap_file(pcap_t *p)
  82 int pcap_fileno(pcap_t *p)
  83 void pcap_perror(pcap_t *p, char *prefix)
  84 char *pcap_geterr(pcap_t *p)
  85 char *pcap_strerror(int error)
  86 .ft
  87 .LP
  88 .ft B
  89 void pcap_close(pcap_t *p)
  90 void pcap_dump_close(pcap_dumper_t *p)
  91 .ft
  92 .fi
  93 .SH DESCRIPTION
  94 The Packet Capture library
  95 provides a high level interface to packet capture systems. All packets
  96 on the network, even those destined for other hosts, are accessible
  97 through this mechanism.
  98 .PP
  99 .SH ROUTINES
 100 NOTE:
 101 .I errbuf
 102 in
 103 .B pcap_open_live(),
 104 .B pcap_open_offline(),
 105 .B pcap_lookupdev(),
 106 and
 107 .B pcap_lookupnet()
 108 is assumed to be able to hold at least
 109 .B PCAP_ERRBUF_SIZE
 110 chars.
 111 .PP
 112 .B pcap_open_live()
 113 is used to obtain a packet capture descriptor to look
 114 at packets on the network.
 115 .I device
 116 is a string that specifies the network device to open; on Linux systems
 117 with 2.2 or later kernels, a
 118 .I device
 119 argument of "any" or
 120 .B NULL
 121 can be used to capture packets from all interfaces.
 122 .I snaplen
 123 specifies the maximum number of bytes to capture.
 124 .I promisc
 125 specifies if the interface is to be put into promiscuous mode.
 126 (Note that even if this parameter is false, the interface
 127 could well be in promiscuous mode for some other reason.)  For now, this
 128 doesn't work on the "any" device; if an argument of "any" or NULL is
 129 supplied, the
 130 .I promisc
 131 flag is ignored.
 132 .I to_ms
 133 specifies the read timeout in milliseconds.  The read timeout is used to
 134 arrange that the read not necessarily return immediately when a packet
 135 is seen, but that it wait for some amount of time to allow more packets
 136 to arrive and to read multiple packets from the OS kernel in one
 137 operation.  Not all platforms support a read timeout; on platforms that
 138 don't, the read timeout is ignored.
 139 .I ebuf
 140 is used to return error text and is only set when
 141 .B pcap_open_live()
 142 fails and returns
 143 .BR NULL .
 144 .PP
 145 .B pcap_open_dead()
 146 is used for creating a
 147 .B pcap_t
 148 structure to use when calling the other functions in libpcap.  It is
 149 typically used when just using libpcap for compiling BPF code.
 150 .PP
 151 .B pcap_open_offline()
 152 is called to open a ``savefile'' for reading.
 153 .I fname
 154 specifies the name of the file to open. The file has
 155 the same format as those used by
 156 .B tcpdump(1)
 157 and
 158 .BR tcpslice(1) .
 159 The name "-" in a synonym for
 160 .BR stdin .
 161 .I ebuf
 162 is used to return error text and is only set when
 163 .B pcap_open_offline()
 164 fails and returns
 165 .BR NULL .
 166 .PP
 167 .B pcap_dump_open()
 168 is called to open a ``savefile'' for writing. The name "-" in a synonym
 169 for
 170 .BR stdout .
 171 .B NULL
 172 is returned on failure.
 173 .I p
 174 is a
 175 .I pcap
 176 struct as returned by
 177 .B pcap_open_offline()
 178 or
 179 .BR pcap_open_live() .
 180 .I fname
 181 specifies the name of the file to open.
 182 If
 183 .B NULL
 184 is returned,
 185 .B pcap_geterr()
 186 can be used to get the error text.
 187 .PP
 188 .B pcap_lookupdev()
 189 returns a pointer to a network device suitable for use with
 190 .B pcap_open_live()
 191 and
 192 .BR pcap_lookupnet() .
 193 If there is an error,
 194 .B NULL
 195 is returned and
 196 .I errbuf
 197 is filled in with an appropriate error message.
 198 .PP
 199 .B pcap_lookupnet()
 200 is used to determine the network number and mask
 201 associated with the network device
 202 .BR device .
 203 Both
 204 .I netp
 205 and
 206 .I maskp
 207 are
 208 .I bpf_u_int32
 209 pointers.
 210 A return of \-1 indicates an error in which case
 211 .I errbuf
 212 is filled in with an appropriate error message.
 213 .PP
 214 .B pcap_dispatch()
 215 is used to collect and process packets.
 216 .I cnt
 217 specifies the maximum number of packets to process before returning.
 218 This is not a minimum number; when reading a live capture, only one
 219 bufferful of packets is read at a time, so fewer than
 220 .I cnt
 221 packets may be processed. A
 222 .I cnt
 223 of \-1 processes all the packets received in one buffer when reading a
 224 live capture, or all the packets in the file when reading a
 225 ``savefile''.
 226 .I callback
 227 specifies a routine to be called with three arguments:
 228 a
 229 .I u_char
 230 pointer which is passed in from
 231 .BR pcap_dispatch() ,
 232 a pointer to the
 233 .I pcap_pkthdr
 234 struct (which precede the actual network headers and data),
 235 and a
 236 .I u_char
 237 pointer to the packet data.
 238 .PP
 239 The number of packets read is returned.
 240 0 is returned if no packets were read from a live capture (if, for
 241 example, they were discarded because they didn't pass the packet filter,
 242 or if, on platforms that support a read timeout that starts before any
 243 packets arrive, the timeout expires before any packets arrive, or if the
 244 file descriptor for the capture device is in non-blocking mode and no
 245 packets were available to be read) or if no more packets are available
 246 in a ``savefile.'' A return of \-1 indicates
 247 an error in which case
 248 .B pcap_perror()
 249 or
 250 .B pcap_geterr()
 251 may be used to display the error text.
 252 .PP
 253 .BR NOTE :
 254 when reading a live capture,
 255 .B pcap_dispatch()
 256 will not necessarily return when the read times out; on some platforms,
 257 the read timeout isn't supported, and, on other platforms, the timer
 258 doesn't start until at least one packet arrives.  This means that the
 259 read timeout should
 260 .B NOT
 261 be used in, for example, an interactive application, to allow the packet
 262 capture loop to ``poll'' for user input periodically, as there's no
 263 guarantee that
 264 .B pcap_dispatch()
 265 will return after the timeout expires.
 266 .PP
 267 .B pcap_loop()
 268 is similar to
 269 .B pcap_dispatch()
 270 except it keeps reading packets until
 271 .I cnt
 272 packets are processed or an error occurs.
 273 It does
 274 .B not
 275 return when live read timeouts occur.
 276 Rather, specifying a non-zero read timeout to
 277 .B pcap_open_live()
 278 and then calling
 279 .B pcap_dispatch()
 280 allows the reception and processing of any packets that arrive when the
 281 timeout occurs.
 282 A negative
 283 .I cnt
 284 causes
 285 .B pcap_loop()
 286 to loop forever (or at least until an error occurs).
 287 .PP
 288 .B pcap_next()
 289 returns a
 290 .I u_char
 291 pointer to the next packet.
 292 .PP
 293 .B pcap_dump()
 294 outputs a packet to the ``savefile'' opened with
 295 .BR pcap_dump_open() .
 296 Note that its calling arguments are suitable for use with
 297 .B pcap_dispatch()
 298 or
 299 .BR pcap_loop() .
 300 .PP
 301 .B pcap_compile()
 302 is used to compile the string
 303 .I str
 304 into a filter program.
 305 .I program
 306 is a pointer to a
 307 .I bpf_program
 308 struct and is filled in by
 309 .BR pcap_compile() .
 310 .I optimize
 311 controls whether optimization on the resulting code is performed.
 312 .I netmask
 313 specifies the netmask of the local net.
 314 A return of \-1 indicates an error in which case
 315 .BR pcap_geterr()
 316 may be used to display the error text.
 317 .PP
 318 .B pcap_compile_nopcap()
 319 is similar to
 320 .B pcap_compile()
 321 except that instead of passing a pcap structure, one passes the
 322 snaplen and linktype explicitly.  It is intended to be used for
 323 compiling filters for direct BPF usage, without necessarily having
 324 called
 325 .BR pcap_open() .
 326 A return of \-1 indicates an error; the error text is unavailable.
 327 .RB ( pcap_compile_nopcap()
 328 is a wrapper around
 329 .BR pcap_open_dead() ,
 330 .BR pcap_compile() ,
 331 and
 332 .BR pcap_close() ;
 333 the latter three routines can be used directly in order to get the error
 334 text for a compilation error.)
 335 .B
 336 .PP
 337 .B pcap_setfilter()
 338 is used to specify a filter program.
 339 .I fp
 340 is a pointer to a
 341 .I bpf_program
 342 struct, usually the result of a call to
 343 .BR pcap_compile() .
 344 .B \-1
 345 is returned on failure, in which case
 346 .BR pcap_geterr()
 347 may be used to display the error text;
 348 .B 0
 349 is returned on success.
 350 .PP
 351 .B pcap_freecode()
 352 is used to free up allocated memory pointed to by a
 353 .I bpf_program
 354 struct generated by
 355 .B pcap_compile()
 356 when that BPF program is no longer needed, for example after it
 357 has been made the filter program for a pcap structure by a call to
 358 .BR pcap_setfilter() .
 359 .PP
 360 .B pcap_datalink()
 361 returns the link layer type, e.g.
 362 .BR DLT_EN10MB .
 363 .PP
 364 .B pcap_snapshot()
 365 returns the snapshot length specified when
 366 .B pcap_open_live
 367 was called.
 368 .PP
 369 .B pcap_is_swapped()
 370 returns true if the current ``savefile'' uses a different byte order
 371 than the current system.
 372 .PP
 373 .B pcap_major_version()
 374 returns the major number of the version of the pcap used to write the
 375 savefile.
 376 .PP
 377 .B pcap_minor_version()
 378 returns the minor number of the version of the pcap used to write the
 379 savefile.
 380 .PP
 381 .B pcap_file()
 382 returns the name of the ``savefile.''
 383 .PP
 384 .B int pcap_stats()
 385 returns 0 and fills in a
 386 .B pcap_stat
 387 struct. The values represent packet statistics from the start of the
 388 run to the time of the call. If there is an error or the under lying
 389 packet capture doesn't support packet statistics, \-1 is returned and
 390 the error text can be obtained with
 391 .B pcap_perror()
 392 or
 393 .BR pcap_geterr() .
 394 .PP
 395 .B pcap_fileno()
 396 returns the file descriptor number of the ``savefile.''
 397 .PP
 398 .B pcap_perror()
 399 prints the text of the last pcap library error on
 400 .BR stderr ,
 401 prefixed by
 402 .IR prefix .
 403 .PP
 404 .B pcap_geterr()
 405 returns the error text pertaining to the last pcap library error.
 406 .BR NOTE :
 407 the pointer it returns will no longer point to a valid error message
 408 string after the
 409 .B pcap_t
 410 passed to it is closed; you must use or copy the string before closing
 411 the
 412 .BR pcap_t .
 413 .PP
 414 .B pcap_strerror()
 415 is provided in case
 416 .BR strerror (1)
 417 isn't available.
 418 .PP
 419 .B pcap_close()
 420 closes the files associated with
 421 .I p
 422 and deallocates resources.
 423 .PP
 424 .B pcap_dump_close()
 425 closes the ``savefile.''
 426 .PP
 427 .SH SEE ALSO
 428 tcpdump(1), tcpslice(1)
 429 .SH AUTHORS
 430 The original authors are:
 431 .LP
 432 Van Jacobson,
 433 Craig Leres and
 434 Steven McCanne, all of the
 435 Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.
 436 .LP
 437 The current version is available from "The Tcpdump Group"'s Web site at
 438 .LP
 439 .RS
 440 .I http://www.tcpdump.org/
 441 .RE
 442 .SH BUGS
 443 Please send problems, bugs, questions, desirable enhancements, etc. to:
 444 .LP
 445 .RS
 446 tcpdump-workers@tcpdump.org
 447 .RE
 448 .LP
 449 Please send source code contributions, etc. to:
 450 .LP
 451 .RS
 452 patches@tcpdump.org
 453 .RE