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

   1 .\" @(#) $Header: /tcpdump/master/libpcap/pcap_findalldevs.3pcap,v 1.3 2008-04-06 02:53:22 guy Exp $
   2 .\"
   3 .\" Copyright (c) 1994, 1996, 1997
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that: (1) source code distributions
   8 .\" retain the above copyright notice and this paragraph in its entirety, (2)
   9 .\" distributions including binary code include the above copyright notice and
  10 .\" this paragraph in its entirety in the documentation or other materials
  11 .\" provided with the distribution, and (3) all advertising materials mentioning
  12 .\" features or use of this software display the following acknowledgement:
  13 .\" ``This product includes software developed by the University of California,
  14 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
  15 .\" the University nor the names of its contributors may be used to endorse
  16 .\" or promote products derived from this software without specific prior
  17 .\" written permission.
  18 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  19 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  20 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  21 .\"
  22 .TH PCAP_FINDALLDEVS 3PCAP "22 August 2010"
  23 .SH NAME
  24 pcap_findalldevs, pcap_freealldevs \- get a list of capture devices, and
  25 free that list
  26 .SH SYNOPSIS
  27 .nf
  28 .ft B
  29 #include <pcap/pcap.h>
  30 .ft
  31 .LP
  32 .nf
  33 .ft B
  34 char errbuf[PCAP_ERRBUF_SIZE];
  35 .ft
  36 .LP
  37 .ft B
  38 int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf);
  39 void pcap_freealldevs(pcap_if_t *alldevs);
  40 .ft
  41 .fi
  42 .SH DESCRIPTION
  43 .B pcap_findalldevs()
  44 constructs a list of network devices that can be opened with
  45 .B pcap_create()
  46 and
  47 .B pcap_activate()
  48 or with
  49 .BR pcap_open_live() .
  50 (Note that there may be network devices that cannot be opened by the
  51 process calling
  52 .BR pcap_findalldevs() ,
  53 because, for example, that process might not have sufficient privileges
  54 to open them for capturing; if so, those devices will not appear on the
  55 list.)
  56 .I alldevsp
  57 is set to point to the first element of the list; each element of the
  58 list is of type
  59 .BR pcap_if_t ,
  60 and has the following members:
  61 .RS
  62 .TP
  63 .B next
  64 if not
  65 .BR NULL ,
  66 a pointer to the next element in the list;
  67 .B NULL
  68 for the last element of the list
  69 .TP
  70 .B name
  71 a pointer to a string giving a name for the device to pass to
  72 .B pcap_open_live()
  73 .TP
  74 .B description
  75 if not
  76 .BR NULL ,
  77 a pointer to a string giving a human-readable description of the device
  78 .TP
  79 .B addresses
  80 a pointer to the first element of a list of addresses for the interface
  81 .TP
  82 .B flags
  83 interface flags:
  84 .RS
  85 .TP
  86 .B PCAP_IF_LOOPBACK
  87 set if the interface is a loopback interface
  88 .RE
  89 .RE
  90 .PP
  91 Each element of the list of addresses is of type
  92 .BR pcap_addr_t ,
  93 and has the following members:
  94 .RS
  95 .TP
  96 .B next
  97 if not
  98 .BR NULL ,
  99 a pointer to the next element in the list;
 100 .B NULL
 101 for the last element of the list
 102 .TP
 103 .B addr
 104 a pointer to a
 105 .B "struct sockaddr"
 106 containing an address
 107 .TP
 108 .B netmask
 109 if not
 110 .BR NULL ,
 111 a pointer to a
 112 .B "struct sockaddr"
 113 that contains the netmask corresponding to the address pointed to by
 114 .B addr
 115 .TP
 116 .B broadaddr
 117 if not
 118 .BR NULL ,
 119 a pointer to a
 120 .B "struct sockaddr"
 121 that contains the broadcast address corresponding to the address pointed
 122 to by
 123 .BR addr ;
 124 may be null if the interface doesn't support broadcasts
 125 .TP
 126 .B dstaddr
 127 if not
 128 .BR NULL ,
 129 a pointer to a
 130 .B "struct sockaddr"
 131 that contains the destination address corresponding to the address pointed
 132 to by
 133 .BR addr ;
 134 may be null if the interface isn't a point-to-point interface
 135 .RE
 136 .PP
 137 Note that not all the addresses in the list of addresses are
 138 necessarily IPv4 or IPv6 addresses - you must check the
 139 .B sa_family
 140 member of the
 141 .B "struct sockaddr"
 142 before interpreting the contents of the address.
 143 .PP
 144 The list of devices must be freed with
 145 .BR pcap_freealldevs() ,
 146 whch frees the list pointed to by
 147 .IR alldevs .
 148 .SH RETURN VALUE
 149 .B pcap_findalldevs()
 150 returns 0 on success and \-1 on failure.
 151 If \-1 is returned,
 152 .I errbuf
 153 is filled in with an appropriate error message.
 154 .I errbuf
 155 is assumed to be able to hold at least
 156 .B PCAP_ERRBUF_SIZE
 157 chars.
 158 .SH SEE ALSO
 159 pcap(3PCAP), pcap_create(3PCAP), pcap_activate(3PCAP),
 160 pcap_open_live(3PCAP)