protect_headers_setup(8)				      System Manager's Manual					  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

       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  sym-
       bolic  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 informa-
       tion 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  !=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, 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 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 process-
       ing 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
       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  pro-
       logue  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 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.

SEE ALSO

       Commands: cc(1), cpp(1), cxx(1)

       Programmer's Guide

       Compaq C Language Reference Manual

															  protect_headers_setup(8)