Man Pages

protoize(1) - phpMan protoize(1) - phpMan

Command: man perldoc info search(apropos)  


protoize(1)                           GNU                          protoize(1)



NAME
       protoize, unprotoize - automatically add or remove function prototypes

SYNOPSIS
       protoize [-CfgklNnqv] [-B DIRECTORY] [-c COMPILATION-OPTIONS] [-d DIRECTORY] [-i STRING] [-p PROGRAM] [-x FILE]
              [FILE...]

       unprotoize [-fkNnqv] [-c COMPILATION-OPTIONS] [-d DIRECTORY] [-i STRING] [-p PROGRAM] [-x FILE] [FILE...]

DESCRIPTION
       protoize is an optional part of GCC.  You can use it to add prototypes to a program, thus converting  the  pro-
       gram  to  ANSI  C in one respect.  The companion program unprotoize does the reverse: it removes argument types
       from any prototypes that are found.

       When you run these programs, you must specify a set of source files as command line arguments.  The  conversion
       programs  start out by compiling these files to see what functions they define.  The information gathered about
       a file FOO is saved in a file named FOO.X.

       After scanning comes the actual conversion.  The specified files are all eligible to be  converted;  any  files
       they include (whether sources or just headers) are eligible as well.

       But  not  all  the  eligible  files are converted.  By default, protoize and unprotoize convert only source and
       header files in the current directory.  You can specify additional directories whose files should be  converted
       with  the  -d  DIRECTORY  option.  You can also specify particular files to exclude with the -x FILE option.  A
       file is converted if it is eligible, its directory name matches one of the specified directory names,  and  its
       name within the directory has not been excluded.

       Basic  conversion  with  protoize  consists of rewriting most function definitions and function declarations to
       specify the types of the arguments.  The only ones not rewritten are those for varargs functions.

       protoize optionally inserts prototype declarations at the beginning of the source file, to make them  available
       for any calls that precede the function's definition.  Or it can insert prototype declarations with block scope
       in the blocks where undeclared functions are called.

       Basic conversion with unprotoize consists of rewriting most function declarations to remove any argument types,
       and rewriting function definitions to the old-style pre-ANSI form.

       Both  conversion  programs  print a warning for any function declaration or definition that they can't convert.
       You can suppress these warnings with the -q option.

       The output from protoize or unprotoize replaces the original source file.  The original file is  renamed  to  a
       name ending with .save.  If the .save file already exists, then the source file is simply discarded.

       protoize  and  unprotoize both depend on gcc(1) to scan the program and collect information about the functions
       it uses.

       The options are as follows:

       -B DIRECTORY
              Look for the file SYSCALLS.c.X in directory, instead of the usual directory  (normally  /usr/local/lib).
              This  file  contains prototype information about standard system functions.  This option applies only to
              protoize.

       -C     Rename files to end in .C instead of .c.  This is convenient if you are converting a C program  to  C++.
              This option applies only to protoize.

       -c COMPILATION-OPTIONS
              Use  COMPILATION-OPTIONS as the options when running gcc(1) to produce the .X files.  The special option
              -aux-info is always passed in addition, to tell gcc to write a  .X  file.   Note  that  the  compilation
              options  must  be  given as a single argument to protoize or unprotoize.  If you want to specify several
              gcc options, you must quote the entire set of compilation options to make them  a  single  word  in  the
              shell.   There  are certain gcc arguments that you cannot use, because they would produce the wrong kind
              of output.  These include -g, -O, -c, -S,-o.  If you include these in the COMPILATION-OPTIONS, they  are
              ignored.

       -d DIRECTORY
              Specify additional directories whose files should be converted.

       -g     Add  explicit  global declarations.  This means inserting explicit declarations at the beginning of each
              source file for each function that is called in the file and was not declared.  These declarations  pre-
              cede  the first function definition that contains a call to an undeclared function.  This option applies
              only to

       -i STRING
              Indent old-style parameter declarations with the string STRING.  This option applies only  to  protoize.
              unprotoize  converts  prototyped function definitions to old-style function definitions, where the argu-
              ments are declared between the argument list and the initial {.  By default, unprotoize uses five spaces
              as the indentation.  If you want to indent with just one space instead, use -i " ".

       -k     Keep the .X files.  Normally, they are deleted after conversion is finished.

       -l     Add  explicit local declarations.  protoize with -l inserts a prototype declaration for each function in
              each block which calls the function without any declaration.  This option applies only to protoize.

       -N     Make no .save files.  The original files are simply deleted.  Use this option with caution.

       -n     Make no real changes.  This mode just prints information about the conversions that would have been done
              without -n.

       -p PROGRAM
              Use the program PROGRAM as the compiler.  Normally, the name gcc is used.

       -q     Work quietly.  Most warnings are suppressed.

       -v     Print the version number, just like -v for gcc.

       -x FILE
              List of files to exclude from the conversion process.

       If  you  need  special compiler options to compile one of your program's source files, then you should generate
       that file's .X file specially, by running gcc on that source file with the appropriate options and  the  option
       -aux-info.  Then run protoize on the entire set of files.  protoize will use the existing .X file because it is
       newer than the source file.  For example:


       You need to include the special files along with the rest in the protoize command, even though their  .X  files
       already exist, because otherwise they won't get converted.


SEE ALSO
       gcc(1), and the Info entry for gcc, particularly Running protoize section.

HISTORY
       Ron Guilmette implemented the protoize and unprotoize tools.

AUTHORS
       See the GCC manual for the contributors to GCC.

CAVEATS
       The  conversion  programs  protoize  and unprotoize can sometimes change a source file in a way that won't work
       unless you rearrange it.

       protoize can insert references to a type name or type tag before the definition, or in a file  where  they  are
       not defined.

       If  this  happens,  compiler error messages should indicate where the new references are, so fixing the file by
       hand is straightforward.

       There are some C constructs which protoize cannot figure out.  For example, it can't determine  argument  types
       for declaring a pointer-to-function variable; this must be done by hand.  protoize inserts a comment containing
       ??? each time it finds such a variable; all such variables can be found by searching for this string.   ANSI  C
       does not require declaring the argument types of pointer-to-function types.

       Using  unprotoize  can easily introduce bugs.  If the program relied on prototypes to bring about conversion of
       arguments, these conversions will not take place in the program without prototypes.  One case in which you  can
       be  sure  unprotoize  is  safe is when you are removing prototypes that were made with protoize; if the program
       worked before without any prototypes, it will work again without them.

       You can find all the places where this problem might occur by  compiling  the  program  with  the  -Wconversion
       option.  It prints a warning whenever an argument is converted.

       Both  conversion  programs can be confused if there are macro calls in and around the text to be converted.  In
       other words, the standard syntax for a declaration or definition must not result from expanding a macro.   This
       problem  is  inherent  in  the  design  of C and cannot be fixed.  If only a few functions have confusing macro
       calls, you can easily convert them manually.

       protoize cannot get the argument types for a function whose definition was not actually compiled due to prepro-
       cessing  conditionals.   When  this  happens,  protoize changes nothing in regard to such a function.  protoize
       tries to detect such instances and warn about them.

       You can generally work around this problem by using protoize step by step, each time specifying a different set
       of  -D  options  for compilation, until all of the functions have been converted.  There is no automatic way to
       verify that you have got them all, however.

       Confusion may result if there is an occasion to convert a function declaration or definition  in  a  region  of
       source  code  where  there is more than one formal parameter list present.  Thus, attempts to convert code con-
       taining multiple (conditionally compiled) versions of a single function header (in the same vicinity)  may  not
       produce the desired (or expected) results.

       If you plan on converting source files which contain such code, it is recommended that you first make sure that
       each conditionally compiled region of source code which contains an alternative function header  also  contains
       at  least one additional follower token (past the final right parenthesis of the function header).  This should
       circumvent the problem.

       unprotoize can become confused when trying to convert a function definition or  declaration  which  contains  a
       declaration  for a pointer-to-function formal argument which has the same name as the function being defined or
       declared.  We recommand you avoid such choices of formal parameter names.

       It might be necessary to correct some of the indentation by hand and break long lines.   (The  conversion  pro-
       grams don't write lines longer than eighty characters in any case.)

BUGS
       For instructions on reporting bugs, see the GCC manual.

COPYING
       Copyright  1991,  1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free
       Software Foundation, Inc.

       Permission is granted to make and distribute verbatim copies of this manual provided the copyright  notice  and
       this permission notice are preserved on all copies.

       Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim
       copying, provided that the entire resulting derived work is distributed under the terms of a permission  notice
       identical to this one.

       Permission is granted to copy and distribute translations of this manual into another language, under the above
       conditions for modified versions, except that this permission notice may be included in  translations  approved
       by the Free Software Foundation instead of in the original English.



GCC                             8 December 2006                    protoize(1)