I want to define an inline function in a project, compiled with c99. How can I do it?
When I declare the function in a header file and give the detail in a .c file, the definition isn't recognized by other files. When I put the explicit function in a header file, I have a problem because all .o files who use it have a copy of the definition, so the linker gives me a "multiple definition" error.
What I am trying to do is something like:
header.h
inline void func()
{
do things...
}
lib1.c
#include "header.h"
...
lib2.c
#include "header.h"
with a utility which uses both lib1.o and lib2.o
Unfortunately not all compilers are completely complying to C99 in that point even if they claim that they'd be.
An conforming way to do this is
// header file. an inline definition alone is
// not supposed to generate an external symbol
inline void toto(void) {
// do something
}
// in one .c file, force the creation of an
// external symbol
extern inline void toto(void);
Newer versions of gcc, e.g, will work fine with that.
You may get away with it for other compilers (pretenders) by defining something like
#ifdef PRETENDER
# define inlDec static
# define inlIns static
#else
# define inlDec
# define inlIns extern
#endif
// header file. an inline declaration alone is
// not supposed to generate an external symbol
inlDec inline void toto(void) {
// do something
}
// in one .c file, force the creation of an
// external symbol
inlIns inline void toto(void);
Edit:
compilers with C99 support (usually option -std=c99) that I know of
gcc (versions >= 4.3 IIRC) implements
the correct inline model
pcc is also correct
ggc < 4.3 needs a special option to
implement the correct model,
otherwise they use their own model
that results in multiple defined
symbols if you are not careful
icc just emits symbols in every unit
if you don't take special care. But
these symbols are "weak" symbols, so
they don't generate a conflict. They
just blow up your code.
opencc, AFAIR, follows the old gcc specific model
clang doesn't emit symbols for inline functions at all, unless you have an extern declaration and you use the function pointer in one compilation unit.
tcc just ignores the inline keyword
If used by itself, in C99 inline requires that the function be defined in the same translation unit as it's being used (so, if you use it in lib1.c, it must be defined in lib1.c).
You can also declare a method as static inline (and put the definition in a header file shared between two source files). This avoids the multiple-definition issue, and lets the compiler inline the file across all the translation units where it's used (which it may or may not be able to do if you just declare the function in one translation unit).
See: http://www.greenend.org.uk/rjk/2003/03/inline.html
I think you don't need to use the inline word when you are defining and declaring the function inside the Header file, the compiler usually takes it as inline by default unless it's too long, in which case it will be smart enough to treat it as a normal function.
I think the multiple definition may be caused by the lack of a Include Guard in the Header file.
You should use something like this in the header:
#ifndef HEADERNAME_H
#define HEADERNAME_H
void func()
{
// do things...
}
#endif
Related
I've seen a few questions addressing this general topic, but I'm still unsure exactly what the correct approach is for ISO C, and how that may or may not vary from GNU C.
If I have some function inline void foo() in file.h defined with the inline keyword, should I also declare that function in file.c as extern void foo();? Assume that multiple .c files will include file.h.
From what I've read the answer seems to be "yes" and have something to do with how the compiler looks for definitions emitted by other translation units, but to be honest I don't fully understand the implications.
I'm working on a project right now that has a lot of functions declared inline within the header files, and none of those functions are declared in the corresponding .c files. Everything compiles without gcc complaining, but is this approach actually correct?
Yes, if you use inline without static, there needs to be an actual external definition of the function somewhere in case the compiler declines to inline it in one or more places. The canonical way to do that is to make a source file containining (using your example names) nothing but:
#include "file.h"
extern void foo();
Personally, I find extern inline semantics in C confusing and messy, and prefer to avoid them entirely by making all inline functions static. Of course this wastes space with multiple instantiations of the function if the compiler declines to inline, but you should not be doing this with functions of nontrivial size anyway.
inline means the compiler will expand that function where it is used in the code (instead of calling it as a function). That means that an inline definition in a header file with the function implementation in a .c file makes no sense, as wherever you include the header in another .c file the function can't be expanded inline as its code implementation is not known.
So you should keep the inline function and its code implementation in the header file.
I defined my function in .c (without header declaration) as here:
inline int func(int i) {
return i+1;
}
Then in the same file below I use it:
...
i = func(i);
And during the linking I got "undefined reference to 'func'". Why?
The inline model in C99 is a bit different than most people think, and in particular different from the one used by C++
inline is only a hint such that the compiler doesn't complain about doubly defined symbols. It doesn't guarantee that a function is inlined, nor actually that a symbol is generated, if it is needed. To force the generation of a symbol you'd have to add a sort of instantiation after the inline definition:
int func(int i);
Usually you'd have the inline definition in a header file, that is then included in several .c files (compilation units). And you'd only have the above line in exactly one of the compilation units. You probably only see the problem that you have because you are not using optimization for your compiler run.
So, your use case of having the inline in the .c file doesn't make much sense, better just use static for that, even an additional inline doesn't buy you much.
C99 inline semantics are often misunderstood. The inline specifier serves two purposes:
First, as a compiler hint in case of static inline and extern inline declarations. Semantics remain unchanged if you remove the specifier.
Second, in case of raw inline (ie without static or extern) to provide an inline definition as an alternative to an external one, which has to be present in a different translation unit. Not providing the external one is undefined behaviour, which will normally manifest as linking failure.
This is particularly useful if you want to put a function into a shared library, but also make the function body available for optimization (eg inlining or specialization). Assuming a sufficiently smart compiler, this allows you to recover many of the benefits of C++ templates without having to jump through preprocessor hoops.
Note that it's a bit more messy than I described here as having another file scope non-inline external declaration will trigger the first case as described in Jens' answer, even if the definition itself is inline instead of extern inline. This is by design so you can have have a single inline definition in a header file, which you can include into the source file that provides the external one by adding a single line for the external declaration.
This is because of the way GCC handle inline function. GCC performs inline substitution as the part of optimization.
To remove this error use static before inline. Using static keyword force the compiler to inline this function, which makes the program compile successfully.
static inline int func(int i) {
return i+1;
}
...
i = func(i);
I always though that the compiler can choose between inserting the function as is or to treat it as a regular function.
However I don't think it is possible if the inline function is defined in the header file (and can be included from multiple source files).
Is this correct?
Thanks
Yes, the compiler is completely free to chose if he really inlines an inline function. Actually he is free to inline any function, for which he has seen a definition.
inline as a keyword was introduced to avoid the "multiple symbol definition" problem. As such, it only makes sense if you have the definition in a header file.
The usual scheme is to have a definition like
inline void toto(void) {
...
}
in a header file that is included by several TU. Then in exactly one TU you have a declaration without inline
void toto(void);
which ensures that the symbol is exported by this TU.
In ISO C99 and ISO C11, having in the header file:
inline void f(void) { ..... }
means that the compiler can indeed choose between inlining the function, or treating it as a regular function.
However, when treating as a regular function, the compiler will behave similarly to if you had written void f(void);, i.e. it will expect to link to a body of f elsewhere.
So you need to put in exactly one of your translation units the line:
extern inline void f(void);
which causes the compiler to emit the body in that unit.
However, in GNU C, using inline void f(void) { ... } leads to undefined behaviour. The compiler can still choose, but when it chooses to treat as a regular function, it behaves as if you had written void f(void) { ... }, i.e. it emits the function body in every translation unit that uses it.
Some people write their functions in the header as static inline void f(void) { .... }, which works in both ISO C and GNU C, but possibly makes it harder for the linker to combine all of the copies into one.
See this thread for more detail
Assuming that an inline function is defined in a header like:
inline void f(void) {
...
}
...I can see two questions in your message, indeed:
Do you have to include that header with function definition in every
translation unit (TU) in which you are going to use this function?
Is the compiler free to inline the function in some TUs, while not
inlining it in other TUs, within the same project?
Ad.1: Short answer: Yes.
Long answer:
For compilation, definition (not only declaration!) of an inline function must be visible in every TU, where you are going to call it. Including the header in every TU is the best solution here.
By omitting the function’s storage class specifier in the header (as in the above code snippet, which is OK here, see below for short discussion on using extern or static), you go with the default, which means for inline functions: inline keyword is active in each TU in which you include this header. The function retains default external linkage (!), so it is also accessible from other TUs (i.e. in TUs not including this header), but the keyword inline is not active in the TUs that do not include functions’ inlined definition.
Now the linker must put a version of the function in some of the object files, so the function can be linked from the object files generated from TUs which do not include this functions’ ‘inline’ definition (or to the TUs where compiler decided not to inline despite the inline keyword).
You indicate that single TU by re-declaring the function as non-inlined, by adding after the included header file:
void f(void);
If you add static before your inline function definition in header, then each TU will generate its own copy and your executable code will probably take more space (subject to the zillion factors influencing code size with inlining). But you do not need to re-declare the function in any TU as non-inlined.
If you add extern to your inline function definition in header, then you will get ‘undefined reference’ linker error as none of TUs will generate executable code for it, despite possessing function’s definition (=knowing its body). To avoid it, at least one TU must additionally contain non-static re-declaration of this function:
inline void f(void);
(Note that GCC implements three different inlining semantics in C programs (GNU C90, gnu_inline, and one used e.g. with -std=c99), but to my knowledge none of them conforms to the above.)
Ad2: Yes. Even within a single TU the compiler is free to inline only a subset of calls to the inline function, or inline all calls, or none. Being honest, the same applies to functions defined without the inline keyword, because most compilers will try to ‘inline’, as part of their optimizations, even when the keyword is not used. After all, the keyword is just a hint to the compiler, as others have already highlighted in their comments/responses.
IMO both make the function to have a scope of the translation unit only.
What's the difference between "static" and "static inline" function?
Why should inline be put in a header file, not in .c file?
By default, an inline definition is only valid in the current translation unit.
If the storage class is extern, the identifier has external linkage and the inline definition also provides the external definition.
If the storage class is static, the identifier has internal linkage and the inline definition is invisible in other translation units.
If the storage class is unspecified, the inline definition is only visible in the current translation unit, but the identifier still has external linkage and an external definition must be provided in a different translation unit. The compiler is free to use either the inline or the external definition if the function is called within the current translation unit.
As the compiler is free to inline (and to not inline) any function whose definition is visible in the current translation unit (and, thanks to link-time optimizations, even in different translation units, though the C standard doesn't really account for that), for most practical purposes, there's no difference between static and static inline function definitions.
The inline specifier (like the register storage class) is only a compiler hint, and the compiler is free to completely ignore it. Standards-compliant non-optimizing compilers only have to honor their side-effects, and optimizing compilers will do these optimizations with or without explicit hints.
inline and register are not useless, though, as they instruct the compiler to throw errors when the programmer writes code that would make the optimizations impossible: An external inline definition can't reference identifiers with internal linkage (as these would be unavailable in a different translation unit) or define modifiable local variables with static storage duration (as these wouldn't share state accross translation units), and you can't take addresses of register-qualified variables.
Personally, I use the convention to mark static function definitions within headers also inline, as the main reason for putting function definitions in header files is to make them inlinable.
In general, I only use static inline function and static const object definitions in addition to extern declarations within headers.
I've never written an inline function with a storage class different from static.
inline instructs the compiler to attempt to embed the function content into the calling code instead of executing an actual call.
For small functions that are called frequently that can make a big performance difference.
However, this is only a "hint", and the compiler may ignore it, and most compilers will try to "inline" even when the keyword is not used, as part of the optimizations, where its possible.
for example:
static int Inc(int i) {return i+1};
.... // some code
int i;
.... // some more code
for (i=0; i<999999; i = Inc(i)) {/*do something here*/};
This tight loop will perform a function call on each iteration, and the function content is actually significantly less than the code the compiler needs to put to perform the call. inline will essentially instruct the compiler to convert the code above into an equivalent of:
int i;
....
for (i=0; i<999999; i = i+1) { /* do something here */};
Skipping the actual function call and return
Obviously this is an example to show the point, not a real piece of code.
static refers to the scope. In C it means that the function/variable can only be used within the same translation unit.
From my experience with GCC I know that static and static inline differs in a way how compiler issue warnings about unused functions. More precisely when you declare static function and it isn't used in current translation unit then compiler produce warning about unused function, but you can inhibit that warning with changing it to static inline.
Thus I tend to think that static should be used in translation units and benefit from extra check compiler does to find unused functions. And static inline should be used in header files to provide functions that can be in-lined (due to absence of external linkage) without issuing warnings.
Unfortunately I cannot find any evidence for that logic. Even from GCC documentation I wasn't able to conclude that inline inhibits unused function warnings. I'd appreciate if someone will share links to description of that.
One difference that's not at the language level but the popular implementation level: certain versions of gcc will remove unreferenced static inline functions from output by default, but will keep plain static functions even if unreferenced. I'm not sure which versions this applies to, but from a practical standpoint it means it may be a good idea to always use inline for static functions in headers.
In C, static means the function or variable you define can be only used in this file(i.e. the compile unit)
So, static inline means the inline function which can be used in this file only.
EDIT:
The compile unit should be The Translation Unit
In C++, one important effect of inline (that is not mentioned in the other answers yet, I think) is that it prevents linker errors when multiple definitions of the function are found.
Consider a function that is defined in a header file to allow it to be inlined into the source files that include the header. If the compiler decides to not inline (all calls to) this function, the function definition will be included into every object file that references it (i.e. does not inline all calls).
This might cause multiple definitions of the functions to read the linker (though not always, since it depends on the inlining decisions made by the compiler). Without the inline keyword, this produces a linker error, but the inline keyword tells the linker to just pick one definition and discard the rest (which are expected to be equal, but this is not checked).
The static keyword, on the other hand, ensures that if a function is included in the object file, it will be private to that object file. If multiple object files contain the same function, they will coexist and all calls to the function will use their "own" version. This means that more memory is taken up. In practice, I believe this means that using static for functions defined in header files is not a good idea, better to just use inline.
In practice, this also means that static functions cannot produce linker errors, so the effect of inline above is not really useful for static functions. However, as suggested by ony in another answer, adding inline might be helpful to prevent warnings for unused functions.
Note that the above is true for C++. In C, inline works a bit different, and you have to explicitly put an extern declaration in a single source file to have the inline function emitted into that object file so it is available for any non-inlined uses. In other words, inline means that a function is not emitted into any source file, even when not all calls are inlined, unless it is also specified as extern, and then it is emitted (even if all local calls are inlined). I'm not sure how that interacts with static, though.
An inline definition is not externally linked.
// average.h
#ifndef AVERAGE_H
#define AVERAGE_H
inline double average(double a, double b);
#endif
Attempting to call an inline function with the definition above from another
module after it has been preprocessed or linked to a c file will result in an error.
There are two ways to solve this problem:
make it a static inline function defintion.
Example:
// average.h
#ifndef AVERAGE_H
#define AVERAGE_H
static inline double average(double a, double b);
#endif
include the defintion from the c file and make it external.
Example:
#include "average.h"
extern double average(double a ,double b){
return (a + b) / 2;
}
I am getting the warning: function used but not defined. I have static
__inline__ in header file say a.h. The header file is included in a.c. I would like put all those inline function which are in header files into the .c files. Following code gives the idea of my problem.
Orginal code:
a.h:
static __inline__ function1(){
function definition;
}
I changed:
a.h:
static function1();
a.c:
#include "a.h"
static function1(){
function definition;
}
On doing above I got the warning:
warning: function function1 is used but not defined.
Could you please let me know why i am getting such warning? I would like to transfer all the __inline__ function into the .c so that I won't get the warning:
warning: function1 is could not be inlined, code size may grow.
Thanks in advance
You've declared the function to be static. This means that it is only visible within the current compilation unit. In other words: the implementation is only visible inside the a.c file. You need to remove the static keyword both in the a.h and a.c so that other .c files can see the function. You should specify a return value, e.g. void function1(); because it implicitly is int if you didn't specify one.
Functions declared static within a .c file are only visible/usable within that file only. If they are not used in it, then they are effectively dead code and the compiler warns you about this fact. In GCC you can use the unused function attribute to suppress this warning:
static int __attribute__((unused)) function1() {
...
}
EDIT:
In general you should usually follow the following guidelines regarding inline functions:
If they are used in multiple C files, declare them static and have their definition in an included header file. That allows all .c files that include that header to have their own private definition of the function, which allows the compiler to inline it. Lone static function prototypes make little to no sense in a header file that will be used by multiple source files, since their actual definitions will be missing.
If they are not intended to be reused, have their definition (and, if necessary, their prototype) in the .c file where they are supposed to be used.
If GCC complains about being unable to inline a function, due to the function size:
Ask yourself if you really need that function to be inlined - from my experience, the compiler usually knows best.
If you really, really want that function inlined, the always_inline function attribute may be of use. You may also have to provide a non-default -finline-limit=n option to GCC to increase the allowed size for inline functions.
See also this for additional information on inline functions and some possible pitfalls regarding their use.
EDIT 2:
If you have a static inline function defined in a shared header file and want to turn it into a normal, for lack of a better word, function you should:
Select a .c file where the presence of that function make sense (i.e. put it with other related functions).
Remove the static and inline keywords from its definition and move the definition from the header into that file.
Remove the static and inline keywords from its prototype and put it into the header file.
Congratulations, you now have a normal publicly-available function.
Disclaimer: you just made a function that was private to a number of files, public to all of your program. If there is another public symbol - variable or function - with the same name, you may get errors while linking or even strange behaviour at runtime. You've been warned...
Declare the function normally in the header file
a.h
#ifndef A_H_INCLUDED
#define A_H_INCLUDED
void function1(void);
#endif
Define the function in a single code file with no static
a.c
#include "a.h"
void function1(void) {
/* function definition */
}
and call the function from other files, after including the header
b.c
#include "a.h"
void quux(void) {
function1(); /* call regular function */
}
The way you had before (static and implementation in header file) worked because each code file that included that header got its own version of the function; different to every other function of the same name in every other file (but doing exactly the same).