unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



protect_headers_setup(8)			     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
      <&lt;__DECC_include_prologue.h>&gt; and <&lt;__DECC_include_epilogue.h>&gt; 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
      <&lt;__DECC_include_prologue.h>&gt; and <&lt;__DECC_include_epilogue.h>&gt;.  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 <&lt;__DECC_include_prologue.h>&gt; and
      <&lt;__DECC_include_epilogue.h>&gt;. 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 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:

       <&lt;__DECC_include_prologue.h>&gt;
       <&lt;__DECC_include_epilogue.h>&gt;

  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, world");
       }

  In the preceding example, <&lt;stdio.h>&gt; defines stdout as	(&&amp;_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 &&amp;_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:


       <&lt;__DECC_include_prologue.h>&gt;
       <&lt;__DECC_include_epilogue.h>&gt;

       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 environ-
       ment.

   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 com-
  pilers.  It is also disabled by default for all inputs to the	cpp prepro-
  cessor.

  You can enable or disable the	-protect_headers feature by using the follow-
  ing 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	epi-
  logue	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