Question

I’m trying to replace some macro subroutines with inline functions, so the compiler can optimize them, so the debugger can step into them, etc. If I define them as normal functions it works:

void do_something(void)
{
  blah;
}

void main(void)
{
  do_something();
}

but if I define them as inline:

inline void do_something(void)
{
  blah;
}

void main(void)
{
  do_something();
}

it says “Error: Undefined external”. What does that mean? Taking a stab in the dark, I tried

static inline void do_something(void)
{
  blah;
}

void main(void)
{
  do_something();
}

and no more errors. The function definition and call to the function are in the same .c file.

Can someone explain why one works and the other doesn’t?

(Second related question: Where do I put inline functions if I want to use them in more than one .c file?)

Answer 1

First, the compiler does not always inline functions marked as inline; eg if you turn all optimizations off it will probably not inline them.

When you define an inline function

inline void do_something(void)
{
  blah
}

and use that function, even in the same file, the call to that function is resolved by the linker not the compiler, because it is implicitely “extern”. But this definition alone does not provide an external definition of the function.

If you include a declaration without inline

void do_something(void);

in a C file which can see the inline definition, the compiler will provide an external definition of the function, and the error should go away.

The reason static inline works is that it makes the function visible only within that compilatioin unit, and so allows the compiler to resolve the call to the function (and optimize it) and emit the code for the function within that compilation unit. The linker then doesn’t have to resolve it, so there is no need for an external definition.

The best place to put inline function is in a header file, and declare them static inline. This removes any need for an external definition, so it resolves the linker problem. However, this causes the compiler to emit the code for the function in every compilation unit that uses it, so could result in code bloat. But since the function is inline, it is probably small anyway, so this usually isn’t a problem.

The other option is to define it as extern inline in the header, and in one C file provide and extern declaration without the inline modifier.

The gcc manual explains it thus:

By declaring a function inline, you can direct GCC to make calls to
that function faster. One way GCC can achieve this is to integrate
that function’s code into the code for its callers. This makes
execution faster by eliminating the function-call overhead; in
addition, if any of the actual argument values are constant, their
known values may permit simplifications at compile time so that not
all of the inline function’s code needs to be included. The effect on
code size is less predictable; object code may be larger or smaller
with function inlining, depending on the particular case. You can
also direct GCC to try to integrate all “simple enough” functions into
their callers with the option -finline-functions.

GCC implements three different semantics of declaring a function
inline. One is available with -std=gnu89 or -fgnu89-inline or
when gnu_inline attribute is present on all inline declarations,
another when -std=c99, -std=c1x, -std=gnu99 or -std=gnu1x
(without -fgnu89-inline), and the third is used when compiling C++.

To declare a function inline, use the inline keyword in its
declaration, like this:

 static inline int
 inc (int *a)
 {
   return (*a)++;
 }

If you are writing a header file to be included in ISO C90 programs,
write __inline__ instead of inline.

The three types of inlining behave similarly in two important cases:
when the inline keyword is used on a static function, like the
example above, and when a function is first declared without using the
inline keyword and then is defined with inline, like this:

 extern int inc (int *a);
 inline int
 inc (int *a)
 {
   return (*a)++;
 }

In both of these common cases, the program behaves the same as if you
had not used the inline keyword, except for its speed.

When a function is both inline and static, if all calls to the
function are integrated into the caller, and the function’s address is
never used, then the function’s own assembler code is never
referenced. In this case, GCC does not actually output assembler code
for the function, unless you specify the option
-fkeep-inline-functions. Some calls cannot be integrated for various
reasons (in particular, calls that precede the function’s definition
cannot be integrated, and neither can recursive calls within the
definition). If there is a nonintegrated call, then the function is
compiled to assembler code as usual. The function must also be
compiled as usual if the program refers to its address, because that
can’t be inlined.

Note that certain usages in a function definition can make it
unsuitable for inline substitution. Among these usages are: use of
varargs, use of alloca, use of variable sized data types , use of computed goto,
use of nonlocal goto, and nested functions.
Using -Winline will warn when a function marked inline could not
be substituted, and will give the reason for the failure.

As required by ISO C++, GCC considers member functions defined within
the body of a class to be marked inline even if they are not
explicitly declared with the inline keyword. You can override this
with -fno-default-inline.

GCC does not inline any functions when not optimizing unless you
specify the always_inline attribute for the function, like this:

 /* Prototype.  */
 inline void foo (const char) __attribute__((always_inline));

The remainder of this section is specific to GNU C90 inlining.

When an inline function is not static, then the compiler must
assume that there may be calls from other source files; since a global
symbol can be defined only once in any program, the function must not
be defined in the other source files, so the calls therein cannot be
integrated. Therefore, a non-static inline function is always
compiled on its own in the usual fashion.

If you specify both inline and extern in the function definition,
then the definition is used only for inlining. In no case is the
function compiled on its own, not even if you refer to its address
explicitly. Such an address becomes an external reference, as if you
had only declared the function, and had not defined it.

This combination of inline and extern has almost the effect of a
macro. The way to use it is to put a function definition in a header
file with these keywords, and put another copy of the definition
(lacking inline and extern) in a library file. The definition in
the header file will cause most calls to the function to be inlined.
If any uses of the function remain, they will refer to the single copy
in the library.