protoize, unprotoize - automatically add or remove function
prototypes
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 ...
protoize is an optional part of GNU C. 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 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, and -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
precede the first function definition that
contains a
call to an undeclared function. This option applies
only to
protoize.
-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 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.
protoize will use the existing `.X' file because it is newer
than the
source file. For example:
$ gcc -Dfoo=bar file1.c -aux-info
$ protoize *.c
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.
Note: most of this information is out of date and superseded
by the EGCS
install procedures. It is provided for historical reference
only.
gcc(1), gcc-local(1)
Ron Guilmette implemented the protoize and unprotoize tools.
See the GNU CC manual for the contributors to GNU CC.
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 preprocessing 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 containing
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 programs don't write
lines longer than
eighty characters in any case.)
For instructions on reporting bugs, see the GCC manual.
Copyright 1991, 1992, 1993 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.
OpenBSD 3.6 January 14, 2003
[ Back ] |
