To: J3                                                     J3/18-145
From: Brian Friesen
Subject: CFI function to return error texts
Date: 2018-February-15


Introduction
------------

Table 18.5 defines 11 macros which correspond to various errors which
can be returned by the fucntions declared in
ISO_Fortran_binding.h. The standard defines the value of the
CFI_SUCCESS macro to be 0, but the remaining 10 macros do not have
prescribed values - they are required only to be unique and non-zero.

Consequently, when a function defined in ISO_Fortran_binding.h returns
an error, the user must look in the ISO_Fortran_binding.h source file
provided by the processor in order to determine which error
occurred. This is an unnecessary burden to place upon the user.

Proposal
--------

Add a new function to ISO_Fortran_binding.h:

  const char *CFI_strerror(const int CFI_error_macro)

which, when given an error code from a CFI function defined in
ISO_Fortran_binding.h, returns a processor-dependent string
representation of the error corresponding to the error code. For
example:

  CFI_strerror(CFI_SUCCESS)

could return "CFI_SUCCESS" or "No error detected." Similarly,

  CFI_strerror(CFI_ERROR_OUT_OF_BOUNDS)

could return "CFI_ERROR_OUT_OF_BOUNDS" or "A reference is out of
bounds." With this function, they can get the human-readable
representation of the error.