2008-07-01 08:02:33 +00:00
|
|
|
.\" @(#) $Header: /tcpdump/master/libpcap/pcap_activate.3pcap,v 1.5 2008-07-01 08:02:33 guy Exp $
|
2008-04-06 02:53:21 +00:00
|
|
|
.\"
|
|
|
|
.\" 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_ACTIVATE 3PCAP "5 April 2008"
|
|
|
|
.SH NAME
|
|
|
|
pcap_activate \- activate a capture handle
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.ft B
|
|
|
|
#include <pcap/pcap.h>
|
|
|
|
.ft
|
|
|
|
.LP
|
|
|
|
.ft B
|
|
|
|
int pcap_activate(pcap_t *p);
|
|
|
|
.ft
|
|
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.B pcap_activate()
|
|
|
|
is used to activate a packet capture handle to look
|
|
|
|
at packets on the network, with the options that were set on the handle
|
|
|
|
being in effect.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
.B pcap_activate()
|
2008-04-09 21:26:12 +00:00
|
|
|
returns 0 on success without warnings,
|
|
|
|
.B PCAP_WARNING_PROMISC_NOTSUP
|
|
|
|
on success on a device that doesn't support promiscuous mode if
|
|
|
|
promiscuous mode was requested,
|
|
|
|
.B PCAP_WARNING
|
|
|
|
on success with any other warning,
|
2008-04-06 02:53:21 +00:00
|
|
|
.B PCAP_ERROR_ACTIVATED
|
|
|
|
if the handle has already been activated,
|
|
|
|
.B PCAP_ERROR_NO_SUCH_DEVICE
|
Add an error for "you don't have permission to open that device", as
that often means "sorry, this platform requires you to run as root or to
somehow tweak the system to give you capture privileges", and
applications might want to explain that in a way that does a better job
of letting the user know what they have to do.
Try to return or PCAP_ERROR_PERM_DENIED for open errors, rather than
just returning PCAP_ERROR, so that the application can, if it chooses,
try to explain the error better (as those two errors are the ones that
don't mean "there's probably some obscure OS or libpcap problem", but
mean, instead, "you made an error" or "you need to get permission to
capture").
Check for monitor mode *after* checking whether the device exists in the
first place; a non-existent device doesn't support monitor mode, but
that's because it doesn't, well, exist, and the latter would be a more
meaningful error.
Have pcap_open_live() supply an error message for return values other
than PCAP_ERROR, PCAP_ERROR_NO_SUCH_DEVICE, and PCAP_ERROR_PERM_DENIED -
those all supply error strings (PCAP_ERROR because it's for various OS
problems that might require debugging, and the other two because there
might be multiple causes).
2008-04-09 19:58:02 +00:00
|
|
|
if the capture source specified when the handle was created doesn't
|
|
|
|
exist,
|
|
|
|
.B PCAP_ERROR_PERM_DENIED
|
|
|
|
if the process doesn't have permission to open the capture source,
|
2008-04-06 02:53:21 +00:00
|
|
|
.B PCAP_ERROR_RFMON_NOTSUP
|
|
|
|
if monitor mode was specified but the capture source doesn't support
|
2008-07-01 08:02:33 +00:00
|
|
|
monitor mode,
|
|
|
|
.B PCAP_ERROR_IFACE_NOT_UP
|
|
|
|
if the capture source is not up, and
|
2008-04-06 02:53:21 +00:00
|
|
|
.B PCAP_ERROR
|
2008-07-01 08:02:33 +00:00
|
|
|
if another error occurred.
|
2008-04-06 02:53:21 +00:00
|
|
|
If
|
2008-04-09 21:26:12 +00:00
|
|
|
.B PCAP_WARNING
|
|
|
|
or
|
2008-04-06 02:53:21 +00:00
|
|
|
.B PCAP_ERROR
|
|
|
|
is returned,
|
|
|
|
.B pcap_geterr()
|
|
|
|
or
|
|
|
|
.B pcap_perror()
|
|
|
|
may be called with
|
|
|
|
.I p
|
2008-04-09 21:26:12 +00:00
|
|
|
as an argument to fetch or display a message describing the warning or
|
|
|
|
error.
|
2008-04-09 20:20:17 +00:00
|
|
|
If
|
2008-04-09 21:26:12 +00:00
|
|
|
.BR PCAP_WARNING_PROMISC_NOTSUP ,
|
|
|
|
.BR PCAP_ERROR_NO_SUCH_DEVICE ,
|
2008-04-09 20:20:17 +00:00
|
|
|
or
|
|
|
|
.B PCAP_ERROR_PERM_DENIED
|
|
|
|
is returned,
|
|
|
|
.B pcap_geterr()
|
|
|
|
or
|
|
|
|
.B pcap_perror()
|
|
|
|
may be called with
|
|
|
|
.I p
|
2008-04-09 21:26:12 +00:00
|
|
|
as an argument to fetch or display an message giving additional details
|
|
|
|
about the problem that might be useful for debugging the problem if it's
|
|
|
|
unexpected.
|
2008-04-06 02:53:21 +00:00
|
|
|
.SH SEE ALSO
|
|
|
|
pcap(3PCAP)
|