The Tcpdump Group git mirrors - libpcap/blob - pcap.3

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