target/linux/etrax-2.6/image/e100boot/src/libpcap-0.4/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_setfilter()
 229 is used to specify a filter program.
 230 .I fp
 231 is a pointer to an array of
 232 .I bpf_program
 233 struct, usually the result of a call to
 234 .BR pcap_compile() .
 235 .B \-1
 236 is returned on failure;
 237 .B 0
 238 is returned on success.
 239 .PP
 240 .B pcap_loop()
 241 is similar to
 242 .B pcap_dispatch()
 243 except it keeps reading packets until
 244 .I cnt
 245 packets are processed or an error occurs.
 246 It does
 247 .B not
 248 return when live read timeouts occur.
 249 Rather, specifying a non-zero read timeout to
 250 .B pcap_open_live()
 251 and then calling
 252 .B pcap_dispatch()
 253 allows the reception and processing of any packets that arrive when the
 254 timeout occurs.
 255 A negative
 256 .I cnt
 257 causes
 258 .B pcap_loop()
 259 to loop forever (or at least until an error occurs).
 260 .PP
 261 .B pcap_next()
 262 returns a
 263 .I u_char
 264 pointer to the next packet.
 265 .PP
 266 .B pcap_datalink()
 267 returns the link layer type, e.g.
 268 .BR DLT_EN10MB .
 269 .PP
 270 .B pcap_snapshot()
 271 returns the snapshot length specified when
 272 .B pcap_open_live
 273 was called.
 274 .PP
 275 .B pcap_is_swapped()
 276 returns true if the current ``savefile'' uses a different byte order
 277 than the current system.
 278 .PP
 279 .B pcap_major_version()
 280 returns the major number of the version of the pcap used to write the
 281 savefile.
 282 .PP
 283 .B pcap_minor_version()
 284 returns the minor number of the version of the pcap used to write the
 285 savefile.
 286 .PP
 287 .B pcap_file()
 288 returns the name of the ``savefile.''
 289 .PP
 290 .B int pcap_stats()
 291 returns 0 and fills in a
 292 .B pcap_stat
 293 struct. The values represent packet statistics from the start of the
 294 run to the time of the call. If there is an error or the under lying
 295 packet capture doesn't support packet statistics, -1 is returned and
 296 the error text can be obtained with
 297 .B pcap_perror()
 298 or
 299 .BR pcap_geterr() .
 300 .PP
 301 .B pcap_fileno()
 302 returns the file descriptor number of the ``savefile.''
 303 .PP
 304 .B pcap_perror()
 305 prints the text of the last pcap library error on
 306 .BR stderr ,
 307 prefixed by
 308 .IR prefix .
 309 .PP
 310 .B pcap_geterr()
 311 returns the error text pertaining to the last pcap library error.
 312 .PP
 313 .B pcap_strerror()
 314 is provided in case
 315 .BR strerror (1)
 316 isn't available.
 317 .PP
 318 .B pcap_close()
 319 closes the files associated with
 320 .I p
 321 and deallocates resources.
 322 .PP
 323 .B pcap_dump_close()
 324 closes the ``savefile.''
 325 .PP
 326 .SH SEE ALSO
 327 tcpdump(1), tcpslice(1)
 328 .SH AUTHORS
 329 Van Jacobson,
 330 Craig Leres and
 331 Steven McCanne, all of the
 332 Lawrence Berkeley National Laboratory, University of California, Berkeley, CA.
 333 .LP
 334 The current version is available via anonymous ftp:
 335 .LP
 336 .RS
 337 .I ftp://ftp.ee.lbl.gov/libpcap.tar.Z
 338 .RE
 339 .SH BUGS
 340 Please send bug reports to libpcap@ee.lbl.gov.