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

   1 .\" @(#) $Header: /tcpdump/master/libpcap/Attic/pcap.3,v 1.12 2000-10-22 02:21:34 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 "24 July 2000"
  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 .ft
  66 .LP
  67 .ft B
  68 u_char *pcap_next(pcap_t *p, struct pcap_pkthdr *h)
  69 .ft
  70 .LP
  71 .ft B
  72 int pcap_datalink(pcap_t *p)
  73 int pcap_snapshot(pcap_t *p)
  74 int pcap_is_swapped(pcap_t *p)
  75 int pcap_major_version(pcap_t *p)
  76 int pcap_minor_version(pcap_t *p)
  77 int pcap_stats(pcap_t *p, struct pcap_stat *ps)
  78 FILE *pcap_file(pcap_t *p)
  79 int pcap_fileno(pcap_t *p)
  80 void pcap_perror(pcap_t *p, char *prefix)
  81 char *pcap_geterr(pcap_t *p)
  82 char *pcap_strerror(int error)
  83 .ft
  84 .LP
  85 .ft B
  86 void pcap_close(pcap_t *p)
  87 void pcap_dump_close(pcap_dumper_t *p)
  88 .ft
  89 .fi
  90 .SH DESCRIPTION
  91 The Packet Capture library
  92 provides a high level interface to packet capture systems. All packets
  93 on the network, even those destined for other hosts, are accessible
  94 through this mechanism.
  95 .PP
  96 .SH ROUTINES
  97 NOTE:
  98 .I errbuf
  99 in
 100 .B pcap_open_live(),
 101 .B pcap_open_offline(),
 102 .B pcap_lookupdev(),
 103 and
 104 .B pcap_lookupnet()
 105 is assumed to be able to hold at least
 106 .B PCAP_ERRBUF_SIZE
 107 chars.
 108 .PP
 109 .B pcap_open_live()
 110 is used to obtain a packet capture descriptor to look
 111 at packets on the network.
 112 .I device
 113 is a string that specifies the network device to open; on Linux systems
 114 with 2.2 or later kernels, a
 115 .I device
 116 argument of "any" or
 117 .B NULL
 118 can be used to capture packets from all interfaces.
 119 .I snaplen
 120 specifies the maximum number of bytes to capture.
 121 .I promisc
 122 specifies if the interface is to be put into promiscuous mode.
 123 (Note that even if this parameter is false, the interface
 124 could well be in promiscuous mode for some other reason.)
 125 .I to_ms
 126 specifies the read timeout in milliseconds.
 127 .I ebuf
 128 is used to return error text and is only set when
 129 .B pcap_open_live()
 130 fails and returns
 131 .BR NULL .
 132 .PP
 133 .B pcap_open_dead()
 134 is used for creating a
 135 .B pcap_t
 136 structure to use when calling the other functions in libpcap.  It is
 137 typically used when just using libpcap for compiling BPF code.
 138 .PP
 139 .B pcap_open_offline()
 140 is called to open a ``savefile'' for reading.
 141 .I fname
 142 specifies the name of the file to open. The file has
 143 the same format as those used by
 144 .B tcpdump(1)
 145 and
 146 .BR tcpslice(1) .
 147 The name "-" in a synonym for
 148 .BR stdin .
 149 .I ebuf
 150 is used to return error text and is only set when
 151 .B pcap_open_offline()
 152 fails and returns
 153 .BR NULL .
 154 .PP
 155 .B pcap_dump_open()
 156 is called to open a ``savefile'' for writing. The name "-" in a synonym
 157 for
 158 .BR stdout .
 159 .B NULL
 160 is returned on failure.
 161 .I p
 162 is a
 163 .I pcap
 164 struct as returned by
 165 .B pcap_open_offline()
 166 or
 167 .BR pcap_open_live() .
 168 .I fname
 169 specifies the name of the file to open.
 170 If
 171 .B NULL
 172 is returned,
 173 .B pcap_geterr()
 174 can be used to get the error text.
 175 .PP
 176 .B pcap_lookupdev()
 177 returns a pointer to a network device suitable for use with
 178 .B pcap_open_live()
 179 and
 180 .BR pcap_lookupnet() .
 181 If there is an error,
 182 .B NULL
 183 is returned and
 184 .I errbuf
 185 is filled in with an appropriate error message.
 186 .PP
 187 .B pcap_lookupnet()
 188 is used to determine the network number and mask
 189 associated with the network device
 190 .BR device .
 191 Both
 192 .I netp
 193 and
 194 .I maskp
 195 are
 196 .I bpf_u_int32
 197 pointers.
 198 A return of -1 indicates an error in which case
 199 .I errbuf
 200 is filled in with an appropriate error message.
 201 .PP
 202 .B pcap_dispatch()
 203 is used to collect and process packets.
 204 .I cnt
 205 specifies the maximum number of packets to process before returning. A
 206 .I cnt
 207 of -1 processes all the packets received in one buffer. A
 208 .I cnt
 209 of 0 processes all packets until an error occurs,
 210 .B EOF
 211 is reached, or the read times out (when doing live reads and a non-zero
 212 read timeout is specified).
 213 .I callback
 214 specifies a routine to be called with three arguments:
 215 a
 216 .I u_char
 217 pointer which is passed in from
 218 .BR pcap_dispatch() ,
 219 a pointer to the
 220 .I pcap_pkthdr
 221 struct (which precede the actual network headers and data),
 222 and a
 223 .I u_char
 224 pointer to the packet data. The number of packets read is returned.
 225 Zero is returned when
 226 .B EOF
 227 is reached in a ``savefile.'' A return of -1 indicates
 228 an error in which case
 229 .B pcap_perror()
 230 or
 231 .BR pcap_geterr()
 232 may be used to display the error text.
 233 .PP
 234 .B pcap_dump()
 235 outputs a packet to the ``savefile'' opened with
 236 .BR pcap_dump_open() .
 237 Note that its calling arguments are suitable for use with
 238 .BR pcap_dispatch() .
 239 .PP
 240 .B pcap_compile()
 241 is used to compile the string
 242 .I str
 243 into a filter program.
 244 .I program
 245 is a pointer to a
 246 .I bpf_program
 247 struct and is filled in by
 248 .BR pcap_compile() .
 249 .I optimize
 250 controls whether optimization on the resulting code is performed.
 251 .I netmask
 252 specifies the netmask of the local net.
 253 .PP
 254 .B pcap_compile_nopcap()
 255 is similar to
 256 .B pcap_compile()
 257 except that instead of passing a pcap structure, one passes the
 258 snaplen and linktype explicitly.  It is intended to be used for
 259 compiling filters for direct bpf usage, without necessarily having
 260 called
 261 .BR pcap_open() .
 262 .PP
 263 .B pcap_setfilter()
 264 is used to specify a filter program.
 265 .I fp
 266 is a pointer to an array of
 267 .I bpf_program
 268 struct, usually the result of a call to
 269 .BR pcap_compile() .
 270 .B \-1
 271 is returned on failure;
 272 .B 0
 273 is returned on success.
 274 .PP
 275 .B pcap_loop()
 276 is similar to
 277 .B pcap_dispatch()
 278 except it keeps reading packets until
 279 .I cnt
 280 packets are processed or an error occurs.
 281 It does
 282 .B not
 283 return when live read timeouts occur.
 284 Rather, specifying a non-zero read timeout to
 285 .B pcap_open_live()
 286 and then calling
 287 .B pcap_dispatch()
 288 allows the reception and processing of any packets that arrive when the
 289 timeout occurs.
 290 A negative
 291 .I cnt
 292 causes
 293 .B pcap_loop()
 294 to loop forever (or at least until an error occurs).
 295 .PP
 296 .B pcap_next()
 297 returns a
 298 .I u_char
 299 pointer to the next packet.
 300 .PP
 301 .B pcap_datalink()
 302 returns the link layer type, e.g.
 303 .BR DLT_EN10MB .
 304 .PP
 305 .B pcap_snapshot()
 306 returns the snapshot length specified when
 307 .B pcap_open_live
 308 was called.
 309 .PP
 310 .B pcap_is_swapped()
 311 returns true if the current ``savefile'' uses a different byte order
 312 than the current system.
 313 .PP
 314 .B pcap_major_version()
 315 returns the major number of the version of the pcap used to write the
 316 savefile.
 317 .PP
 318 .B pcap_minor_version()
 319 returns the minor number of the version of the pcap used to write the
 320 savefile.
 321 .PP
 322 .B pcap_file()
 323 returns the name of the ``savefile.''
 324 .PP
 325 .B int pcap_stats()
 326 returns 0 and fills in a
 327 .B pcap_stat
 328 struct. The values represent packet statistics from the start of the
 329 run to the time of the call. If there is an error or the under lying
 330 packet capture doesn't support packet statistics, -1 is returned and
 331 the error text can be obtained with
 332 .B pcap_perror()
 333 or
 334 .BR pcap_geterr() .
 335 .PP
 336 .B pcap_fileno()
 337 returns the file descriptor number of the ``savefile.''
 338 .PP
 339 .B pcap_perror()
 340 prints the text of the last pcap library error on
 341 .BR stderr ,
 342 prefixed by
 343 .IR prefix .
 344 .PP
 345 .B pcap_geterr()
 346 returns the error text pertaining to the last pcap library error.
 347 .PP
 348 .B pcap_strerror()
 349 is provided in case
 350 .BR strerror (1)
 351 isn't available.
 352 .PP
 353 .B pcap_close()
 354 closes the files associated with
 355 .I p
 356 and deallocates resources.
 357 .PP
 358 .B pcap_dump_close()
 359 closes the ``savefile.''
 360 .PP
 361 .SH SEE ALSO
 362 tcpdump(1), tcpslice(1)
 363 .SH AUTHORS
 364 The original authors are:
 365 .LP
 366 Van Jacobson,
 367 Craig Leres and
 368 Steven McCanne, all of the
 369 Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.
 370 .LP
 371 The current version is available from "The Tcpdump Group"'s Web site at
 372 .LP
 373 .RS
 374 .I http://www.tcpdump.org/
 375 .RE
 376 .SH BUGS
 377 Please send problems, bugs, questions, desirable enhancements, etc. to:
 378 .LP
 379 .RS
 380 tcpdump-workers@tcpdump.org
 381 .RE
 382 .LP
 383 Please send source code contributions, etc. to:
 384 .LP
 385 .RS
 386 patches@tcpdump.org
 387 .RE