add fi_strerror utility

Not infrequently, I find myself with the numeric return value from a
libfabric function but no easy way to call fi_strerror(3).  This commit
adds a small developer utility called fi_strerror that does what you
would expect.

```
$ fi_strerror
Usage: fi_strerror FI_ERROR_CODE

Displays the error string for the given numeric FI_ERROR_CODE.
FI_ERROR_CODE may be a hexadecimal, octal, or decimal constant.
For convenience, the absolute value of FI_ERROR_CODE will be used.
$ fi_strerror BOGUS
ERROR: unable to parse 'BOGUS'

Usage: fi_strerror FI_ERROR_CODE

Displays the error string for the given numeric FI_ERROR_CODE.
FI_ERROR_CODE may be a hexadecimal, octal, or decimal constant.
For convenience, the absolute value of FI_ERROR_CODE will be used.
$ fi_strerror 5
Input/output error
$ fi_strerror 0x107
Missing or unavailable completion queue
$ fi_strerror -0x107
Missing or unavailable completion queue
```

Signed-off-by: Dave Goodell <[email protected]>

.gitignore

@@ -34,3 +34,4 @@ config/missing
 config/test-driver
 
 util/fi_info
+util/fi_strerror

Makefile.am

@@ -70,14 +70,19 @@ endif
 linkback = $(top_builddir)/src/libfabric.la
 
 bin_PROGRAMS = \
-	util/fi_info
+	util/fi_info \
+	util/fi_strerror
 
 bin_SCRIPTS =
 
 util_fi_info_SOURCES = \
 	util/info.c
 util_fi_info_LDADD = $(linkback)
 
+util_fi_strerror_SOURCES = \
+	util/strerror.c
+util_fi_strerror_LDADD = $(linkback)
+
 src_libfabric_la_SOURCES = \
 	include/fi.h \
 	include/fi_abi.h \
@@ -138,6 +143,7 @@ nodist_rdmainclude_HEADERS = \
 endif HAVE_DIRECT
 
 real_man_pages = \
+        man/man1/fi_strerror.1 \
         man/man3/fi_av.3 \
         man/man3/fi_cm.3 \
         man/man3/fi_cntr.3 \

libfabric.spec.in

@@ -47,6 +47,7 @@ rm -rf %{buildroot}
 %defattr(-,root,root,-)
 %{_libdir}/lib*.so.*
 %{_bindir}/fi_info
+%{_bindir}/fi_strerror
 %dir %{_libdir}/libfabric/
 %doc AUTHORS COPYING README
 
@@ -56,6 +57,7 @@ rm -rf %{buildroot}
 %{_libdir}/*.a
 %{_libdir}/pkgconfig/libfabric.pc
 %{_includedir}/*
+%{_mandir}/man1/*
 %{_mandir}/man3/*
 %{_mandir}/man7/*
 

man/fi_strerror.1.md

@@ -0,0 +1,31 @@
+---
+layout: page
+title: fi_strerror(1)
+tagline: Libfabric Programmer's Manual
+---
+{% include JB/setup %}
+
+# NAME
+
+fi_strerror \- display libfabric error strings
+
+# SYNOPSIS
+
+```
+fi_strerror FI_ERROR_CODE
+```
+
+# DESCRIPTION
+
+Display the error string for the given numeric `FI_ERROR_CODE`.
+`FI_ERROR_CODE` may be a hexadecimal, octal, or decimal constant.  Although
+the [`fi_strerror`(3)](fi_errno.3.html) library function only accepts positive
+error values, for convenience this utility accepts both positive and negative
+error values.
+
+This is primarily a convenience tool for developers.
+
+# SEE ALSO
+
+[`fabric`(7)](fabric.7.html)
+[`fi_errno`(3)](fi_errno.3.html)

man/man1/fi_strerror.1

@@ -0,0 +1,25 @@
+.TH fi_strerror 1 "2016\-06\-30" "Libfabric Programmer\[aq]s Manual" "\@VERSION\@"
+.SH NAME
+.PP
+fi_strerror - display libfabric error strings
+.SH SYNOPSIS
+.IP
+.nf
+\f[C]
+fi_strerror\ FI_ERROR_CODE
+\f[]
+.fi
+.SH DESCRIPTION
+.PP
+Display the error string for the given numeric \f[C]FI_ERROR_CODE\f[].
+\f[C]FI_ERROR_CODE\f[] may be a hexadecimal, octal, or decimal constant.
+Although the \f[C]fi_strerror\f[](3) library function only accepts
+positive error values, for convenience this utility accepts both
+positive and negative error values.
+.PP
+This is primarily a convenience tool for developers.
+.SH SEE ALSO
+.PP
+\f[C]fabric\f[](7) \f[C]fi_errno\f[](3)
+.SH AUTHORS
+OpenFabrics.

util/strerror.c

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2013-2014 Intel Corporation.  All rights reserved.
+ * Copyright (c) 2016 Cisco Systems, Inc.  All rights reserved.
+ *
+ * This software is available to you under the BSD license below:
+ *
+ *     Redistribution and use in source and binary forms, with or
+ *     without modification, are permitted provided that the following
+ *     conditions are met:
+ *
+ *      - Redistributions of source code must retain the above
+ *        copyright notice, this list of conditions and the following
+ *        disclaimer.
+ *
+ *      - Redistributions in binary form must reproduce the above
+ *        copyright notice, this list of conditions and the following
+ *        disclaimer in the documentation and/or other materials
+ *        provided with the distribution.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AWV
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#include <limits.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <rdma/fi_errno.h>
+
+static void usage(const char *argv0)
+{
+	printf("Usage: %s FI_ERROR_CODE\n", argv0);
+	printf("\n");
+	printf("Displays the error string for the given numeric FI_ERROR_CODE.\n");
+	printf("FI_ERROR_CODE may be a hexadecimal, octal, or decimal constant.\n");
+	printf("For convenience, the absolute value of FI_ERROR_CODE will be used.\n");
+}
+
+int main(int argc, char *argv[])
+{
+	char *endptr;
+	long err;
+
+	if (argc != 2) {
+		usage(argv[0]);
+		return EXIT_FAILURE;
+	}
+
+	if (strcmp(argv[1], "-h") == 0) {
+		usage(argv[0]);
+		return EXIT_SUCCESS;
+	}
+
+	errno = 0;
+	endptr = NULL;
+	err = strtol(argv[1], &endptr, 0);
+	if (errno || endptr == argv[1] || *endptr != '\0') {
+		printf("ERROR: unable to parse '%s'\n\n", argv[1]);
+		usage(argv[0]);
+		return EXIT_FAILURE;
+	}
+
+	if (err < (long)INT_MIN || err > (long)INT_MAX) {
+		printf("ERROR: '%s' is out of range\n\n", argv[1]);
+		usage(argv[0]);
+		return EXIT_FAILURE;
+	}
+
+	printf("%s\n", fi_strerror(err >= 0 ? (int)err : (int)-err));
+
+	return EXIT_SUCCESS;
+}