contrib/libpcap/pcap_findalldevs.3pcap

   1 .\" @(#) $Header: /tcpdump/master/libpcap/pcap_findalldevs.3pcap,v 1.1.2.3 2008-04-06 03:21:55 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 "5 April 2008"
  23 .SH NAME
  24 pcap_findalldevs \- get a list of capture devices
  25 .SH SYNOPSIS
  26 .nf
  27 .ft B
  28 #include <pcap/pcap.h>
  29 .ft
  30 .LP
  31 .nf
  32 .ft B
  33 char errbuf[PCAP_ERRBUF_SIZE];
  34 .ft
  35 .LP
  36 .ft B
  37 int pcap_findalldevs(pcap_if_t **alldevsp, char *errbuf);
  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 might 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 set to point to the first element of the list; each element of the
  56 list is of type
  57 .BR pcap_if_t ,
  58 and has the following members:
  59 .RS
  60 .TP
  61 .B next
  62 if not
  63 .BR NULL ,
  64 a pointer to the next element in the list;
  65 .B NULL
  66 for the last element of the list
  67 .TP
  68 .B name
  69 a pointer to a string giving a name for the device to pass to
  70 .B pcap_open_live()
  71 .TP
  72 .B description
  73 if not
  74 .BR NULL ,
  75 a pointer to a string giving a human-readable description of the device
  76 .TP
  77 .B addresses
  78 a pointer to the first element of a list of addresses for the interface
  79 .TP
  80 .B flags
  81 interface flags:
  82 .RS
  83 .TP
  84 .B PCAP_IF_LOOPBACK
  85 set if the interface is a loopback interface
  86 .RE
  87 .RE
  88 .PP
  89 Each element of the list of addresses is of type
  90 .BR pcap_addr_t ,
  91 and has the following members:
  92 .RS
  93 .TP
  94 .B next
  95 if not
  96 .BR NULL ,
  97 a pointer to the next element in the list;
  98 .B NULL
  99 for the last element of the list
 100 .TP
 101 .B addr
 102 a pointer to a
 103 .B "struct sockaddr"
 104 containing an address
 105 .TP
 106 .B netmask
 107 if not
 108 .BR NULL ,
 109 a pointer to a
 110 .B "struct sockaddr"
 111 that contains the netmask corresponding to the address pointed to by
 112 .B addr
 113 .TP
 114 .B broadaddr
 115 if not
 116 .BR NULL ,
 117 a pointer to a
 118 .B "struct sockaddr"
 119 that contains the broadcast address corresponding to the address pointed
 120 to by
 121 .BR addr ;
 122 may be null if the interface doesn't support broadcasts
 123 .TP
 124 .B dstaddr
 125 if not
 126 .BR NULL ,
 127 a pointer to a
 128 .B "struct sockaddr"
 129 that contains the destination address corresponding to the address pointed
 130 to by
 131 .BR addr ;
 132 may be null if the interface isn't a point-to-point interface
 133 .RE
 134 .PP
 135 Note that not all the addresses in the list of addresses are
 136 necessarily IPv4 or IPv6 addresses - you must check the
 137 .B sa_family
 138 member of the
 139 .B "struct sockaddr"
 140 before interpreting the contents of the address.
 141 .PP
 142 The list of devices must be freed with
 143 .BR pcap_freealldevs() .
 144 .SH RETURN VALUE
 145 .B pcap_findalldevs()
 146 returns 0 on success and \-1 on failure.
 147 If \-1 is returned,
 148 .I errbuf
 149 is filled in with an appropriate error message.
 150 .I errbuf
 151 is assumed to be able to hold at least
 152 .B PCAP_ERRBUF_SIZE
 153 chars.
 154 .SH SEE ALSO
 155 pcap(3PCAP), pcap_create(3PCAP), pcap_activate(3PCAP),
 156 pcap_open_live(3PCAP), pcap_freealldevs(3PCAP)