Diagnosing BIND(C) Interoperability Failures: A Step‑by‑Step Fortran Guide

Problem Statement

When a Fortran program calls a C function via BIND(C), the most common failure is a link‑time unresolved symbol or a runtime crash due to a mismatched calling convention. This guide walks through the recognizable symptoms, the root causes, and a sequence of checks that will help you pinpoint and fix the problem.

Recognizable Condition

• Linker error: undefined reference to `external_func' or similar.
• Runtime crash after the first call (segmentation fault, illegal instruction).
• Wrong return value or corrupted arguments.

Diagnostic Table

Symptom	Likely Cause	Immediate Check
Unresolved symbol at link time	Incorrect symbol name or mangling	Verify BIND(C, name='…') matches the C function’s exported name
Runtime crash or corrupted data	Argument type mismatch or calling convention clash	Check argument kinds and order, ensure iso_c_binding is used
Wrong return value	Return type mismatch or ABI difference	Confirm return kind and that both compilers use the same ABI (e.g., System V AMD64)
Build succeeds but program hangs	Optimiser interfering with C calling convention	Compile with flags that disable sibling‑calling optimisations
Linker finds symbol but program crashes immediately	ABI mismatch between C and Fortran compiler	Check compiler versions and ABI compatibility notes

Ordered Checks & Fixes

1. Confirm BIND(C) Declaration
   • In Fortran, the subroutine or function must be declared with BIND(C) and an explicit name attribute if the C symbol differs.

     interface
        function add(a, b) bind(C, name='add') result(res)
           import :: C_INT
           integer(C_INT), value :: a, b
           integer(C_INT) :: res
        end function add
     end interface
     

   • In C, the function must be declared without name mangling: extern "C" int add(int a, int b);
2. Verify Argument Types
   • Fortran integer(C_INT) maps to int in C. If you use integer(C_LONG), it maps to long.
   • Use value attribute in Fortran to pass by value, matching C’s default.
   • For real(C_DOUBLE), C expects double.
   • For character(kind=C_CHAR), C expects char.
3. Check Name Mangling
   • Run nm on the C object to see the exported symbol.

     nm add.o | grep add
     

   • Ensure the Fortran compiler is not appending underscores or changing case. If you need a specific name, use bind(C, name='add').
4. Compiler Flags for Calling Convention
   • Some optimisers (e.g., GCC’s sibling‑calling optimisation) can change the stack layout. Disable it with -fno-optimize-sibling-calling.
   • Example compile command for GCC/Intel:

     gfortran -c -fno-optimize-sibling-calling test.f90
     gcc -c add.c
     gfortran test.o add.o -o test
     

5. ABI Compatibility
   • Both compilers must target the same Application Binary Interface (ABI). On Linux x86‑64, System V AMD64 is standard.
   • Check compiler docs for ABI flags (e.g., --abi=32 for 32‑bit).
6. Minimal Test Case
   • Create a tiny C file:

     /* add.c */
     #include <stdio.h>
     int add(int a, int b) {
        return a + b;
     }
     

   • And a Fortran file:

     program test
        use iso_c_binding
        interface
           function add(a, b) bind(C, name='add') result(res)
              import :: C_INT
              integer(C_INT), value :: a, b
              integer(C_INT) :: res
           end function add
        end interface
        print *, add(2, 3)
     end program test
     

   • Compile and link:

     gfortran -c test.f90
     gcc -c add.c
     gfortran test.o add.o -o test
     ./test
     # Expected output: 5
     

   • If the output is not 5 or you get a crash, revisit the checks above.
7. Escalation Criteria
   • If all checks pass but the program still crashes, suspect an ABI mismatch between the C and Fortran compilers. Try compiling both with the same vendor (e.g., GCC for both) or consult the vendor’s interoperability guide.
   • For large projects, enable debug symbols (-g) and use gdb to step into the C function to see where the stack or registers are corrupted.
   • If the issue persists across multiple C functions, consider using a wrapper that isolates Fortran and C, or switch to a language that guarantees ABI compatibility (e.g., C++ with extern "C").

Limitations & Practical Checks

• Different Fortran compilers (Gfortran, Intel, PGI) may have subtle differences in default integer kind. Always query integer(C_INT) size with print *, c_int_sizeof().
• Some systems use a 64‑bit int in C; if your Fortran code uses integer(C_INT) assuming 32‑bit, data will be truncated.
• Always verify the final binary with objdump -t or nm to ensure the symbol names match.
• When using libraries, check that the library’s ABI is documented and that you compile with matching flags.

Conclusion

By following the ordered checks above, you can systematically identify the root cause of a BIND(C) interoperability failure. The key is to ensure that symbol names, argument types, and calling conventions line up exactly between Fortran and C, and that both compilers target the same ABI. A minimal test case is an invaluable sanity check before scaling up to larger projects.