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