I think I've pointed out that it is documented, in the "obsolete feature"
section of the CPP manual. I've digged a little further, and pragma once
and import where already considered obsolete by gcc for 2.95.3...
Incidentally, the reason they were added and then obsoleted may
be illustrative.
Consider the following expanded source code fragment:
#include <some/path/file.h>
#include <another/header.h>
#include <alternative/path/file.h>
which is the result of:
#include <some/path/file.h>
where the "file.h" in question begins with:
#include <another/header.h>
and "header.h" begins with:
#include <alternative/path/file.h>
As it happens, <alternative/path/file.h> is another name for
the file <some/path/file.h>.
If file.h contains a "#pragma once" directive, does this prevent
the double inclusion of the file under the alternative name
<alternative/path/file.h>? If so, why? If not, why not?
If file.h begins with:
#ifndef H_USUAL_PATH_TO_FILE_H
#define H_USUAL_PATH_TO_FILE_H
... contents of file.h ...
#endif
then, regardless of whether you:
#include <usual/path/file.h>
or:
#include <some/path/file.h>
or:
#include <alternative/path/file.h>
the actual contents get included exactly once. This is true whether
or not those files are links, symbolic links, or copies. GCC's
implementation of "#pragma once" attempted, at some point at least,
to use Unix/POSIX <dev,inode> pairs to uniquely identify files, so
that links and symbolic links were handled correctly, but as it
turns out, this fails when the file is on an NFS file server under
two different mount points. In this case, the files appeared to
be different, as if the two names specified copies of the file.
One could, perhaps, run something like an MD5 checksum on the entire
contents of the header. The chances of two different headers having
the same MD5 sum are low enough to disregard. But it seems simpler
to use header guards, which work even in the presence of links,
symlinks, copies, and NFS file servers.