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

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