dect
/
libpcap
Archived
13
0
Fork 0
This repository has been archived on 2022-02-17. You can view files and clone it, but cannot push or open issues or pull requests.
libpcap/pcap_open_live.3pcap

108 lines
3.6 KiB
Plaintext
Raw Normal View History

.\" @(#) $Header: /tcpdump/master/libpcap/pcap_open_live.3pcap,v 1.1 2008-04-05 20:19:42 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.
.\"
.TH PCAP_OPEN_LIVE 3PCAP "4 April 2008"
.SH NAME
pcap_open_live \- open a device for capturing
.SH SYNOPSIS
.nf
.ft B
#include <pcap.h>
.ft
.LP
.nf
.ft B
char errbuf[PCAP_ERRBUF_SIZE];
.ft
.LP
.ft B
pcap_t *pcap_open_live(const char *device, int snaplen,
.ti +8
int promisc, int to_ms, char *errbuf);
.ft
.fi
.SH DESCRIPTION
.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.
.PP
.I snaplen
specifies the maximum number of bytes to capture. If this value is less
than the size of a packet that is captured, only the first
.I snaplen
bytes of that packet will be captured and provided as packet data. A
value of 65535 should be sufficient, on most if not all networks, to
capture all the data available from the packet.
.PP
.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.
.PP
.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. A zero value for
.IR to_ms ,
on platforms that support a read timeout,
will cause a read to wait forever to allow enough packets to
arrive, with no timeout.
.SH RETURN VALUE
.B pcap_open_live()
returns a
.I pcap_t *
on success and
.B NULL
on failure.
If
.B NULL
is returned,
.I errbuf
is filled in with an appropriate error message.
.I errbuf
may also be set to warning text when
.B pcap_open_live()
succeds; to detect this case the caller should store a zero-length string in
.I errbuf
before calling
.B pcap_open_live()
and display the warning to the user if
.I errbuf
is no longer a zero-length string.
.I errbuf
is assumed to be able to hold at least
.B PCAP_ERRBUF_SIZE
chars.