Unintended public exposure of C symbols via @cImport in Zig

Direct Answers

1. Yes. Placing @cImport at file scope (or inside any non-pub block) keeps all imported C declarations file‑private. They cannot be accessed from other files unless you explicitly re‑export them.
2. Wrap the import in a private const at file scope, then selectively re‑export only what you need. Example:

   // file.zig
   const c = @cImport({
       @cInclude("stdlib.h");
   });
   
   pub const malloc = c.malloc;
   // free, calloc, etc. stay private
   

3. The warning is not sufficient on its own. It is a lint (compilation still succeeds), and it only fires when @cImport appears directly in a pub block. It does not catch transitive leaks through pub usingnamespace or re‑exports from dependencies. Treat it as a backstop, not a substitute for deliberate API design.

Why This Works

Zig defaults to file‑private visibility. Any declaration at file scope — including a const that holds an @cImport result — is invisible outside that file unless marked pub. The @cImport expression itself has no visibility; it inherits the visibility of the block it sits in. Therefore:

• pub { @cImport(...) } → every C declaration becomes public.
• const c = @cImport(...); (no pub) → the whole c namespace is private; only pub const malloc = c.malloc; (or similar) escapes.

Verification Steps (Zig 0.13.x–0.14.x)

1. Create a.zig:

   const c = @cImport({ @cInclude("stdlib.h"); });
   

2. Create b.zig:

   const A = @import("a.zig");
   const _ = A.c.malloc; // should fail: private field
   

3. Run zig build-exe b.zig — expect a “private field” error.
4. Change a.zig to pub { @cImport({ @cInclude("stdlib.h"); }) } and rebuild — compilation now succeeds, confirming the leak.
5. Add -Werror to your build to promote the pub-block warning to a hard error in CI.

Caveats & Edge Cases

• Transitive exposure: If a dependency you consume uses pub @cImport internally, those C symbols become part of its public API and therefore reachable by you. Audit build.zig.zon dependencies if you see unexpected C symbols.
• pub usingnamespace @cImport(...): This is the most leak‑prone pattern — avoid it in public headers.
• Version note: The warning appeared in Zig 0.13.0. Earlier versions silently leak; later versions may escalate the lint severity. Check the language reference under “Visibility” and “C Translation” for the authoritative rules.

One Diagnostic Detail That Changes the Recommendation

Are you building a library (intended for zig build --prefix consumption) or an executable? For libraries, the private-const pattern is mandatory to avoid polluting downstream consumers. For executables, the risk is lower but the same pattern keeps internal boundaries clean.