Merge pull request #742 in SNORT/snort3 from macros_doc to master

Squashed commit of the following:

commit 8d2d0b87dd0dfe416fa7991f6c7c8b3e1501d8af
Author: Michael Altizer <mialtize@cisco.com>
Date:   Thu Dec 8 13:15:13 2016 -0500

    utils: License and document CPP padding guard macros.

diff --git a/doc/style.txt b/doc/style.txt
index ccc2b226f85187586eacd4a0c6fdfa925a1d4980..b5542a777698a7af51cfba13da491e11459f1cc5 100644 (file)
--- a/doc/style.txt
+++ b/doc/style.txt
@@ -304,6 +304,12 @@ yet firm so feedback is welcome to get something we can live with.
     -Wno-deprecated-declarations
     -fsanitize=address -fno-omit-frame-pointer
 
+* Two macros (PADDING_GUARD_START and PADDING_GUARD_END) are provided by
+  utils/cpp_macros.h.  These should be used to surround any structure used as
+  a hash key with a raw comparator or that would otherwise suffer from
+  unintentional padding.  A compiler warning will be generated if any structure
+  definition is automatically padded between the macro invocations.
+
 * Then Fix All Warnings and Aborts.  None Allowed.
 
 === Uncrustify

diff --git a/src/utils/cpp_macros.h b/src/utils/cpp_macros.h
index 3b01ef085a16a05536a106129d97bae7a12ae298..739fbcbcd960bd9f37fc21a6b4c6b95899073ac5 100644 (file)
--- a/src/utils/cpp_macros.h
+++ b/src/utils/cpp_macros.h
@@ -1,8 +1,31 @@
+//--------------------------------------------------------------------------
+// Copyright (C) 2016-2016 Cisco and/or its affiliates. All rights reserved.
+//
+// This program is free software; you can redistribute it and/or modify it
+// under the terms of the GNU General Public License Version 2 as published
+// by the Free Software Foundation.  You may not use, modify or distribute
+// this program under any other version of the GNU General Public License.
+//
+// This program is distributed in the hope that it will be useful, but
+// WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along
+// with this program; if not, write to the Free Software Foundation, Inc.,
+// 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+//--------------------------------------------------------------------------
+// cpp_macros.h author Michael Altizer <mialtize@cisco.com>
+
 #ifndef CPP_MACROS_H
 #define CPP_MACROS_H
 
+// Miscellaneous C preprocessor macros
+
 #define STRINGIFY(x) #x
 
+// Pair of macros to temporarily enable and then disable warnings for structures
+// being automatically padded.  Currently implemented for Clang and GCC >= 5.0.
 #if defined(__clang__) && !defined(__ICC)
 #  define PADDING_GUARD_BEGIN \
     _Pragma(STRINGIFY( clang diagnostic push )) \