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