When to put static function definitions in header files in C?

Some ideas:

• One possible legitimate use I can think of is when you want to make a function available without creating a symbol with external linkage and polluting the external namespace. (But then you could just use an obscure prefixed name like mylib123__foobar, and #define foobar mylib123__foobar in the header file, so this one seems a little iffy.)
• You want certain functionality to be available purely through the header file, without requiring the user to link a library/object files. I could see this being a real motivation when providing a 'library' that's almost nothing but data structures and a few trivial pieces of code to manipulate them. In fact if the data structures are not opaque and meant to be accessed directly by the application, putting functions for use with them in the same header file (versus in a library) greatly reduces the risk of breaking things if/when you change the data structures.

• Perhaps the function is merely a wrapper for an external function, and the way the wrapper works might depend on compile-time options in the calling compilation unit. For example:

  static int foobar(int x){    return real_foobar(COMPILETIME_PARAMETER, x);}

  You might say just use macros, but what if foobar needs to be called via a function pointer for the intended usage?

With that having been said...

In reality, the main reason people put static functions in header files is usually based on some 10-years-outdated notion that it will improve performance, by permitting the compiler to inline the function or whatnot. Most people who do this have not done any measurement. Since modern compilers can compile the whole program as a unit if asked, and this theoretically results in a lot more possibilities for optimization, and since it's a questionable optimization to begin with, I'm really skeptical of placement of functions in headers for performance purposes.

This criticism especially applies the OP's example of "large" static functions in header files. There's almost no way a large function could benefit from inlining unless a constant argument value allows the compiler to eliminate 90% of the code or something. (For a real-world example of this extreme case, see some of the crazy inline function/macro definitions used in libavcodec. :-)

As a rule of thumb, you should not be putting static functions in header files. In a one-off program, it probably won't hurt anything, aside from expanding the size of your code because you've got a redundant copy in each module. In a shared library, it could easily cause bugs because now part of your library is embedded in the library's callers, so version mismatches could easily happen.

If you've got some terribly, horribly time-critical function where the time spent making the function call matters, you might consider putting it in the header, but in that case (a) you probably want to declare it inline as well, and (b) you've already done all the other optimizations you can find.

In short, unless you know beyond the shadow of a doubt that you need your static function in a header file... you don't want a static function in a header file; you want a non-static function in a .c file with its header in the .h.

In my experience it is generally a bad idea to define a function in a .h file, and i've never had cause to do so, doing so by accident once caused me no end of headaches.

Though i guess it would allow each file that includes the header to have its own separate implementation of the function which, if the function has static vars, may be the desired behaviour e.g. if you want/need to keep track of some information separately for each file.