Manual Page Result
0
Command: protect_headers_setup | Section: 8 | Source: Digital UNIX | File: protect_headers_setup.8.gz
protect_headers_setup(8) System Manager's Manual protect_headers_setup(8)
NAME
protect_headers_setup.sh - Sets up header files for the -protect_head-
ers 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]
FLAGS
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 flag 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
flag 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 flag cannot be used
without the -l or -d flags. 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 cre-
ated 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 directo-
ries, 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 ac-
tions determined by the flag argument. For -l, it creates symbolic
links with the following names: __DECC_include_prologue.h __DECC_in-
clude_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 directo-
ries.
When passed other flags, 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 point-
ers were 64 bits and that structure members were naturally aligned.
These are the C and C++ compiler defaults. The interfaces to the sys-
tem libraries (the header files in the /usr/include tree) do not ex-
plicitly encode these assumptions.
You can alter the compiler's assumptions about pointer size (with
-xtaso_short) and structure member alignment (with -Zpn [where !=8] or
-nomember_alignment). If you use any of these options and your appli-
cation 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, world0); } 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: Run the
protect_headers_setup script to ensure that all system header file di-
rectories are protected from the previously described problems. A pro-
tected 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 com-
piler's pointer size and data layout environment to appropriate
values for system header files. The prologue file also sup-
presses certain warning-level and informational-level diagnostic
messages that are inappropriate for system header files. ,IP
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 di-
rective, the compiler searches for files with these special
names in the directory containing the header file. If the di-
rectory contains a prologue file, that file is included just be-
fore the file specified in the #include directive. If the di-
rectory 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 in-
cluded 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 flags 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 dis-
ables it otherwise.
If more than one such flag appears on the command line, only the last
one is applied.
Note
The protect headers feature is not available with cc -oldc or cpp
-oldc.
To alert users to the potential danger of compiling system headers with
nonstandard data layout in effect, cc, cxx, and cpp may issue the fol-
lowing 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_head-
ers_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_head-
ers feature is not always needed. The feature is not needed under ei-
ther of the following circumstances: When an application does not in-
clude 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 elimi-
nate 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 af-
ter 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 di-
rectory will not be protected unless it contains the appropriate pro-
logue and epilogue files. If protection is needed, you have two op-
tions: 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 align-
ment, you should add empty prologue and epilogue files to that direc-
tory (if they are not already present). This will prevent the pro-
tect_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.
RELATED INFORMATION
Commands: cc(1), cpp(1), cxx(1)
Programmer's Guide
DEC C Language Reference Manual delim off
protect_headers_setup(8)