When can you omit the file extension in an #include directive?

The C++ standard headers do not have a “.h” suffix. I believe the reason is that there were many, different pre-standard implementations that the standard would break. So instead of requiring that vendors change their exiting “iostream.h” (for example) header to be standards compliant (which would break their existing user’s code), the standards committee decided that they’d drop the suffix (which, I believe no then existing implementation had already done).

That way, existing, non-standard programs would continue to work using the vendor’s non-standard libraries. When the user wanted to make their programs standards compliant, one of the steps they would take is to change the “#include” directive to drop the “.h” suffix.

So

#include <iostream>     // include the standard library version
#include <iostream.h>   // include a vendor specific version (which by 
                        //      now might well be the same)

As other answers have mentioned, writers of non-standard libraries may choose either naming convention, but I’d think they would want to continue using “.h” or “.hpp” (as Boost has done) for a couple reasons:

1. if & when the library gets standardized, the standard version won’t automatically override the previous, non-standard one (causing broken user code in all likelihood)
2. it seems to be a convention (more or less) that headers without a suffix are standard libraries, and those with a suffix (other than the old C headers) are non-standard.

Note that a similar problem happened when the committee went to add hash maps to the STL – they found that there are already many (different) hash_map implementations that exist, so instead of coming up with a standard one that breaks a lot of stuff out there today, they are calling the standard implementation “unordered_map“. Namespaces were supposed to help prevent this type of jumping through hoops, but it didn’t seem to work well enough (or be used well enough) to allow them to use the more natural name without breaking a lot of code.

Note that for the ‘C’ headers, C++ allows you to include either a <cxxxxxx> or <xxxxxx.h> variant. The one that starts with ‘c’ and has no “.h” suffix put their declarations in the std namespace (and possibly the global namespace), the ones with the “.h” suffix put the names in the global namespace (some compilers also put the names in the std namespace – it’s unclear to me if that’s standard compliant, though I don’t see the harm).