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

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