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