From 409f2293a38c2b9adb2d6097748c95efcdafad2f Mon Sep 17 00:00:00 2001 From: Guy Harris Date: Wed, 22 Aug 2018 17:20:53 -0700 Subject: [PATCH] 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". --- CMakeLists.txt | 10 ++-- Makefile.in | 2 +- configure | 14 ++++-- configure.ac | 16 ++++--- pcap_dump_open.3pcap.in | 4 +- pcap_findalldevs.3pcap | 10 +++- pcap_get_required_select_timeout.3pcap | 14 +++++- pcap_get_tstamp_precision.3pcap.in | 4 +- pcap_list_tstamp_types.3pcap.in | 4 +- pcap_open_offline.3pcap.in | 3 +- ....3pcap => pcap_set_immediate_mode.3pcap.in | 46 ++++++++++++++++++- pcap_set_tstamp_precision.3pcap.in | 9 ++-- pcap_set_tstamp_type.3pcap.in | 4 +- 13 files changed, 114 insertions(+), 26 deletions(-) rename pcap_set_immediate_mode.3pcap => pcap_set_immediate_mode.3pcap.in (60%) diff --git a/CMakeLists.txt b/CMakeLists.txt index d99fdb7022..ea17ad4954 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 dff75ec121..5bf218868c 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 578d26dc82..49eccf4ca4 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 @@ -9971,6 +9975,7 @@ fi + # Check whether --enable-usb was given. @@ -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 cbd2d2e2ec..8e376da56d 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 4a8a8624be..b86696f088 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 47822efffe..712e255a0f 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 e4e424c885..e58cb4e78d 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 f0b1a7e6e4..2e72e0bac1 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 39ebabd67c..4deff7948a 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 97e9066fef..6ad4ddbbb8 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 similarity index 60% rename from pcap_set_immediate_mode.3pcap rename to pcap_set_immediate_mode.3pcap.in index d9b4afea2f..2fe45c5439 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 008350edb7..dc2b4b3d2a 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 1b0740ce87..1834d07214 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)