Deprecate this function, and indicate why it's not a good function.

diff --git a/pcap_lookupdev.3pcap b/pcap_lookupdev.3pcap
index aaa3a2013aa78f4d7eaef2edeabefeed09cd8f58..45c4ef8bfb70a98002a556052319cf4c03686aaf 100644 (file)
--- a/pcap_lookupdev.3pcap
+++ b/pcap_lookupdev.3pcap
@@ -32,10 +32,18 @@ char errbuf[PCAP_ERRBUF_SIZE];
 .ft
 .LP
 .ft B
-char *pcap_lookupdev(char *errbuf);
+[DEPRECATED] char *pcap_lookupdev(char *errbuf);
 .ft
 .fi
 .SH DESCRIPTION
+.B This interface is obsoleted by
+.BR pcap_findalldevs (3PCAP).
+To find a default device on which to capture, call
+.B pcap_findalldevs()
+and, if the list it returns is not empty, use the first device in the
+list.  (If the list is empty, there are no devices on which capture is
+possible.)
+.LP
 .B pcap_lookupdev()
 returns a pointer to a string giving the name of a network device
 suitable for use with
@@ -58,3 +66,15 @@ chars.
 .SH SEE ALSO
 pcap(3PCAP), pcap_create(3PCAP), pcap_activate(3PCAP),
 pcap_open_live(3PCAP), pcap_lookupnet(3PCAP)
+.SH BUGS
+The pointer returned by
+.B pcap_lookupdev()
+points to a static buffer; subsequent calls to
+.B pcap_lookupdev()
+in the same thread, or calls to
+.B pcap_lookupdev()
+in another thread, may overwrite that buffer.
+.LP
+In WinPcap, this function may return a UTF-16 string rather than an
+ASCII or UTF-8 string.
+