Refactor StrError_R() and fix doxygen references.

- In StrError_R(): Assume the happy path where the buffer
  is sufficient to hold the error message, first, instead
  of preemptively filling the buffer with the fallback
  numerical code. We rely on the fallback behaviour only
  when the buffer has been deemed to be too small.

- In StrError_R(): Properly handle negative return values
  from snprintf(), instead of casting it away without
  considering the possibility of the value being
  negative.

- Doxygen: generation of documentation produced warnings
  due to linking against strerror_r(), a symbol that
  wasn't found by doxygen because string.h wasn't included
  in StrError_R.h used to generate doc output. Including
  it wasn't necessary, so the references were dropped
  and fixed-width text is used to refer to the function
  instead.

Author: shenghaoyang

common/base/StrError_R.cpp

@@ -36,28 +36,29 @@ const int StrError_R_BufSize(1024);
 
 std::string StrError_R(int errnum) {
   // Pre-allocate to prevent re-allocation.
-  std::string out(StrError_R_BufSize, ' ');
-  out.assign("errno = ");
-
-  // Buffer size here is digits10 + 3 to account for:
-  // - Systems in which the int type cannot represent the full range of base 10
-  //   digits in the position of the most significant base 10 digit.
-  // - Terminating NUL byte added by snprintf.
-  // - 1 additional unit of storage just in case something absurd is used
-  //   on the host system (negative errno / zero-width int type, anyone? -
-  //   though this is meant to be impossible).
-  char errs[std::numeric_limits<int>::digits10 + 3];
-  if (static_cast<unsigned int>(snprintf(errs, sizeof(errs), "%d", errnum))
-        >= sizeof(errs)) {
-    out.append("<truncated>");
-  } else {
-    out.append(errs);
-  }
-  const std::string::size_type olen(out.size());
-
-  out.resize(StrError_R_BufSize, ' ');
+  std::string out(StrError_R_BufSize, '\0');
   if (StrError_R_XSI(errnum, &(out[0]), out.size())) {
-    out.resize(olen);
+    out.assign("errno = ");
+    // Buffer size here is digits10 + 3 to account for:
+    // - Systems in which the int type cannot represent the full range
+    //   of digits in the position of the most significant base 10 digit.
+    //   (i.e. 0-2 representable in an 8-bit unsigned integer at the
+    //   hundredth's place instead of 0-9 because an u8 is clamped to
+    //   [0, 255])
+    // - Terminating NUL byte added by snprintf.
+    // - 1 additional unit of storage just in case a negative errnum is
+    //   passed, and somehow StrError_R_XSI() failed on that.
+    char errs[std::numeric_limits<int>::digits10 + 3];
+    int r(snprintf(errs, sizeof(errs), "%d", errnum));
+    if (r < 0) {
+      out.append("<error>");
+    // Ugly cast required to avoid compiler warning when comparing
+    // numbers of different signedness.
+    } else if (static_cast<unsigned int>(r) >= sizeof(errs)) {
+      out.append("<truncated>");
+    } else {
+      out.append(errs);
+    }
   } else {
     out.resize(strlen(&(out[0])));
   }

include/ola/base/StrError_R.h

@@ -23,7 +23,7 @@
  * @defgroup strerror Description of system error codes
  * @brief Error descriptions
  * @details Convenience functions to obtain descriptions of system error codes.
- * The functions in this group are only defined if @ref strerror_r() is available.
+ * The functions in this group are only defined if \c strerror_r() is available.
  */
 
 /**
@@ -55,7 +55,7 @@ namespace ola {
 extern const int StrError_R_BufSize;
 
 /**
- * @brief XSI-compliant version of @ref strerror_r()
+ * @brief XSI-compliant version of \c strerror_r()
  *
  * See https://linux.die.net/man/3/strerror for more details.
  */