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