Add some "what if it's an earlier release" information.

Expand the BACKWARD COMPATIBILITY section to either say "sorry, you
can't get that with earlier releases of libpcap" or "if you need this,
here's what you'd have to do".

13 files changed, 114 insertions, 26 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index d99fdb70..ea17ad49 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1808,10 +1808,12 @@ set_source_files_properties(${CMAKE_CURRENT_BINARY_DIR}/grammar.c PROPERTIES
 
 #
 # Assume, by default, no support for shared libraries and V7/BSD
-# convention for man pages (file formats in section 5, miscellaneous
-# info in section 7, administrative commands and daemons in section 8).
+# convention for man pages (devices in section 4, file formats in
+# section 5, miscellaneous info in section 7, administrative commands
+# and daemons in section 8).  Individual cases can override this.
 # Individual cases can override this.
 #
+set(MAN_DEVICES 4)
 set(MAN_FILE_FORMATS 5)
 set(MAN_MISC_INFO 7)
 set(MAN_ADMIN_COMMANDS 8)
@@ -1869,6 +1871,7 @@ elseif(CMAKE_SYSTEM_NAME STREQUAL "OSF1")
     #
     set(MAN_FILE_FORMATS 4)
     set(MAN_MISC_INFO 5)
+    set(MAN_DEVICES 7)
 elseif(CMAKE_SYSTEM_NAME STREQUAL "SunOS" AND CMAKE_SYSTEM_VERSION MATCHES "5[.][0-9.]*")
     #
     # SunOS 5.x.
@@ -1892,6 +1895,7 @@ elseif(CMAKE_SYSTEM_NAME STREQUAL "SunOS" AND CMAKE_SYSTEM_VERSION MATCHES "5[.]
         set(MAN_ADMIN_COMMANDS 1m)
         set(MAN_FILE_FORMATS 4)
         set(MAN_MISC_INFO 5)
+        set(MAN_DEVICES 7D)
     endif()
 endif()
 
@@ -2079,6 +2083,7 @@ set(MAN3PCAP_EXPAND
     pcap_list_tstamp_types.3pcap.in
     pcap_open_dead.3pcap.in
     pcap_open_offline.3pcap.in
+    pcap_set_immediate_mode.3pcap.in
     pcap_set_tstamp_precision.3pcap.in
     pcap_set_tstamp_type.3pcap.in
 )
@@ -2114,7 +2119,6 @@ set(MAN3PCAP_NOEXPAND
     pcap_open_live.3pcap
     pcap_set_buffer_size.3pcap
     pcap_set_datalink.3pcap
-    pcap_set_immediate_mode.3pcap
     pcap_set_promisc.3pcap
     pcap_set_protocol_linux.3pcap
     pcap_set_rfmon.3pcap
diff --git a/Makefile.in b/Makefile.in
index dff75ec1..5bf21886 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -168,6 +168,7 @@ MAN3PCAP_EXPAND = \
 	pcap_list_tstamp_types.3pcap.in \
 	pcap_open_dead.3pcap.in \
 	pcap_open_offline.3pcap.in \
+	pcap_set_immediate_mode.3pcap.in \
 	pcap_set_tstamp_precision.3pcap.in \
 	pcap_set_tstamp_type.3pcap.in
 
@@ -203,7 +204,6 @@ MAN3PCAP_NOEXPAND = \
 	pcap_open_live.3pcap \
 	pcap_set_buffer_size.3pcap \
 	pcap_set_datalink.3pcap \
-	pcap_set_immediate_mode.3pcap \
 	pcap_set_promisc.3pcap \
 	pcap_set_protocol_linux.3pcap \
 	pcap_set_rfmon.3pcap \
diff --git a/configure b/configure
index 578d26dc..49eccf4c 100755
--- a/configure
+++ b/configure
@@ -645,6 +645,7 @@ PTHREAD_LIBS
 MAN_ADMIN_COMMANDS
 MAN_MISC_INFO
 MAN_FILE_FORMATS
+MAN_DEVICES
 DYEXT
 SSRC
 ADDLARCHIVEOBJS
@@ -7945,11 +7946,12 @@ fi
 # Do various checks for various OSes and versions of those OSes.
 #
 # Assume, by default, no support for shared libraries and V7/BSD
-# convention for man pages (file formats in section 5, miscellaneous
-# info in section 7, administrative commands and daemons in section 8).
-# Individual cases can override this.
+# convention for man pages (devices in section 4, file formats in
+# section 5, miscellaneous info in section 7, administrative commands
+# and daemons in section 8).  Individual cases can override this.
 #
 DYEXT="none"
+MAN_DEVICES=4
 MAN_FILE_FORMATS=5
 MAN_MISC_INFO=7
 MAN_ADMIN_COMMANDS=8
@@ -8178,6 +8180,7 @@ osf*)
 	#
 	MAN_FILE_FORMATS=4
 	MAN_MISC_INFO=5
+	MAN_DEVICES=7
 	;;
 
 sinix*)
@@ -8243,6 +8246,7 @@ $as_echo "#define HAVE_SOLARIS 1" >>confdefs.h
 		MAN_ADMIN_COMMANDS=1m
 		MAN_FILE_FORMATS=4
 		MAN_MISC_INFO=5
+		MAN_DEVICES=7D
 	esac
 	;;
 esac
@@ -9973,6 +9977,7 @@ fi
 
 
 
+
 # Check whether --enable-usb was given.
 if test "${enable_usb+set}" = set; then :
   enableval=$enable_usb;
@@ -10711,7 +10716,7 @@ ac_config_headers="$ac_config_headers config.h"
 
 ac_config_commands="$ac_config_commands default-1"
 
-ac_config_files="$ac_config_files Makefile pcap-filter.manmisc pcap-linktype.manmisc pcap-tstamp.manmisc pcap-savefile.manfile pcap.3pcap pcap_compile.3pcap pcap_datalink.3pcap pcap_dump_open.3pcap pcap_get_tstamp_precision.3pcap pcap_list_datalinks.3pcap pcap_list_tstamp_types.3pcap pcap_open_dead.3pcap pcap_open_offline.3pcap pcap_set_tstamp_precision.3pcap pcap_set_tstamp_type.3pcap rpcapd/Makefile rpcapd/rpcapd.manadmin testprogs/Makefile"
+ac_config_files="$ac_config_files Makefile pcap-filter.manmisc pcap-linktype.manmisc pcap-tstamp.manmisc pcap-savefile.manfile pcap.3pcap pcap_compile.3pcap pcap_datalink.3pcap pcap_dump_open.3pcap pcap_get_tstamp_precision.3pcap pcap_list_datalinks.3pcap pcap_list_tstamp_types.3pcap pcap_open_dead.3pcap pcap_open_offline.3pcap pcap_set_immediate_mode.3pcap pcap_set_tstamp_precision.3pcap pcap_set_tstamp_type.3pcap rpcapd/Makefile rpcapd/rpcapd.manadmin testprogs/Makefile"
 
 cat >confcache <<\_ACEOF
 # This file is a shell script that caches the results of configure
@@ -11428,6 +11433,7 @@ do
     "pcap_list_tstamp_types.3pcap") CONFIG_FILES="$CONFIG_FILES pcap_list_tstamp_types.3pcap" ;;
     "pcap_open_dead.3pcap") CONFIG_FILES="$CONFIG_FILES pcap_open_dead.3pcap" ;;
     "pcap_open_offline.3pcap") CONFIG_FILES="$CONFIG_FILES pcap_open_offline.3pcap" ;;
+    "pcap_set_immediate_mode.3pcap") CONFIG_FILES="$CONFIG_FILES pcap_set_immediate_mode.3pcap" ;;
     "pcap_set_tstamp_precision.3pcap") CONFIG_FILES="$CONFIG_FILES pcap_set_tstamp_precision.3pcap" ;;
     "pcap_set_tstamp_type.3pcap") CONFIG_FILES="$CONFIG_FILES pcap_set_tstamp_type.3pcap" ;;
     "rpcapd/Makefile") CONFIG_FILES="$CONFIG_FILES rpcapd/Makefile" ;;
diff --git a/configure.ac b/configure.ac
index cbd2d2e2..8e376da5 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1522,11 +1522,12 @@ fi
 # Do various checks for various OSes and versions of those OSes.
 #
 # Assume, by default, no support for shared libraries and V7/BSD
-# convention for man pages (file formats in section 5, miscellaneous
-# info in section 7, administrative commands and daemons in section 8).
-# Individual cases can override this.
+# convention for man pages (devices in section 4, file formats in
+# section 5, miscellaneous info in section 7, administrative commands
+# and daemons in section 8).  Individual cases can override this.
 #
 DYEXT="none"
+MAN_DEVICES=4
 MAN_FILE_FORMATS=5
 MAN_MISC_INFO=7
 MAN_ADMIN_COMMANDS=8
@@ -1751,6 +1752,7 @@ osf*)
 	#
 	MAN_FILE_FORMATS=4
 	MAN_MISC_INFO=5
+	MAN_DEVICES=7
 	;;
 
 sinix*)
@@ -1794,6 +1796,7 @@ solaris*)
 		MAN_ADMIN_COMMANDS=1m
 		MAN_FILE_FORMATS=4
 		MAN_MISC_INFO=5
+		MAN_DEVICES=7D
 	esac
 	;;
 esac
@@ -1862,6 +1865,7 @@ AC_SUBST(ADDLOBJS)
 AC_SUBST(ADDLARCHIVEOBJS)
 AC_SUBST(SSRC)
 AC_SUBST(DYEXT)
+AC_SUBST(MAN_DEVICES)
 AC_SUBST(MAN_FILE_FORMATS)
 AC_SUBST(MAN_MISC_INFO)
 AC_SUBST(MAN_ADMIN_COMMANDS)
@@ -2257,7 +2261,7 @@ AC_OUTPUT(Makefile pcap-filter.manmisc pcap-linktype.manmisc
 	pcap_compile.3pcap pcap_datalink.3pcap pcap_dump_open.3pcap
 	pcap_get_tstamp_precision.3pcap pcap_list_datalinks.3pcap
 	pcap_list_tstamp_types.3pcap pcap_open_dead.3pcap
-	pcap_open_offline.3pcap pcap_set_tstamp_precision.3pcap
-	pcap_set_tstamp_type.3pcap rpcapd/Makefile rpcapd/rpcapd.manadmin
-	testprogs/Makefile)
+	pcap_open_offline.3pcap pcap_set_immediate_mode.3pcap
+	pcap_set_tstamp_precision.3pcap pcap_set_tstamp_type.3pcap
+	rpcapd/Makefile rpcapd/rpcapd.manadmin testprogs/Makefile)
 exit 0
diff --git a/pcap_dump_open.3pcap.in b/pcap_dump_open.3pcap.in
index 4a8a8624..b86696f0 100644
--- a/pcap_dump_open.3pcap.in
+++ b/pcap_dump_open.3pcap.in
@@ -95,7 +95,9 @@ can be used to get the error text.
 .PP
 The
 .B pcap_dump_open_append()
-function became available in libpcap release 1.7.2.
+function became available in libpcap release 1.7.2.  In previous
+releases, there is no support for appending packets to an existing
+savefile.
 .SH SEE ALSO
 pcap(3PCAP),
 \%pcap-savefile(@MAN_FILE_FORMATS@)
diff --git a/pcap_findalldevs.3pcap b/pcap_findalldevs.3pcap
index 47822eff..712e255a 100644
--- a/pcap_findalldevs.3pcap
+++ b/pcap_findalldevs.3pcap
@@ -218,6 +218,14 @@ The
 .B PCAP_IF_UP
 and
 .B PCAP_IF_RUNNING
-constants became available in libpcap release 1.6.1.
+constants became available in libpcap release 1.6.1.  The
+.BR PCAP_IF_WIRELESS ,
+.BR PCAP_IF_CONNECTION_STATUS ,
+.BR PCAP_IF_CONNECTION_STATUS_UNKNOWN ,
+.BR PCAP_IF_CONNECTION_STATUS_CONNECTED ,
+.BR PCAP_IF_CONNECTION_STATUS_DISCONNECTED ,
+and
+.B PCAP_IF_CONNECTION_STATUS_NOT_APPLICABLE
+constants became available in libpcap release 1.9.0.
 .SH SEE ALSO
 pcap(3PCAP)
diff --git a/pcap_get_required_select_timeout.3pcap b/pcap_get_required_select_timeout.3pcap
index e4e424c8..e58cb4e7 100644
--- a/pcap_get_required_select_timeout.3pcap
+++ b/pcap_get_required_select_timeout.3pcap
@@ -83,6 +83,16 @@ is returned if the timeout is required; otherwise
 .B NULL
 is returned.
 .SH BACKWARD COMPATIBILITY
-This function became available in libpcap release 1.9.0.
+This function became available in libpcap release 1.9.0.  In previous
+releases,
+.BR select() ,
+.BR poll() ,
+.BR epoll_wait() ,
+and
+.B kevent()
+cannot be used on any capture source for which
+.B pcap_get_selectable_fd
+returns \-1.
 .SH SEE ALSO
-pcap(3PCAP), kqueue(2)
+pcap(3PCAP), pcap_get_selectable_fd(3PCAP), select(2), poll(2),
+epoll_wait(2), kqueue(2)
diff --git a/pcap_get_tstamp_precision.3pcap.in b/pcap_get_tstamp_precision.3pcap.in
index f0b1a7e6..2e72e0ba 100644
--- a/pcap_get_tstamp_precision.3pcap.in
+++ b/pcap_get_tstamp_precision.3pcap.in
@@ -47,7 +47,9 @@ which indicates
 that pcap captures contains time stamps in microseconds or nanoseconds
 respectively.
 .SH BACKWARD COMPATIBILITY
-This function became available in libpcap release 1.5.1.
+This function became available in libpcap release 1.5.1.  In previous
+releases, time stamps from a capture device or savefile are always given
+in seconds and microseconds.
 .SH SEE ALSO
 pcap(3PCAP),
 pcap_set_tstamp_precision(3PCAP),
diff --git a/pcap_list_tstamp_types.3pcap.in b/pcap_list_tstamp_types.3pcap.in
index 39ebabd6..4deff794 100644
--- a/pcap_list_tstamp_types.3pcap.in
+++ b/pcap_list_tstamp_types.3pcap.in
@@ -67,7 +67,9 @@ may be called with
 as an argument to fetch or display the error text.
 .SH BACKWARD COMPATIBILITY
 .PP
-These functions became available in libpcap release 1.2.1.
+These functions became available in libpcap release 1.2.1.  In previous
+releases, the time stamp type cannot be set; only the default time stamp
+type offered by a capture source is available.
 .SH SEE ALSO
 pcap(3PCAP), pcap_tstamp_type_val_to_name(3PCAP),
 pcap-tstamp(@MAN_MISC_INFO@)
diff --git a/pcap_open_offline.3pcap.in b/pcap_open_offline.3pcap.in
index 97e9066f..6ad4ddbb 100644
--- a/pcap_open_offline.3pcap.in
+++ b/pcap_open_offline.3pcap.in
@@ -109,6 +109,7 @@ chars.
 .B pcap_open_offline_with_tstamp_precision
 and
 .B pcap_fopen_offline_with_tstamp_precision
-became available in libpcap release 1.5.1.
+became available in libpcap release 1.5.1.  In previous releases, time
+stamps from a savefile are always given in seconds and microseconds.
 .SH SEE ALSO
 pcap(3PCAP), pcap-savefile(@MAN_FILE_FORMATS@)
diff --git a/pcap_set_immediate_mode.3pcap b/pcap_set_immediate_mode.3pcap.in
index d9b4afea..2fe45c54 100644
--- a/pcap_set_immediate_mode.3pcap
+++ b/pcap_set_immediate_mode.3pcap.in
@@ -46,6 +46,50 @@ returns 0 on success or
 if called on a capture handle that has been activated.
 .SH BACKWARD COMPATIBILITY
 .PP
-This function became available in libpcap release 1.5.0.
+This function became available in libpcap release 1.5.0.  In previous
+releases, if immediate delivery of packets is required:
+.IP
+on FreeBSD, NetBSD, OpenBSD, DragonFly BSD, macOS, and Solaris 11,
+immediate mode must be turned on with a
+.B BIOCIMMEDIATE
+.BR ioctl (2),
+as documented in
+.BR bpf(@MAN_DEVICES@) ,
+on the descriptor returned by
+.B pcap_fileno(3PCAP),
+after
+.BR pcap_activate(3PCAP)
+is called;
+.IP
+on Solaris 10 and earlier versions of Solaris, immediate mode must be
+turned on by using a read timeout of 0 when opening the device (this
+will not provide immediate delivery of packets on other platforms, so
+don't assume it's sufficient);
+.IP
+on Digital UNIX/Tru64 UNIX, immediate mode must be turned on by doing a
+.B BIOCMBIC
+.BR ioctl ,
+as documented in
+.BR packetfilter(7) ,
+to clear the
+.B ENBATCH
+flag on the descriptor returned by
+.B pcap_fileno(3PCAP),
+after
+.BR pcap_activate(3PCAP)
+is called;
+.IP
+on Windows, immediate mode must be turned on by calling
+.B pcap_setmintocopy()
+with a size of 0.
+.PP
+On Linux, with previous releases of libpcap, capture devices are always
+in immediate mode; however, in 1.5.0 and later, they are, by default,
+.B not
+in immediate mode, so if
+.B pcap_set_immediate_mode()
+is available, it should be used.
+.PP
+On other platforms, capture devices are always in immediate mode.
 .SH SEE ALSO
 pcap(3PCAP), pcap_create(3PCAP), pcap_activate(3PCAP)
diff --git a/pcap_set_tstamp_precision.3pcap.in b/pcap_set_tstamp_precision.3pcap.in
index 008350ed..dc2b4b3d 100644
--- a/pcap_set_tstamp_precision.3pcap.in
+++ b/pcap_set_tstamp_precision.3pcap.in
@@ -50,13 +50,16 @@ to request desired precision. By default, time stamps are in microseconds.
 .SH RETURN VALUE
 .B pcap_set_tstamp_precision()
 returns 0 on success if the specified time stamp precision is expected to be
-supported by the operating system,
+supported by the capture device,
 .B PCAP_ERROR_TSTAMP_PRECISION_NOTSUP
-if operating system does not support requested time stamp precision,
+if the capture device does not support the requested time stamp
+precision,
 .B PCAP_ERROR_ACTIVATED
 if called on a capture handle that has been activated.
 .SH BACKWARD COMPATIBILITY
-This function became available in libpcap release 1.5.1.
+This function became available in libpcap release 1.5.1.  In previous
+releases, time stamps from a capture device or savefile are always given
+in seconds and microseconds.
 .SH SEE ALSO
 pcap(3PCAP),
 pcap_get_tstamp_precision(3PCAP),
diff --git a/pcap_set_tstamp_type.3pcap.in b/pcap_set_tstamp_type.3pcap.in
index 1b0740ce..1834d072 100644
--- a/pcap_set_tstamp_type.3pcap.in
+++ b/pcap_set_tstamp_type.3pcap.in
@@ -60,7 +60,9 @@ if called on a capture handle that has been activated, and
 if the capture device doesn't support setting the time stamp type.
 .SH BACKWARD COMPATIBILITY
 .PP
-This function became available in libpcap release 1.2.1.
+This function became available in libpcap release 1.2.1.  In previous
+releases, the time stamp type cannot be set; only the default time stamp
+type offered by a capture source is available.
 .SH SEE ALSO
 pcap(3PCAP),
 pcap_tstamp_type_name_to_val(3PCAP)