1PCAP_FINDALLDEVS(3PCAP)                                PCAP_FINDALLDEVS(3PCAP)
2
3
4

NAME

6       pcap_findalldevs, pcap_freealldevs - get a list of capture devices, and
7       free that list
8

SYNOPSIS

10       #include <pcap/pcap.h>
11
12       char errbuf[PCAP_ERRBUF_SIZE];
13
14       int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf);
15       void pcap_freealldevs(pcap_if_t *alldevs);
16

DESCRIPTION

18       pcap_findalldevs() constructs a list of network  devices  that  can  be
19       opened   with   pcap_create(3PCAP)  and  pcap_activate(3PCAP)  or  with
20       pcap_open_live(3PCAP).  (Note that there may be  network  devices  that
21       cannot  be  opened  by the process calling pcap_findalldevs(), because,
22       for example, that process does not have sufficient privileges  to  open
23       them  for capturing; if so, those devices will not appear on the list.)
24       If pcap_findalldevs() succeeds, the pointer pointed to by  alldevsp  is
25       set to point to the first element of the list, or to NULL if no devices
26       were found (this is considered success).  Each element of the  list  is
27       of type pcap_if_t, and has the following members:
28
29              next   if  not  NULL, a pointer to the next element in the list;
30                     NULL for the last element of the list
31
32              name   a pointer to a string giving a name  for  the  device  to
33                     pass to pcap_open_live()
34
35              description
36                     if  not  NULL, a pointer to a string giving a human-read‐
37                     able description of the device
38
39              addresses
40                     a pointer to the first  element  of  a  list  of  network
41                     addresses  for  the  device, or NULL if the device has no
42                     addresses
43
44              flags  device flags:
45
46                     PCAP_IF_LOOPBACK
47                            set if the device is a loopback interface
48
49                     PCAP_IF_UP
50                            set if the device is up
51
52                     PCAP_IF_RUNNING
53                            set if the device is running
54
55                     PCAP_IF_WIRELESS
56                            set if the device is a  wireless  interface;  this
57                            includes IrDA as well as radio-based networks such
58                            as IEEE 802.15.4 and IEEE 802.11,  so  it  doesn't
59                            just mean Wi-Fi
60
61                     PCAP_IF_CONNECTION_STATUS
62                            a bitmask for an indication of whether the adapter
63                            is connected  or  not;  for  wireless  interfaces,
64                            "connected" means "associated with a network"
65
66                     The possible values for the connection status bits are:
67
68                     PCAP_IF_CONNECTION_STATUS_UNKNOWN
69                            it's  unknown  whether the adapter is connected or
70                            not
71
72                     PCAP_IF_CONNECTION_STATUS_CONNECTED
73                            the adapter is connected
74
75                     PCAP_IF_CONNECTION_STATUS_DISCONNECTED
76                            the adapter is disconnected
77
78                     PCAP_IF_CONNECTION_STATUS_NOT_APPLICABLE
79                            the notion of "connected" and "disconnected" don't
80                            apply  to  this interface; for example, it doesn't
81                            apply to a loopback device
82
83       Each element of the list of addresses is of type pcap_addr_t,  and  has
84       the following members:
85
86              next   if  not  NULL, a pointer to the next element in the list;
87                     NULL for the last element of the list
88
89              addr   a pointer to a struct sockaddr containing an address
90
91              netmask
92                     if not NULL, a pointer to a struct sockaddr that contains
93                     the  netmask  corresponding  to the address pointed to by
94                     addr
95
96              broadaddr
97                     if not NULL, a pointer to a struct sockaddr that contains
98                     the   broadcast  address  corresponding  to  the  address
99                     pointed to by addr; may be null  if  the  device  doesn't
100                     support broadcasts
101
102              dstaddr
103                     if not NULL, a pointer to a struct sockaddr that contains
104                     the destination  address  corresponding  to  the  address
105                     pointed  to  by  addr;  may be null if the device isn't a
106                     point-to-point interface
107
108       Note that the  addresses  in  the  list  of  addresses  might  be  IPv4
109       addresses, IPv6 addresses, or some other type of addresses, so you must
110       check the sa_family member of the struct sockaddr  before  interpreting
111       the  contents  of the address; do not assume that the addresses are all
112       IPv4 addresses, or even all IPv4 or  IPv6  addresses.   IPv4  addresses
113       have  the  value AF_INET, IPv6 addresses have the value AF_INET6 (which
114       older operating systems that don't support IPv6 might not define),  and
115       other  addresses  have  other  values.   Whether  other  addresses  are
116       returned, and what types they might have  is  platform-dependent.   For
117       IPv4 addresses, the struct sockaddr pointer can be interpreted as if it
118       pointed to a struct sockaddr_in; for IPv6 addresses, it can  be  inter‐
119       preted as if it pointed to a struct sockaddr_in6.
120
121       The  list  of devices must be freed with pcap_freealldevs(3PCAP), which
122       frees the list pointed to by alldevs.
123

RETURN VALUE

125       pcap_findalldevs() returns 0 on success and PCAP_ERROR on  failure;  as
126       indicated,  finding no devices is considered success, rather than fail‐
127       ure, so 0 will be returned in that case.  If  PCAP_ERROR  is  returned,
128       errbuf  is  filled  in  with  an  appropriate error message.  errbuf is
129       assumed to be able to hold at least PCAP_ERRBUF_SIZE chars.
130

BACKWARD COMPATIBILITY

132       The PCAP_IF_UP and PCAP_IF_RUNNING constants became available in  libp‐
133       cap  release  1.6.1.   The PCAP_IF_WIRELESS, PCAP_IF_CONNECTION_STATUS,
134       PCAP_IF_CONNECTION_STATUS_UNKNOWN, PCAP_IF_CONNECTION_STATUS_CONNECTED,
135       PCAP_IF_CONNECTION_STATUS_DISCONNECTED,   and   PCAP_IF_CONNECTION_STA‐
136       TUS_NOT_APPLICABLE constants became available in libpcap release 1.9.0.
137

SEE ALSO

139       pcap(3PCAP)
140
141
142
143                                22 August 2018         PCAP_FINDALLDEVS(3PCAP)
Impressum