I have been reading Zed Shaw's "Learn C The Hard Way". In the 20th chapter, the author creates a header file e.g. headerfile.h and includes the line
#ifndef _headerfile_h. I understand the #ifndef directive but not _headerfile_h. Please explain this _headerfile_h or mention any resource to look for it.
#ifndef _headerfile_h
#define _headerfile_h
…other material…
#endif /* _headerfile_h */
It's simply a unique name that will only used by that header, to prevent problems if the header is included twice.
Note that you should not, in general, create function, variable, tag or macro names that start with an underscore. Part of C11 §7.1.3 Reserved identifiers says:
All identifiers that begin with an underscore and either an uppercase letter or another underscore are always reserved for any use.
All identifiers that begin with an underscore are always reserved for use as identifiers with file scope in both the ordinary and tag name spaces.
See also:
What does double underscore (__const) mean in C?
How do I use extern to share variables between source files?
Should I use #include in headers?
Why doesn't the compiler generate a header guard automatically?
What is a good reference documenting patterns of use of ".h" files in C?
When to use include guards in C
and probably some others too. A number of those questions have further links to other resources — SO questions and external links.
The directive #ifndef checks if the "argument" is defined as a macro or not. If it's not defined (the n in ifndef stands for "not") then the next block up to the matching #endif is passed on by the preprocessor.
If the macro is defined, then the block is skipped and not passed on to the compiler by the preprocessor.
So what #ifndef _headerfile_h does is check if the symbol _headerfile_h is defined as a macro or not.
From the macro name it seems like this is part of an header include guard.
Related
I have often seen code like
#ifndef HEADERFILE_H
#define HEADERFILE_H
// some declarations in
// the header file.
#endif
I want to know what #define HEADERFILE_H define HEADERFILE_H to?
I tried doing
cout<<HEADERFILE_H<<endl;
but I am getting
error: expected expression
A define preprocessing directive has the form # define identifier preprocessing-tokens, ending with a new-line character. The preprocessing-tokens is a list of zero or more preprocessing tokens. It may be empty, that is, it may have zero tokens. This means, that when the identifier is encountered in a place where macro replacement occurs, it will be replaced with nothing.1
Tests of the form #ifdef identifier, #ifndef identifier, or define identifier in a #if or #elif directive test whether identifier is defined or not. If it was not defined (or its definition was removed with the #undef directive), then the test indicates it is not defined. If it was defined, then the test indicates it was defined, even if the definition is for zero tokens.
A definition with zero tokens is different from no definition at all, and defined identifier will evaluate as true for the former and false for the latter.
Footnote
1 If the list does have tokens, then identifier will be replaced with those tokens and # and ## operators among them will be applied. A preprocessing token is largely an identifier (like foo34), a constant (like 3, 4u, or 1.8e4), one of the C operators or special characters (like * or +=), or certain other components of the C language.
It actually defines "nothing else than itself". That is: you may define a macro without assigning it a specific value. Since you can check if a given macro is defined or not, you therefore can ask for the simple "existence" of a given macro.
This is useful to indicate a context (for example, if you're compiling for a given OS) and/or the availability of some resources.
In this particular example, this is a called a "guard": it will define itself if this hasn't been done first before, as well as including the rest of the file, which is totally embedded in the #ifdef … #endif clause.
This is used to implement a kind of require_once, that is something that will be included if needed, but not multiple times. This is required when you are defining functions or declaring variables at a global scope, for instance.
This is a language idiom (I will comment it):
#ifndef HEADERFILE_H
Between this, and the last #endif everything is included in compilation, but only if HEADERFILE_H has not been defined before.
#define HEADERFILE_H
The first thing we do in the block is to #define the identifier, so next time we find this fragment again later, the contents between #ifndef and #endif will not be #included again (because of the identifier declaration).
// some declarations in
// the header file.
this block will be included only once, even if you #include this file several times.
#endif
and this marks the end of the protected block.
It is common to include some file that, indeed, #includes another, and that file includes another, leading to a point in which you don't know which files have been included and which don't. This phrasing allows you to be protected, and to be able to #include the same file several times (normally you cannot, as some definitions cannot be repeated in the same compilation unit, e.g. declarations) the lines above will include the contents and define the identifier, making next inclussions (that are effectively done) not to include the contents, as the identifier appears as #definen in second and ulterior times.
Per this question, it seems there is some flexibility to how you can write that--
#ifndef _HEADER_H
or:
#ifndef __HEADER___H__
etc. It's not set in stone.
But I don't understand why we're using underscores at all in the first place. Why can't I just write:
#ifndef header.h
What's wrong with that? Why are we placing underscores everywhere and capitalizing everything? What does the preprocessor do with underscores?
header.h is not a valid identifier. You cannot have a period in a macro name.
That said, the name you pick for your include guard macros is completely arbitrary. After all, it's just another variable. It is purely convention (and reasonable in order to avoid clashes) to name them after the file.
I encourage you to phrase the header structure out aloud to see what the preprocessor does.
#ifndef MY_HEADER_H /* If the macro MY_HEADER_H is not defined (yet)... */
#define MY_HEADER_H /* ... then define it now ... */
... /* ... and deal with all this stuff ... */
#endif /* ... otherwise, skip all over it and go here. */
You see that this mechanism works equally well if you substitute MY_HEADER_H with I_REALLY_LIKE_BANANAS or whatever. The only requirement is that it be a valid macro identifier and not clash with the name of any other include guard.
In the above example, the macro is defined empty. That's fine, but it is not the only option. The second line could equally well read
#define MY_HEADER_H 1
which would then define the macro to 1. Some people do this but it doesn't really add anything and the value 1 is rather arbitrary. I generally don't do this. The only advantage is that if you define it to 1, you can also use #if in addition to #ifdef.
A final word of caution: Identifiers that start with an underscore or contain two or more consecutive underscore characters are reserved for the implementation and should not be used in user-code. Hence, _MY_HEADER_H and __MY_HEADER__H__ are both unfortunate choices.
The logic by which the preprocessor finds the correct header file if you say
#include <myheader.h>
is completely unrelated. Here, myheader.h names a file and the preprocessor will search for it in a number of directories (that usually can e configured via the -I command line option). Only after it has found and opened the file it will go ahead parsing it and thereby, it will eventually find the include guards that will cause it to essentially skip over the file if it has already parsed it before (and the include guard macro is therefore already defined so the first check evaluates to false).
Because #ifdef or #ifndef requires a preprocessor symbol after it, and these symbols cannot contain dots.
In the C11 (latest draft) spec n1570 (§6.10.1):
Preprocessing directives of the forms
# ifdef identifier new-line group opt
# ifndef identifier new-line group opt
check whether the identifier is or is not currently defined as a macro name.
and identifiers cannot contain dots (§6.4.2.1)
BTW, include guards are not required to have #ifdef symbols related to the file name. You can have a header file foo.h guarded with a #ifndef JESUISCHARLIEHEBDO or by #ifndef I_LOVE_PINK_ROSES_BUT_NOT_YELLOW_ONES preprocessor directive if you want so. But by human convention, the names are often related.
Notice that identifiers starting with an underscore are implementation defined, so you should rather avoid #ifndef _FOO_INCLUDED but prefer #ifndef FOO_INCLUDED
In the code I'm writing, I have been told to define a variable in a header file in the following way:
#define CLR_BLACK 0x0000
and since this is the only example I've been given, I was wondering whether all variables defined in a header file with the #define command need to be in caps. For example, would the following be valid?
#define videoBuffer (u16*)0x6000000
No. You can use any combination of alphanumeric characters and underscores. Don't start with a number.
However a variable name like videoBuffer would be difficult to distinguish from regular variables (without syntax coloring). That's why most people either use all caps for preprocessor macros or start them with a lower case k, like this: kMyPreprocessorMacro
EDIT: Those are not "global variables" by the way (as you tagged). They're preprocessor macros. Basically an automatic find and replace mechanism that is run at compile time.
No.
#define is a pre-processor macro. It replaces every occurrence of the first string after it with whatever comes after the string. The first string does not need to be in caps.
No, but it's a common and useful convention so if you're reading the code you can see what's a macro and what isn't. See C++ #ifndef for include files, why is all caps used for the header file?
I'm currently learning the C programming language (coming from Java) and I'm a bit confused as to how to define a macro.
In order for other code to use the macro, the header file must have it. But if I define the macro in the header file, then the source file can't use it. Do I have to define it in both or do I have to #include the source file's own header file?
Source files virtually always include their "own" header file -- i.e., a header that declares the functions defined in a source file. Declaring a function before actually defining it is perfectly legal and often desirable: you may get compile errors if the header is accidentally mismatched, and that's a good thing.
First #include is essentially like directly inserting the file in your file. It is run by the compiler pre-processor, which is run before the compiler. Google C preprocessor for more info...
Typically setup is:
#include "macros.h"
...
printf("Macro value %d\n", MACRO_HERE(1) );
and in your header file, macros.h
#ifndef MACROS_H_
#define MACROS_H_
#define MACRO_HERE( n ) ( n + 1 )
#endif
The wrapped #ifdef(s) prevent the macro from being redefined if you later have another include file which also includes macro.h
See also: #pragma once (which is widely used in many compilers also)
You can define it both in the header or the implementation file, but it needs to be visible to the translation unit you use it in.
If it's for use just inside one implementation file, define it in that file only.
If more files use the macro, define it in a header and include that header wherever you need the macro.
If I have a several header files :lets say 1.h, 2.h, 3.h.
Let's say the all three of the header files have #include <stdlib.h> and one of the include files in them.
When I have to use all 3 header files in a C file main.c,
it will have 3 copies of #include <stdlib.h> after the preprocessor.
How does the compiler handle this kind of conflict?
Is this an error or does this create any overhead?
If there are no header guards, what will happen?
Most C headers include are wrapped as follows:
#ifndef FOO_H
#define FOO_H
/* Header contents here */
#endif
The first time the preprocessor scans this, it will include the contents of the header because FOO_H is undefined; however, it also defines FOO_H preventing the header contents from being added a second time.
There is a small performance impact of having a header included multiple times: the preprocessor has to go to disk and read the header each time. This can be mitigated by adding guards in your C file to include:
#ifndef FOO_H
#include <foo.h>
#endif
This stuff is discussed in great detail in Large-Scale C++ Software Design (an excellent book).
This is usually solved with preprocessor statements:
#ifndef __STDLIB_H
#include <stdlib.h>
#define __STDLIB_H
#endif
Although I never saw it for common header files like stdlib.h, so it might just be necessary for your own header files.
The preprocessor will include all three copies, but header guards will prevent all but the first copy from being parsed.
Header guards will tell the preprocessor to convert subsequent copies of that header file to effectively nothing.
Response to edit:
Standard library headers will have the header guards. It would be very unusual and incorrect for them to not have the guards.
Similarly, it is your responsibility to use header guards on your own headers.
If header guards are missing, hypothetically, you will get a variety of errors relating to duplicate definitions.
Another point: You can redeclare a function (or extern variable) a bazillion times and the compiler will accept it:
int printf(const char*, ...);
int printf(const char*, ...);
is perfectly legal and has a small compilation overhead but no runtime overhead.
That's what happens when an unguarded include file is included more than once.
Note that it is not true for everything in an include file. You can't redeclare an enum, for example.
This is done by one of the two popular techniques, both of which are under stdlib's responsibility.
One is defining a unique constant and checking for it, to #ifdef out all the contents of the file if it is already defined.
Another is microsoft-specific #pragma once, that has an advantage of not having to even read the from the hard drive if it was already included (by remembering the exact path)
You must also do the same in all header files you produce. Or, headers that include yours will have a problem.
As far a I know regular include simply throws in the contents of another file. The standard library stdlib.h urely utilizes the code guards: http://en.wikipedia.org/wiki/Include_guard, so you end up including only one copy. However, you can break it (do try it!) if you do: #include A, #undef A_GUARD, #include A again.
Now ... why do you include a .h inside another .h? This can be ok, at least in C++, but it is best avoided. You can use forward declarations for that: http://en.wikipedia.org/wiki/Forward_declaration
Using those works for as long as your code does not need to know the size of an imported structure right in the header. You might want to turn some function arguments by value into the ones by reference / pointer to solve this issue.
Also, always utilize the include guards or #pragma once for your own header files!
As others have said, for standard library headers, the system must ensure that the effect of a header being included more than once is the same as the header being included once (they must be idempotent). An exception to that rule is assert.h, the effect of which can change depending upon whether NDEBUG is defined or not. To quote the C standard:
Standard headers may be included in any order; each may be included more than once in
a given scope, with no effect different from being included only once, except that the
effect of including <assert.h> depends on the definition of NDEBUG.
How this is done depends upon the compiler/library. A compiler system may know the names of all the standard headers, and thus not process them a second time (except assert.h as mentioned above). Or, a standard header may include compiler-specific magic (mostly #pragma statements), or "include guards".
But the effect of including any other header more than once need not be same, and then it is up to the header-writer to make sure there is no conflict.
For example, given a header:
int a;
including it twice will result in two definitions of a. This is a Bad Thing.
The easiest way to avoid conflict like this is to use include guards as defined above:
#ifndef H_HEADER_NAME_
#define H_HEADER_NAME_
/* header contents */
#endif
This works for all the compilers, and doesn't rely of compiler-specific #pragmas. (Even with the above, it is a bad idea to define variables in a header file.)
Of course, in your code, you should ensure that the macro name for include guard satisfies this:
It doesn't start with E followed by an uppercase character,
It doesn't start with PRI followed by a lowercase character or X,
It doesn't start with LC_ followed by an uppercase character,
It doesn't start with SIG/SIG_ followed by an uppercase character,
..etc. (That is why I prefer the form H_NAME_.)
As a perverse example, if you want your users guessing about certain buffer sizes, you can have a header like this (warning: don't do this, it's supposed to be a joke).
#ifndef SZ
#define SZ 1024
#else
#if SZ == 1024
#undef SZ
#define SZ 128
#else
#error "You can include me no more than two times!"
#endif
#endif