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 "7 April 2014"
  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 .B pcap_findalldevs()
  42 constructs a list of network devices that can be opened with
  43 .B pcap_create()
  44 and
  45 .B pcap_activate()
  46 or with
  47 .BR pcap_open_live() .
  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 .B 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 .B 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 .RE
 102 .RE
 103 .PP
 104 Each element of the list of addresses is of type
 105 .BR pcap_addr_t ,
 106 and has the following members:
 107 .RS
 108 .TP
 109 .B next
 110 if not
 111 .BR NULL ,
 112 a pointer to the next element in the list;
 113 .B NULL
 114 for the last element of the list
 115 .TP
 116 .B addr
 117 a pointer to a
 118 .B "struct sockaddr"
 119 containing an address
 120 .TP
 121 .B netmask
 122 if not
 123 .BR NULL ,
 124 a pointer to a
 125 .B "struct sockaddr"
 126 that contains the netmask corresponding to the address pointed to by
 127 .B addr
 128 .TP
 129 .B broadaddr
 130 if not
 131 .BR NULL ,
 132 a pointer to a
 133 .B "struct sockaddr"
 134 that contains the broadcast address corresponding to the address pointed
 135 to by
 136 .BR addr ;
 137 may be null if the device doesn't support broadcasts
 138 .TP
 139 .B dstaddr
 140 if not
 141 .BR NULL ,
 142 a pointer to a
 143 .B "struct sockaddr"
 144 that contains the destination address corresponding to the address pointed
 145 to by
 146 .BR addr ;
 147 may be null if the device isn't a point-to-point interface
 148 .RE
 149 .PP
 150 Note that the addresses in the list of addresses might be IPv4
 151 addresses, IPv6 addresses, or some other type of addresses, so you must
 152 check the
 153 .B sa_family
 154 member of the
 155 .B "struct sockaddr"
 156 before interpreting the contents of the address; do not assume that the
 157 addresses are all IPv4 addresses, or even all IPv4 or IPv6 addresses.
 158 IPv4 addresses have the value
 159 .BR AF_INET ,
 160 IPv6 addresses have the value
 161 .B AF_INET6
 162 (which older operating systems that don't support IPv6 might not
 163 define), and other addresses have other values.  Whether other addresses
 164 are returned, and what types they might have is platform-dependent.
 165 For IPv4 addresses, the
 166 .B "struct sockaddr"
 167 pointer can be interpreted as if it pointed to a
 168 .BR "struct sockaddr_in" ;
 169 for IPv6 addresses, it can be interpreted as if it pointed to a
 170 .BR "struct sockaddr_in6".
 171 .PP
 172 The list of devices must be freed with
 173 .BR pcap_freealldevs() ,
 174 which frees the list pointed to by
 175 .IR alldevs .
 176 .SH RETURN VALUE
 177 .B pcap_findalldevs()
 178 returns 0 on success and \-1 on failure; as indicated, finding no
 179 devices is considered success, rather than failure, so 0 will be
 180 returned in that case.
 181 If \-1 is returned,
 182 .I errbuf
 183 is filled in with an appropriate error message.
 184 .I errbuf
 185 is assumed to be able to hold at least
 186 .B PCAP_ERRBUF_SIZE
 187 chars.
 188 .SH SEE ALSO
 189 pcap(3PCAP), pcap_create(3PCAP), pcap_activate(3PCAP),
 190 pcap_open_live(3PCAP)