Correct naming convention for C library code [closed]

Question

What is the correct way to name files and functions that are part of a C based code library/API?

Answer 1

What you can (but should not) do is be completely careless and use no systematic naming conventions at all. This 'works', but makes life uncomfortable for your customers; they have no easy way of knowing which names they can use in their own program. (I came across a library which defined a undocumented function for its internal use that was called error(). The name didn't match any part of the external documented namespaces. At the time, one of my own standard error reporting functions was also called error() — though it is now err_error(); that meant I couldn't use my own standard error reporting functions with that library. The upshot was I didn't use that library if I didn't have to; it was too much of a nuisance to use.)

So, you shouldn't be like that. You should be careful in the names you expose.

Your public header should use one (or a very few) systematic prefixes, which are documented. Typically, you'd choose a prefix such as PFX, and use that:

• enumeration constants start PFX_.
• macros start PFX_.
• functions start pfx_.
• global variables (you don't have any of those, do you) start pfx_.
• type names and structure or union tags start pfx_.
• Your private variables and functions that are visible outside their own source file have a systematic prefix (possibly pfx_ again, or maybe pfxp_ where the last p is for private, or perhaps pfx[A-Z] so that private names are camel-cased but start with pfx).

Only variables or functions that are strictly file scope (no external linkage) are not constrained by these rules, but even then, it is advisable to use the naming convention (so if a function needs to be used by two files later, you don't have to revise the calls in the code where the function was previously static).

This way, you can simply document that names starting PFX_ or pfx_ are reserved by your library. Users can still use names with the same prefix (you can't stop them), but they do so at their own risk because upgrades to the library might add names that are reserved. They can keep well clear of your names because you've documented them, and because the documentation is (relatively) easy to understand.

Note that the C standard and the POSIX standards both lay down rules for reserved names. However, the rules for the reserved POSIX and C names are considerably more complex than just a single prefix. They're also sweeping. For example, POSIX reserves all names ending _t for use as type names if any POSIX header is included.