protoize man page on CentOS

Man page or keyword search:  
man Server   8420 pages
apropos Keyword Search (all sections)
Output format
CentOS logo
[printable version]

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 program 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	 gath‐
       ered 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	direc‐
       tory.   You  can	 specify  additional directories whose files should be
       converted with the -d DIRECTORY option.	You can also specify  particu‐
       lar  files  to exclude with the -x FILE option.	A file is converted if
       it is eligible, its directory name matches one of the specified	direc‐
       tory names, and its name within the directory has not been excluded.

       Basic conversion with protoize consists of rewriting most function def‐
       initions and function declarations to specify the types	of  the	 argu‐
       ments.  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 defi‐
       nitions 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  dis‐
       carded.

       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 func‐
	      tion that is called in the file and  was	not  declared.	 These
	      declarations precede 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 pro‐
	      totyped function definitions to old-style function  definitions,
	      where  the  arguments 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.	  pro‐
       toize 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  pro‐
       toize command, even though their .X files already exist, because other‐
       wise they won't get converted.

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

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  com‐
       ment  containing ??? each time it finds such a variable; all such vari‐
       ables 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  pro‐
       totypes	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 syn‐
       tax 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 preprocessing conditionals.  When this
       happens,	 protoize  changes nothing in regard to such a function.  pro‐
       toize 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 compila‐
       tion, 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 dec‐
       laration or definition in a region of source code where there  is  more
       than one formal parameter list present.	Thus, attempts to convert code
       containing multiple (conditionally compiled) versions of a single func‐
       tion  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 defi‐
       nition 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 programs 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  per‐
       mission notice identical to this one.

       Permission  is granted to copy and distribute translations of this man‐
       ual into another language, under the above conditions for modified ver‐
       sions,  except  that this permission notice may be included in transla‐
       tions approved by the Free Software Foundation instead of in the origi‐
       nal English.

GCC				8 December 2006			   protoize(1)
[top]

List of man pages available for CentOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net