 |
Index for
Section 8 |
|
 |
Alphabetical
listing for P |
|
 |
Bottom of
page |
|
protect_headers_setup(8)
NAME
protect_headers_setup.sh - Sets up header files for the -protect_headers
feature in cc, cxx, and cpp
SYNOPSIS
/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]
OPTIONS
-l 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.
-d 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.
-f 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.
-i 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.
-v 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.
DESCRIPTION
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
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
The -protect_headers feature in cc, cxx, and cpp can solve the pointer size
and data alignment problems. The solution has two parts:
1. 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.
2. 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:
-protect_headers all
Enables the feature.
-protect_headers none
Disables the feature.
-protect_headers default
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
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.
SEE ALSO
Commands: cc(1), cpp(1), cxx(1)
Programmer's Guide
Compaq C Language Reference Manual
|
Index for
Section 8 |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|