|
|
protect_headers_setup(8)
Contents
|
protect_headers_setup.sh - Sets up header files for the
-protect_headers feature in cc, cxx, and cpp
/usr/lib/cmplrs/cc/protect_headers_setup.sh -l [-f]
[dirname]
/usr/lib/cmplrs/cc/protect_headers_setup.sh -d [-f]
[dirname]
/usr/lib/cmplrs/cc/protect_headers_setup.sh -i [dirname]
/usr/lib/cmplrs/cc/protect_headers_setup.sh -v [dirname]
Walks the specified directory tree and creates symbolic
links to <__DECC_include_prologue.h> and
<__DECC_include_epilogue.h> files. This requires write
permission for the directories in which the links will be
created. The script does not overwrite existing files with
the same name (except for prologue and epilogue files or
if the -f option is also specified). It does overwrite
existing symbolic links with the same name. Walks the
specified directory tree and deletes the symbolic links
named <__DECC_include_prologue.h> and <__DECC_include_epilogue.h>.
This requires write permission for the directories
from which the links will be deleted. The script does
not remove real files unless the -f option is also specified.
When combined with -l, causes the script to overwrite
existing files and symbolic links. When combined
with -d, causes the script to remove real files. The -f
option cannot be used without the -l or -d options. Walks
the specified directory tree and outputs an inventory of
all real files and symbolic links named
<__DECC_include_prologue.h> and <__DECC_include_epilogue.h>.
The inventory distinguishes between real files
and symbolic links. It also makes note of symbolic links
that differ from those that would have been created by the
-l option. Walks the specified directory tree and verifies
that all subdirectories that contain header files
also contain valid prologue and epilogue files. It outputs
a list of unprotected directories, including information
on what is wrong with the each directory.
The protect_headers_setup script walks the directory tree
rooted at /usr/include (or dirname if specified) and performs
one of several actions determined by the option
argument. For -l, it creates symbolic links with the following
names:
<__DECC_include_prologue.h>
<__DECC_include_epilogue.h>
The script creates the links in each directory that contains
header files. The links resolve to files located in
/usr/lib/cmplrs/cc. The files contain directives that can
be helpful to C and C++ compiler users who use the
-xtaso_short, -nomember_alignment, or -Zpn (where n!=8)
options.
If the optional dirname argument is specified, the command
walks that directory tree instead of /usr/include.
The tree walk includes walking symbolic links that refer
to directories.
When passed other options, the protect_headers_setup
script will delete these links (-d), inventory them (-i),
or verify that they exist (-v).
Header File Problem [Toc] [Back]
When the system libraries were built, the compiler assumed
that pointers were 64 bits and that structure members were
naturally aligned. These are the C and C++ compiler
defaults. The interfaces to the system libraries (the
header files in the /usr/include tree) do not explicitly
encode these assumptions.
You can alter the compiler's assumptions about pointer
size (with -xtaso_short) and structure member alignment
(with -Zpn [where n!=8] or -nomember_alignment). If you
use any of these options and your application includes a
header file from the /usr/include tree and then calls a
library function or uses types declared in that header
file, problems may occur. In particular, the data layouts
computed by the compiler when it processes the system
header file declarations may differ from the layouts compiled
into the system libraries. This situation can cause
unpredictable results. Consider the following example:
#include <stdio.h> int main () {
fprintf(stdout, "hello, world"); }
In the preceding example, <stdio.h> defines stdout as
(&_iob[1]). Array _iob has the type FILE, where FILE is a
structure containing a number of members that are pointer
types. Thus, the size of a FILE structure depends on the
size of a pointer. As a result, if the program is compiled
with -xtaso_short, the calculation of the address &_iob[1]
will differ from the calculation done in libc and the program
will not work as intended.
The problem is insidious because the program will compile
and link cleanly with -xtaso_short. However, it will not
run correctly because the data layouts will differ.
Similar problems can occur if a program is compiled with
-Zpn (where n!=8) or -nomember_alignment, a header file is
included from the /usr/include tree, and the program makes
use of a structure declared in that header file. The program's
notion of the physical layout of that structure may
differ from the actual layout compiled into the standard
system library.
Solution to the Header File Problem [Toc] [Back]
The -protect_headers feature in cc, cxx, and cpp can solve
the pointer size and data alignment problems. The solution
has two parts: Run the protect_headers_setup script to
ensure that all system header file directories are protected
from the previously described problems. A protected
directory contains files (symbolic links, actually) with
the following names:
<__DECC_include_prologue.h>
<__DECC_include_epilogue.h>
The prologue file contains #pragma directives that
set the compiler's pointer size and data layout
environment to appropriate values for system header
files. The prologue file also suppresses certain
warning-level and informational-level diagnostic
messages that are inappropriate for system header
files. The epilogue file contains #pragma directives
that restore the values from the previous
environment. When the -protect_headers feature is
in effect and the compiler encounters a #include
directive, the compiler searches for files with
these special names in the directory containing the
header file. If the directory contains a prologue
file, that file is included just before the file
specified in the #include directive. If the directory
contains an epilogue file, that file is
included just after the file specified in the
#include directive. This "bracketing" ensures that
system header files are always included in the
appropriate system environment.
The -protect_headers feature is enabled by default in the
cc compiler when processing C source files and in the cxx
compiler when processing C or C++ source files. It is
disabled by default for all other inputs to these compilers.
It is also disabled by default for all inputs to the
cpp preprocessor.
You can enable or disable the -protect_headers feature by
using the following command-line options to the cc, cxx,
or cpp commands: Enables the feature. Disables the feature.
Establishes the default behavior appropriate to the
command and the type of input; that is, enables the feature
for cc with C input and for cxx with C or C++ input,
and disables it otherwise.
If more than one such option appears on the command line,
only the last one is applied.
To alert users to the potential danger of compiling system
headers with nonstandard data layout in effect, cc, cxx,
and cpp may issue the following informational message: A
nondefault pointer size or member alignment is specified
and the system header files do not appear to be protected.
This may yield unpredictable results. The protect_headers_setup
script can help. See protect_headers_setup(8)
or cc(1) for details.
The message is issued if the -protect_headers feature is
enabled, the /usr/include directory does not contain prologue
and epilogue files, and the user specifies
-xtaso_short, -nomember_alignment, or -Zpn (where n!=8).
The message may be misleading in some cases because the
-protect_headers feature is not always needed. The feature
is not needed under either of the following circumstances:
When an application does not include any files from the
/usr/include tree When inclusions of system header files
have been explicitly protected by bracketing the #include
statements with #pragma directives
To prevent the message from appearing in the preceding
cases, use the -protect_headers none switch in your compilations.
You can also eliminate it by running the protect_headers_setup
script. The prologue and epilogue
files established by the script have no effect on the
results of a program.
When to Run the Script [Toc] [Back]
Ideally, the protect_headers_setup script should be run
immediately after the C or C++ compiler is installed. This
will protect the /user/include directories.
If you later add a subdirectory to the /usr/include tree,
the new directory will not be protected unless it contains
the appropriate prologue and epilogue files. If protection
is needed, you have two options: If the header files
define an interface to a library that was built using the
compiler's default assumptions about pointer size (64
bits) and structure member alignment, you should rerun the
script to protect that new directory. If the header files
define an interface to a library that was compiled with
-xtaso_short or with unnatural alignment, you should add
empty prologue and epilogue files to that directory (if
they are not already present). This will prevent the protect_headers_setup
script from adding links to the real
prologue and epilogue files when it is next run.
The second situation is rare, and the creation of such
libraries is not recommended.
Commands: cc(1), cpp(1), cxx(1)
Programmer's Guide
Compaq C Language Reference Manual
protect_headers_setup(8)
[ Back ] |
