|
Packit |
209cc3 |
.\" Copyright (c) 1994, 1996, 1997
|
|
Packit |
209cc3 |
.\" The Regents of the University of California. All rights reserved.
|
|
Packit |
209cc3 |
.\"
|
|
Packit |
209cc3 |
.\" Redistribution and use in source and binary forms, with or without
|
|
Packit |
209cc3 |
.\" modification, are permitted provided that: (1) source code distributions
|
|
Packit |
209cc3 |
.\" retain the above copyright notice and this paragraph in its entirety, (2)
|
|
Packit |
209cc3 |
.\" distributions including binary code include the above copyright notice and
|
|
Packit |
209cc3 |
.\" this paragraph in its entirety in the documentation or other materials
|
|
Packit |
209cc3 |
.\" provided with the distribution, and (3) all advertising materials mentioning
|
|
Packit |
209cc3 |
.\" features or use of this software display the following acknowledgement:
|
|
Packit |
209cc3 |
.\" ``This product includes software developed by the University of California,
|
|
Packit |
209cc3 |
.\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
|
|
Packit |
209cc3 |
.\" the University nor the names of its contributors may be used to endorse
|
|
Packit |
209cc3 |
.\" or promote products derived from this software without specific prior
|
|
Packit |
209cc3 |
.\" written permission.
|
|
Packit |
209cc3 |
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
|
|
Packit |
209cc3 |
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
|
Packit |
209cc3 |
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
|
Packit |
209cc3 |
.\"
|
|
Packit |
209cc3 |
.TH PCAP_FINDALLDEVS 3PCAP "22 August 2018"
|
|
Packit |
209cc3 |
.SH NAME
|
|
Packit |
209cc3 |
pcap_findalldevs, pcap_freealldevs \- get a list of capture devices, and
|
|
Packit |
209cc3 |
free that list
|
|
Packit |
209cc3 |
.SH SYNOPSIS
|
|
Packit |
209cc3 |
.nf
|
|
Packit |
209cc3 |
.ft B
|
|
Packit |
209cc3 |
#include <pcap/pcap.h>
|
|
Packit |
209cc3 |
.ft
|
|
Packit |
209cc3 |
.LP
|
|
Packit |
209cc3 |
.nf
|
|
Packit |
209cc3 |
.ft B
|
|
Packit |
209cc3 |
char errbuf[PCAP_ERRBUF_SIZE];
|
|
Packit |
209cc3 |
.ft
|
|
Packit |
209cc3 |
.LP
|
|
Packit |
209cc3 |
.ft B
|
|
Packit |
209cc3 |
int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf);
|
|
Packit |
209cc3 |
void pcap_freealldevs(pcap_if_t *alldevs);
|
|
Packit |
209cc3 |
.ft
|
|
Packit |
209cc3 |
.fi
|
|
Packit |
209cc3 |
.SH DESCRIPTION
|
|
Packit |
209cc3 |
.B pcap_findalldevs()
|
|
Packit |
209cc3 |
constructs a list of network devices that can be opened with
|
|
Packit |
209cc3 |
.B pcap_create(3PCAP)
|
|
Packit |
209cc3 |
and
|
|
Packit |
209cc3 |
.B pcap_activate(3PCAP)
|
|
Packit |
209cc3 |
or with
|
|
Packit |
209cc3 |
.BR pcap_open_live(3PCAP) .
|
|
Packit |
209cc3 |
(Note that there may be network devices that cannot be opened by the
|
|
Packit |
209cc3 |
process calling
|
|
Packit |
209cc3 |
.BR pcap_findalldevs() ,
|
|
Packit |
209cc3 |
because, for example, that process does not have sufficient privileges
|
|
Packit |
209cc3 |
to open them for capturing; if so, those devices will not appear on the
|
|
Packit |
209cc3 |
list.)
|
|
Packit |
209cc3 |
If
|
|
Packit |
209cc3 |
.B pcap_findalldevs()
|
|
Packit |
209cc3 |
succeeds, the pointer pointed to by
|
|
Packit |
209cc3 |
.I alldevsp
|
|
Packit |
209cc3 |
is set to point to the first element of the list, or to
|
|
Packit |
209cc3 |
.B NULL
|
|
Packit |
209cc3 |
if no devices were found (this is considered success).
|
|
Packit |
209cc3 |
Each element of the list is of type
|
|
Packit |
209cc3 |
.BR pcap_if_t ,
|
|
Packit |
209cc3 |
and has the following members:
|
|
Packit |
209cc3 |
.RS
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B next
|
|
Packit |
209cc3 |
if not
|
|
Packit |
209cc3 |
.BR NULL ,
|
|
Packit |
209cc3 |
a pointer to the next element in the list;
|
|
Packit |
209cc3 |
.B NULL
|
|
Packit |
209cc3 |
for the last element of the list
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B name
|
|
Packit |
209cc3 |
a pointer to a string giving a name for the device to pass to
|
|
Packit |
209cc3 |
.B pcap_open_live()
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B description
|
|
Packit |
209cc3 |
if not
|
|
Packit |
209cc3 |
.BR NULL ,
|
|
Packit |
209cc3 |
a pointer to a string giving a human-readable description of the device
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B addresses
|
|
Packit |
209cc3 |
a pointer to the first element of a list of network addresses for the
|
|
Packit |
209cc3 |
device,
|
|
Packit |
209cc3 |
or
|
|
Packit |
209cc3 |
.B NULL
|
|
Packit |
209cc3 |
if the device has no addresses
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B flags
|
|
Packit |
209cc3 |
device flags:
|
|
Packit |
209cc3 |
.RS
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B PCAP_IF_LOOPBACK
|
|
Packit |
209cc3 |
set if the device is a loopback interface
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B PCAP_IF_UP
|
|
Packit |
209cc3 |
set if the device is up
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B PCAP_IF_RUNNING
|
|
Packit |
209cc3 |
set if the device is running
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B PCAP_IF_WIRELESS
|
|
Packit |
209cc3 |
set if the device is a wireless interface; this includes IrDA as well as
|
|
Packit |
209cc3 |
radio-based networks such as IEEE 802.15.4 and IEEE 802.11, so it
|
|
Packit |
209cc3 |
doesn't just mean Wi-Fi
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B PCAP_IF_CONNECTION_STATUS
|
|
Packit |
209cc3 |
a bitmask for an indication of whether the adapter is connected or not;
|
|
Packit |
209cc3 |
for wireless interfaces, "connected" means "associated with a network"
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
The possible values for the connection status bits are:
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B PCAP_IF_CONNECTION_STATUS_UNKNOWN
|
|
Packit |
209cc3 |
it's unknown whether the adapter is connected or not
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B PCAP_IF_CONNECTION_STATUS_CONNECTED
|
|
Packit |
209cc3 |
the adapter is connected
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B PCAP_IF_CONNECTION_STATUS_DISCONNECTED
|
|
Packit |
209cc3 |
the adapter is disconnected
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B PCAP_IF_CONNECTION_STATUS_NOT_APPLICABLE
|
|
Packit |
209cc3 |
the notion of "connected" and "disconnected" don't apply to this
|
|
Packit |
209cc3 |
interface; for example, it doesn't apply to a loopback device
|
|
Packit |
209cc3 |
.RE
|
|
Packit |
209cc3 |
.RE
|
|
Packit |
209cc3 |
.PP
|
|
Packit |
209cc3 |
Each element of the list of addresses is of type
|
|
Packit |
209cc3 |
.BR pcap_addr_t ,
|
|
Packit |
209cc3 |
and has the following members:
|
|
Packit |
209cc3 |
.RS
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B next
|
|
Packit |
209cc3 |
if not
|
|
Packit |
209cc3 |
.BR NULL ,
|
|
Packit |
209cc3 |
a pointer to the next element in the list;
|
|
Packit |
209cc3 |
.B NULL
|
|
Packit |
209cc3 |
for the last element of the list
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B addr
|
|
Packit |
209cc3 |
a pointer to a
|
|
Packit |
209cc3 |
.B "struct sockaddr"
|
|
Packit |
209cc3 |
containing an address
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B netmask
|
|
Packit |
209cc3 |
if not
|
|
Packit |
209cc3 |
.BR NULL ,
|
|
Packit |
209cc3 |
a pointer to a
|
|
Packit |
209cc3 |
.B "struct sockaddr"
|
|
Packit |
209cc3 |
that contains the netmask corresponding to the address pointed to by
|
|
Packit |
209cc3 |
.B addr
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B broadaddr
|
|
Packit |
209cc3 |
if not
|
|
Packit |
209cc3 |
.BR NULL ,
|
|
Packit |
209cc3 |
a pointer to a
|
|
Packit |
209cc3 |
.B "struct sockaddr"
|
|
Packit |
209cc3 |
that contains the broadcast address corresponding to the address pointed
|
|
Packit |
209cc3 |
to by
|
|
Packit |
209cc3 |
.BR addr ;
|
|
Packit |
209cc3 |
may be null if the device doesn't support broadcasts
|
|
Packit |
209cc3 |
.TP
|
|
Packit |
209cc3 |
.B dstaddr
|
|
Packit |
209cc3 |
if not
|
|
Packit |
209cc3 |
.BR NULL ,
|
|
Packit |
209cc3 |
a pointer to a
|
|
Packit |
209cc3 |
.B "struct sockaddr"
|
|
Packit |
209cc3 |
that contains the destination address corresponding to the address pointed
|
|
Packit |
209cc3 |
to by
|
|
Packit |
209cc3 |
.BR addr ;
|
|
Packit |
209cc3 |
may be null if the device isn't a point-to-point interface
|
|
Packit |
209cc3 |
.RE
|
|
Packit |
209cc3 |
.PP
|
|
Packit |
209cc3 |
Note that the addresses in the list of addresses might be IPv4
|
|
Packit |
209cc3 |
addresses, IPv6 addresses, or some other type of addresses, so you must
|
|
Packit |
209cc3 |
check the
|
|
Packit |
209cc3 |
.B sa_family
|
|
Packit |
209cc3 |
member of the
|
|
Packit |
209cc3 |
.B "struct sockaddr"
|
|
Packit |
209cc3 |
before interpreting the contents of the address; do not assume that the
|
|
Packit |
209cc3 |
addresses are all IPv4 addresses, or even all IPv4 or IPv6 addresses.
|
|
Packit |
209cc3 |
IPv4 addresses have the value
|
|
Packit |
209cc3 |
.BR AF_INET ,
|
|
Packit |
209cc3 |
IPv6 addresses have the value
|
|
Packit |
209cc3 |
.B AF_INET6
|
|
Packit |
209cc3 |
(which older operating systems that don't support IPv6 might not
|
|
Packit |
209cc3 |
define), and other addresses have other values. Whether other addresses
|
|
Packit |
209cc3 |
are returned, and what types they might have is platform-dependent.
|
|
Packit |
209cc3 |
For IPv4 addresses, the
|
|
Packit |
209cc3 |
.B "struct sockaddr"
|
|
Packit |
209cc3 |
pointer can be interpreted as if it pointed to a
|
|
Packit |
209cc3 |
.BR "struct sockaddr_in" ;
|
|
Packit |
209cc3 |
for IPv6 addresses, it can be interpreted as if it pointed to a
|
|
Packit |
209cc3 |
.BR "struct sockaddr_in6".
|
|
Packit |
209cc3 |
.PP
|
|
Packit |
209cc3 |
The list of devices must be freed with
|
|
Packit |
209cc3 |
.BR pcap_freealldevs(3PCAP) ,
|
|
Packit |
209cc3 |
which frees the list pointed to by
|
|
Packit |
209cc3 |
.IR alldevs .
|
|
Packit |
209cc3 |
.SH RETURN VALUE
|
|
Packit |
209cc3 |
.B pcap_findalldevs()
|
|
Packit |
209cc3 |
returns 0 on success and
|
|
Packit |
209cc3 |
.B PCAP_ERROR
|
|
Packit |
209cc3 |
on failure; as indicated, finding no
|
|
Packit |
209cc3 |
devices is considered success, rather than failure, so 0 will be
|
|
Packit |
209cc3 |
returned in that case. If
|
|
Packit |
209cc3 |
.B PCAP_ERROR
|
|
Packit |
209cc3 |
is returned,
|
|
Packit |
209cc3 |
.I errbuf
|
|
Packit |
209cc3 |
is filled in with an appropriate error message.
|
|
Packit |
209cc3 |
.I errbuf
|
|
Packit |
209cc3 |
is assumed to be able to hold at least
|
|
Packit |
209cc3 |
.B PCAP_ERRBUF_SIZE
|
|
Packit |
209cc3 |
chars.
|
|
Packit |
209cc3 |
.SH BACKWARD COMPATIBILITY
|
|
Packit |
209cc3 |
.PP
|
|
Packit |
209cc3 |
The
|
|
Packit |
209cc3 |
.B PCAP_IF_UP
|
|
Packit |
209cc3 |
and
|
|
Packit |
209cc3 |
.B PCAP_IF_RUNNING
|
|
Packit |
209cc3 |
constants became available in libpcap release 1.6.1. The
|
|
Packit |
209cc3 |
.BR PCAP_IF_WIRELESS ,
|
|
Packit |
209cc3 |
.BR PCAP_IF_CONNECTION_STATUS ,
|
|
Packit |
209cc3 |
.BR PCAP_IF_CONNECTION_STATUS_UNKNOWN ,
|
|
Packit |
209cc3 |
.BR PCAP_IF_CONNECTION_STATUS_CONNECTED ,
|
|
Packit |
209cc3 |
.BR PCAP_IF_CONNECTION_STATUS_DISCONNECTED ,
|
|
Packit |
209cc3 |
and
|
|
Packit |
209cc3 |
.B PCAP_IF_CONNECTION_STATUS_NOT_APPLICABLE
|
|
Packit |
209cc3 |
constants became available in libpcap release 1.9.0.
|
|
Packit |
209cc3 |
.SH SEE ALSO
|
|
Packit |
209cc3 |
pcap(3PCAP)
|