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 "9 August 2024"
  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 network devices that can be opened with
  43 .BR pcap_create (3PCAP)
  44 and
  45 .BR pcap_activate (3PCAP)
  46 or with
  47 .BR pcap_open_live (3PCAP).
  48 (Note that there may be network devices that cannot be opened by the
  49 process calling
  50 .BR pcap_findalldevs (),
  51 because, for example, that process does not have sufficient privileges
  52 to open them for capturing; if so, those devices will not appear on the
  53 list.)
  54 .I alldevsp
  55 is a pointer to a
  56 .BR "pcap_if_t *" ;
  57 .I errbuf
  58 is a buffer large enough to hold at least
  59 .B PCAP_ERRBUF_SIZE
  60 chars.
  61 .PP
  62 If
  63 .BR pcap_findalldevs ()
  64 succeeds, the pointer pointed to by
  65 .I alldevsp
  66 is set to point to the first element of the list, or to
  67 .B NULL
  68 if no devices were found (this is considered success).
  69 Each element of the list is of type
  70 .BR pcap_if_t ,
  71 and has the following members:
  72 .RS
  73 .TP
  74 .B next
  75 if not
  76 .BR NULL ,
  77 a pointer to the next element in the list;
  78 .B NULL
  79 for the last element of the list
  80 .TP
  81 .B name
  82 a pointer to a string giving a name for the device to pass to
  83 .BR pcap_open_live ()
  84 .TP
  85 .B description
  86 if not
  87 .BR NULL ,
  88 a pointer to a string giving a human-readable description of the device
  89 .TP
  90 .B addresses
  91 a pointer to the first element of a list of network addresses for the
  92 device,
  93 or
  94 .B NULL
  95 if the device has no addresses
  96 .TP
  97 .B flags
  98 device flags:
  99 .RS
 100 .TP
 101 .B PCAP_IF_LOOPBACK
 102 set if the device is a loopback interface
 103 .TP
 104 .B PCAP_IF_UP
 105 set if the device is up
 106 .TP
 107 .B PCAP_IF_RUNNING
 108 set if the device is running
 109 .TP
 110 .B PCAP_IF_WIRELESS
 111 set if the device is a wireless interface; this includes IrDA as well as
 112 radio-based networks such as IEEE 802.15.4 and IEEE 802.11, so it
 113 doesn't just mean Wi-Fi
 114 .TP
 115 .B PCAP_IF_CONNECTION_STATUS
 116 a bitmask for an indication of whether the adapter is connected or not;
 117 for wireless interfaces, "connected" means "associated with a network"
 118 .TP
 119 The possible values for the connection status bits are:
 120 .TP
 121 .B PCAP_IF_CONNECTION_STATUS_UNKNOWN
 122 it's unknown whether the adapter is connected or not
 123 .TP
 124 .B PCAP_IF_CONNECTION_STATUS_CONNECTED
 125 the adapter is connected
 126 .TP
 127 .B PCAP_IF_CONNECTION_STATUS_DISCONNECTED
 128 the adapter is disconnected
 129 .TP
 130 .B PCAP_IF_CONNECTION_STATUS_NOT_APPLICABLE
 131 the notion of "connected" and "disconnected" don't apply to this
 132 interface; for example, it doesn't apply to a loopback device
 133 .RE
 134 .RE
 135 .PP
 136 Each element of the list of addresses is of type
 137 .BR pcap_addr_t ,
 138 and has the following members:
 139 .RS
 140 .TP
 141 .B next
 142 if not
 143 .BR NULL ,
 144 a pointer to the next element in the list;
 145 .B NULL
 146 for the last element of the list
 147 .TP
 148 .B addr
 149 a pointer to a
 150 .B "struct sockaddr"
 151 containing an address
 152 .TP
 153 .B netmask
 154 if not
 155 .BR NULL ,
 156 a pointer to a
 157 .B "struct sockaddr"
 158 that contains the netmask corresponding to the address pointed to by
 159 .B addr
 160 .TP
 161 .B broadaddr
 162 if not
 163 .BR NULL ,
 164 a pointer to a
 165 .B "struct sockaddr"
 166 that contains the broadcast address corresponding to the address pointed
 167 to by
 168 .BR addr ;
 169 may be
 170 .B NULL
 171 if the device doesn't support broadcasts
 172 .TP
 173 .B dstaddr
 174 if not
 175 .BR NULL ,
 176 a pointer to a
 177 .B "struct sockaddr"
 178 that contains the destination address corresponding to the address pointed
 179 to by
 180 .BR addr ;
 181 may be
 182 .B NULL
 183 if the device isn't a point-to-point interface
 184 .RE
 185 .PP
 186 Note that the addresses in the list of addresses might be IPv4
 187 addresses, IPv6 addresses, or some other type of addresses, so you must
 188 check the
 189 .B sa_family
 190 member of the
 191 .B "struct sockaddr"
 192 before interpreting the contents of the address; do not assume that the
 193 addresses are all IPv4 addresses, or even all IPv4 or IPv6 addresses.
 194 IPv4 addresses have the value
 195 .BR AF_INET ,
 196 IPv6 addresses have the value
 197 .B AF_INET6
 198 (which older operating systems that don't support IPv6 might not
 199 define), and other addresses have other values.  Whether other addresses
 200 are returned, and what types they might have is platform-dependent.
 201 Namely, link-layer addresses, such as Ethernet MAC addresses, have the value
 202 .B AF_PACKET
 203 (on Linux) or
 204 .B AF_LINK
 205 (on AIX, FreeBSD, Haiku, illumos, macOS, NetBSD and OpenBSD) or are not
 206 returned at all (on GNU/Hurd and Solaris).
 207 .PP
 208 For IPv4 addresses, the
 209 .B "struct sockaddr"
 210 pointer can be interpreted as if it pointed to a
 211 .BR "struct sockaddr_in" ;
 212 for IPv6 addresses, it can be interpreted as if it pointed to a
 213 .BR "struct sockaddr_in6".
 214 For link-layer addresses, it can be interpreted as if it pointed to a
 215 .B "struct sockaddr_ll"
 216 (for
 217 .BR AF_PACKET ,
 218 see
 219 .BR packet (7))
 220 or a
 221 .B "struct sockaddr_dl"
 222 (for
 223 .BR AF_LINK ).
 224 .PP
 225 The list of devices must be freed with
 226 .BR pcap_freealldevs (),
 227 which frees the list pointed to by
 228 .IR alldevs .
 229 .SH RETURN VALUE
 230 .BR pcap_findalldevs ()
 231 returns
 232 .B 0
 233 on success and
 234 .B PCAP_ERROR
 235 on failure; as indicated, finding no
 236 devices is considered success, rather than failure, so
 237 .B 0
 238 will be
 239 returned in that case. If
 240 .B PCAP_ERROR
 241 is returned,
 242 .I errbuf
 243 is filled in with an appropriate error message,
 244 and the pointer pointed to by
 245 .I alldevsp
 246 is set to
 247 .BR NULL .
 248 .SH BACKWARD COMPATIBILITY
 249 .PP
 250 The
 251 .B PCAP_IF_UP
 252 and
 253 .B PCAP_IF_RUNNING
 254 constants became available in libpcap release 1.6.1.
 255 .PP
 256 The
 257 .BR PCAP_IF_WIRELESS ,
 258 .BR PCAP_IF_CONNECTION_STATUS ,
 259 .BR PCAP_IF_CONNECTION_STATUS_UNKNOWN ,
 260 .BR PCAP_IF_CONNECTION_STATUS_CONNECTED ,
 261 .BR PCAP_IF_CONNECTION_STATUS_DISCONNECTED ,
 262 and
 263 .B PCAP_IF_CONNECTION_STATUS_NOT_APPLICABLE
 264 constants became available in libpcap release 1.9.0.
 265 .SH SEE ALSO
 266 .BR pcap (3PCAP)