C static linkage: choosing the export boundary for internal helpers in a shared library

Answer

Use static only for helpers that are truly confined to a single .c file. Any helper that must be called from more than one translation unit needs external linkage, but you must hide it from the shared library’s public interface.

Confirmed facts

• static gives internal linkage; the symbol is not placed in the object’s global symbol table and therefore cannot be referenced from another translation unit.
• When building an ELF shared library with the default visibility (-fvisibility=default), any non‑static function or variable appears in the dynamic symbol table (.dynsym) and is callable by downstream code.
• Visibility attributes (__attribute__((visibility(\"hidden\")))) or a linker version script that whitelists exports remove the symbol from the dynamic symbol table while preserving ordinary external linkage inside the library.
• static does not protect a symbol from being referenced by other translation units; it merely prevents the symbol from having external linkage. If another file declares it extern the linker will still resolve it, but the symbol will not be exported from the .so.

Steps for this case

1. Identify helpers used in only one source file; declare them static (or better, place them in an unnamed namespace if using C++).
2. For helpers needed by multiple source files:
   1. Declare them without static in a header that is included where needed.
   2. Add visibility hiding directly on the definition, e.g.

      /* helper.c */
      #include \"helper.h\"
      void __attribute__((visibility(\"hidden\"))) internal_helper(void) {
          /* implementation */
      }
      

   3. Alternatively, compile the whole library with -fvisibility=hidden and create a linker version script that lists only the public API symbols to be exported (default visibility). Example script:

      {
          global:
              public_func1;
              public_func2;
          local:
              *;
      };

      Then link with -Wl,--version-script=mysym.map.
3. Verify the result: run readelf -s libfoo.so | grep internal_helper – the symbol should appear in the symbol table but not in the dynamic section (readelf -d libfoo.so or nm -D libfoo.so should not list it).

Missing diagnostic detail

If you already build with -fvisibility=default and have no version script, confirm whether you can add a linker script without breaking existing consumers; this determines whether the attribute‑per‑function approach or a centralized export map is preferable.