The Tcpdump Group git mirrors - libpcap/blob - pcap_findalldevs.3pcap

   1 .\" Copyright (c) 1994, 1996, 1997
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that: (1) source code distributions
   6 .\" retain the above copyright notice and this paragraph in its entirety, (2)
   7 .\" distributions including binary code include the above copyright notice and
   8 .\" this paragraph in its entirety in the documentation or other materials
   9 .\" provided with the distribution, and (3) all advertising materials mentioning
  10 .\" features or use of this software display the following acknowledgement:
  11 .\" ``This product includes software developed by the University of California,
  12 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
  13 .\" the University nor the names of its contributors may be used to endorse
  14 .\" or promote products derived from this software without specific prior
  15 .\" written permission.
  16 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  17 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  18 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  19 .\"
  20 .TH PCAP_FINDALLDEVS 3PCAP "11 March 2025"
  21 .SH NAME
  22 pcap_findalldevs, pcap_freealldevs \- get a list of capture devices, and
  23 free that list
  24 .SH SYNOPSIS
  25 .nf
  26 .ft B
  27 #include <pcap/pcap.h>
  28 .ft
  29 .LP
  30 .nf
  31 .ft B
  32 char errbuf[PCAP_ERRBUF_SIZE];
  33 .ft
  34 .LP
  35 .ft B
  36 int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf);
  37 void pcap_freealldevs(pcap_if_t *alldevs);
  38 .ft
  39 .fi
  40 .SH DESCRIPTION
  41 .BR pcap_findalldevs ()
  42 constructs a list of packet capture devices that potentially can be opened
  43 with
  44 .BR \%pcap_create (3PCAP)
  45 and
  46 .BR \%pcap_activate (3PCAP)
  47 or with
  48 .BR \%pcap_open_live (3PCAP).
  49 .I alldevsp
  50 is a pointer to a
  51 .BR "pcap_if_t *" ;
  52 .I errbuf
  53 is a buffer large enough to hold at least
  54 .B \%PCAP_ERRBUF_SIZE
  55 chars.
  56 .PP
  57 The most common type of a capture device is a regular network interface, in
  58 which case the capture device name is the same as the OS network interface
  59 name, for example, "eth0".  All supported Linux systems, as well as recent
  60 versions of macOS and Solaris, implement a special "any" pseudo-interface,
  61 which captures packets from all regular network interfaces and does not
  62 support promiscuous mode.  If the "any" pseudo-interface is available, the
  63 list of capture devices includes it.  What is considered a regular network
  64 interface is an implementation detail of the OS (for example, on Linux this
  65 includes SocketCAN devices), so packets captured on the "any" pseudo-interface
  66 may represent more different network protocols than expected.  The list of
  67 capture devices, depending on how libpcap was compiled and how the host is
  68 configured, often also includes at least some of the following types:
  69 Bluetooth, DAG, D-Bus, Netlink, SNF and USB.
  70 .PP
  71 For most capture device types enumeration of devices does not require special
  72 privileges or a specific device state (i.e. being "up" or ready in any other
  73 sense).  However, capturing of packets on a device usually depends on some
  74 conditions, so
  75 .BR \%pcap_findalldevs ()
  76 may list devices that a subsequent call to
  77 .BR pcap_activate ()
  78 would reject -- then, for example, the error code
  79 .B \%PCAP_ERROR_PERM_DENIED
  80 would make the same sense as not being able to read from a particular file in
  81 a directory that allows to list the files.  This is the intended design.
  82 .PP
  83 If
  84 .BR pcap_findalldevs ()
  85 succeeds, the pointer pointed to by
  86 .I alldevsp
  87 is set to point to the first element of the list, or to
  88 .B NULL
  89 if no devices were found (this is considered success).
  90 Each element of the list is of type
  91 .BR pcap_if_t ,
  92 and has the following members:
  93 .RS
  94 .TP
  95 .B next
  96 if not
  97 .BR NULL ,
  98 a pointer to the next element in the list;
  99 .B NULL
 100 for the last element of the list
 101 .TP
 102 .B name
 103 a pointer to a string giving a name for the device to pass to
 104 .BR pcap_create ()
 105 or
 106 .BR pcap_open_live ()
 107 .TP
 108 .B description
 109 if not
 110 .BR NULL ,
 111 a pointer to a string giving a human-readable description of the device
 112 .TP
 113 .B addresses
 114 a pointer to the first element of a list of network addresses for the
 115 device,
 116 or
 117 .B NULL
 118 if the device has no addresses
 119 .TP
 120 .B flags
 121 device flags:
 122 .RS
 123 .TP
 124 .B PCAP_IF_LOOPBACK
 125 set if the device is a loopback interface
 126 .TP
 127 .B PCAP_IF_UP
 128 set if the device is up
 129 .TP
 130 .B PCAP_IF_RUNNING
 131 set if the device is running
 132 .TP
 133 .B PCAP_IF_WIRELESS
 134 set if the device is a wireless interface; this includes IrDA as well as
 135 radio-based networks such as IEEE 802.15.4 and IEEE 802.11, so it
 136 doesn't just mean Wi-Fi
 137 .TP
 138 .B PCAP_IF_CONNECTION_STATUS
 139 a bitmask for an indication of whether the adapter is connected or not;
 140 for wireless interfaces, "connected" means "associated with a network"
 141 .TP
 142 The possible values for the connection status bits are:
 143 .TP
 144 .B PCAP_IF_CONNECTION_STATUS_UNKNOWN
 145 it's unknown whether the adapter is connected or not
 146 .TP
 147 .B PCAP_IF_CONNECTION_STATUS_CONNECTED
 148 the adapter is connected
 149 .TP
 150 .B PCAP_IF_CONNECTION_STATUS_DISCONNECTED
 151 the adapter is disconnected
 152 .TP
 153 .B PCAP_IF_CONNECTION_STATUS_NOT_APPLICABLE
 154 the notion of "connected" and "disconnected" don't apply to this
 155 interface; for example, it doesn't apply to a loopback device
 156 .RE
 157 .RE
 158 .PP
 159 Each element of the list of addresses is of type
 160 .BR pcap_addr_t ,
 161 and has the following members:
 162 .RS
 163 .TP
 164 .B next
 165 if not
 166 .BR NULL ,
 167 a pointer to the next element in the list;
 168 .B NULL
 169 for the last element of the list
 170 .TP
 171 .B addr
 172 a pointer to a
 173 .B "struct sockaddr"
 174 containing an address
 175 .TP
 176 .B netmask
 177 if not
 178 .BR NULL ,
 179 a pointer to a
 180 .B "struct sockaddr"
 181 that contains the netmask corresponding to the address pointed to by
 182 .B addr
 183 .TP
 184 .B broadaddr
 185 if not
 186 .BR NULL ,
 187 a pointer to a
 188 .B "struct sockaddr"
 189 that contains the broadcast address corresponding to the address pointed
 190 to by
 191 .BR addr ;
 192 may be
 193 .B NULL
 194 if the device doesn't support broadcasts
 195 .TP
 196 .B dstaddr
 197 if not
 198 .BR NULL ,
 199 a pointer to a
 200 .B "struct sockaddr"
 201 that contains the destination address corresponding to the address pointed
 202 to by
 203 .BR addr ;
 204 may be
 205 .B NULL
 206 if the device isn't a point-to-point interface
 207 .RE
 208 .PP
 209 Note that the addresses in the list of addresses might be IPv4
 210 addresses, IPv6 addresses, or some other type of addresses, so you must
 211 check the
 212 .B sa_family
 213 member of the
 214 .B "struct sockaddr"
 215 before interpreting the contents of the address; do not assume that the
 216 addresses are all IPv4 addresses, or even all IPv4 or IPv6 addresses.
 217 IPv4 addresses have the value
 218 .BR AF_INET ,
 219 IPv6 addresses have the value
 220 .B AF_INET6
 221 (which older operating systems that don't support IPv6 might not
 222 define), and other addresses have other values.  Whether other addresses
 223 are returned, and what types they might have is platform-dependent.
 224 Namely, link-layer addresses, such as Ethernet MAC addresses, have the value
 225 .B AF_PACKET
 226 (on Linux) or
 227 .B AF_LINK
 228 (on AIX, FreeBSD, Haiku, illumos, macOS, NetBSD and OpenBSD) or are not
 229 returned at all (on GNU/Hurd and Solaris).
 230 .PP
 231 For IPv4 addresses, the
 232 .B "struct sockaddr"
 233 pointer can be interpreted as if it pointed to a
 234 .BR "struct sockaddr_in" ;
 235 for IPv6 addresses, it can be interpreted as if it pointed to a
 236 .BR "struct sockaddr_in6".
 237 For link-layer addresses, it can be interpreted as if it pointed to a
 238 .B "struct sockaddr_ll"
 239 (for
 240 .BR AF_PACKET ,
 241 see
 242 .BR packet (7))
 243 or a
 244 .B "struct sockaddr_dl"
 245 (for
 246 .BR AF_LINK ).
 247 .PP
 248 The list of devices must be freed with
 249 .BR pcap_freealldevs (),
 250 which frees the list pointed to by
 251 .IR alldevs .
 252 .SH RETURN VALUE
 253 .BR pcap_findalldevs ()
 254 returns
 255 .B 0
 256 on success and
 257 .B PCAP_ERROR
 258 on failure; as indicated, finding no
 259 devices is considered success, rather than failure, so
 260 .B 0
 261 will be
 262 returned in that case. If
 263 .B PCAP_ERROR
 264 is returned,
 265 .I errbuf
 266 is filled in with an appropriate error message,
 267 and the pointer pointed to by
 268 .I alldevsp
 269 is set to
 270 .BR NULL .
 271 .SH BACKWARD COMPATIBILITY
 272 .PP
 273 The
 274 .B PCAP_IF_UP
 275 and
 276 .B PCAP_IF_RUNNING
 277 constants became available in libpcap release 1.6.1.
 278 .PP
 279 The
 280 .BR PCAP_IF_WIRELESS ,
 281 .BR PCAP_IF_CONNECTION_STATUS ,
 282 .BR PCAP_IF_CONNECTION_STATUS_UNKNOWN ,
 283 .BR PCAP_IF_CONNECTION_STATUS_CONNECTED ,
 284 .BR PCAP_IF_CONNECTION_STATUS_DISCONNECTED ,
 285 and
 286 .B PCAP_IF_CONNECTION_STATUS_NOT_APPLICABLE
 287 constants became available in libpcap release 1.9.0.
 288 .SH SEE ALSO
 289 .BR pcap (3PCAP)