*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> protect_headers_setup (8)              



NAME    [Toc]    [Back]

       protect_headers_setup.sh  -  Sets  up header files for the
       -protect_headers  feature in cc, cxx, and cpp

SYNOPSIS    [Toc]    [Back]

       /usr/lib/cmplrs/cc/protect_headers_setup.sh    -l     [-f]

       /usr/lib/cmplrs/cc/protect_headers_setup.sh    -d     [-f]

       /usr/lib/cmplrs/cc/protect_headers_setup.sh -i  [dirname]

       /usr/lib/cmplrs/cc/protect_headers_setup.sh -v  [dirname]

OPTIONS    [Toc]    [Back]

       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.

DESCRIPTION    [Toc]    [Back]

       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


       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)

       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:


              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.

SEE ALSO    [Toc]    [Back]

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

       Programmer's Guide

       Compaq C Language Reference Manual

[ Back ]
 Similar pages
Name OS Title
h2ph Linux convert .h C header files to .ph Perl header files
h2ph OpenBSD convert .h C header files to .ph Perl header files
h2ph IRIX convert .h C header files to .ph Perl header files
h2xs Linux convert .h C header files to Perl extensions
h2xs IRIX convert .h C header files to Perl extensions
gensnmptree FreeBSD generate C and header files from a MIB description file
h2xs OpenBSD convert .h C header files to Perl extensions
limits Tru64 Header files for implementation-specific constants
istat IRIX print the header information of a list of image files.
inet6_opt_init Tru64 Return the length of an IPv6 extension header with no options and initialize the header
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service