Add symbolic_constants_posix and its test

util/misc/symbolic_constants_common.h

+// Copyright 2014 The Crashpad Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef CRASHPAD_UTIL_MISC_SYMBOLIC_CONSTANTS_COMMON_H_
+#define CRASHPAD_UTIL_MISC_SYMBOLIC_CONSTANTS_COMMON_H_
+
+namespace crashpad {
+
+// Symbolic constant terminology:

[Robert Sesek, 2014/09/10 20:01:04]

Can this comment be added to Doxygen somehow?

+//
+// A “family” is a group of related symbolic constants. Typically, within a
+// single family, one function will be used to transform a numeric value to a
+// string equivalent, and another will perform the inverse operation. Families
+// include POSIX signals and Mach exception masks.
+//
+// A “full name” is the normal symbolic name used for a constant. For example,
+// in the family of POSIX signals, the strings "SIGHUP" and "SIGSEGV" are full
+// names.
+//
+// A “short name” is an abbreviated form of symbolic name used for a constant.
+// Short names vary between families, but are commonly constructed by removing a
+// common prefix from full names. For example, in the family of POSIX signals,
+// the prefix is SIG, and short names include "HUP" and "SEGV".
+//
+// A “numeric string” is a string that does not contain a full or short name,
+// but contains a numeric value that can be interpreted as a symbolic constant.
+// For example, in the family of POSIX signals, SIGKILL generally has value 9,
+// so the numeric string "9" would be interpreted equivalently to "SIGKILL".
+
+//! \brief Options for various `*ToString` functions in `symbolic_constants_*`
+//!     files.
+enum SymbolicConstantToStringOptionBits {
+  //! \brief Return the full name for a given constant.
+  //!
+  //! \attention API consumers should provide this value when desired, but
+  //!     should provide only one of kUseFullName and ::kUseShortName. Because
+  //!     kUseFullName is valueless, implementers should check for the absence
+  //!     of ::kUseShortName instead.
+  kUseFullName = 0 << 0,
+
+  //! \brief Return the short name for a given constant.
+  kUseShortName = 1 << 0,
+
+  //! \brief If no symbolic name is known for a given constant, return an empty
+  //!     string.
+  //!
+  //! \attention API consumers should provide this value when desired, but
+  //!     should provide only one of kUnknownIsEmpty and ::kUnknownIsNumeric.
+  //!     Because kUnknownIsEmpty is valueless, implementers should check for
+  //!     the absence of ::kUnknownIsNumeric instead.
+  kUnknownIsEmpty = 0 << 1,
+
+  //! \brief If no symbolic name is known for a given constant, return a numeric
+  //!     string.
+  //!
+  //! The numeric format used will vary by family, but will be appropriate to
+  //! the family. Families whose values are typically constructed as bitfields
+  //! will generally use a hexadecimal format, and other families will generally
+  //! use a signed or unsigned decimal format.
+  kUnknownIsNumeric = 1 << 1,
+
+  //! \brief Use `|` to combine values in a bitfield.
+  //!
+  //! For families whose values may be constructed as bitfields, allow
+  //! conversion to strings containing multiple individual components treated as
+  //! being combined by a bitwise “or” operation. An example family of constants
+  //! that behaves this way is the suite of Mach exception masks. For constants
+  //! that are not constructed as bitfields, or constants that are only
+  //! partially constructed as bitfields, this option has no effect.
+  kUseOr = 1 << 2,
+};
+
+//! \brief A bitfield containing values of #SymbolicConstantToStringOptionBits.
+typedef unsigned int SymbolicConstantToStringOptions;
+
+//! \brief Options for various `StringTo*` functions in `symbolic_constants_*`
+//!     files.
+//!
+//! Not every `StringTo*` function will implement each of these options. See
+//! function-specific documentation for details.
+enum StringToSymbolicConstantOptionBits {
+  //! \brief Allow conversion from a string containing a symbolic constant by
+  //!     its full name.
+  kAllowFullName = 1 << 0,
+
+  //! \brief Allow conversion from a string containing a symbolic constant by
+  //!     its short name.
+  kAllowShortName = 1 << 1,
+
+  //! \brief Allow conversion from a numeric string.
+  kAllowNumber = 1 << 2,
+
+  //! \brief Allow `|` to combine values in a bitfield.
+  //!
+  //! For families whose values may be constructed as bitfields, allow
+  //! conversion of strings containing multiple individual components treated as
+  //! being combined by a bitwise “or” operation. An example family of constants
+  //! that behaves this way is the suite of Mach exception masks. For constants
+  //! that are not constructed as bitfields, or constants that are only
+  //! partially constructed as bitfields, this option has no effect.
+  kAllowOr = 1 << 3,
+};
+
+//! \brief A bitfield containing values of #StringToSymbolicConstantOptionBits.
+typedef unsigned int StringToSymbolicConstantOptions;
+
+}  // namespace crashpad
+
+#endif  // CRASHPAD_UTIL_MISC_SYMBOLIC_CONSTANTS_COMMON_H_