- 1 - Formatted: January 15, 2025
PROTOIZE(1) PROTOIZE(1)
21 January 1990
NAME
protoize - convert K&R C source code to ANSI C prototype format
SYNOPSIS
protoize [.B -VqfnkNlgC ] [ -B <dir>
] [ -c <cc opts> ] [ file... ]
DESCRIPTION
Protoize aids in the conversion of
K&R C source code files to ANSI C source code files with function
prototypes. This conversion is useful for eliciting more complete
interface checking from ANSI C compilers, or as a preliminary step in
the conversion of C programs to C++.
Protoize is designed to be used in conjunction with the GNU C
compiler. The GNU C compiler does preliminary information gathering
about functions by analyzing the files to be converted. The GNU C
compiler may be invoked automatically as a result of running protoize
so it is important to have it properly installed before attempting to
convert source files via protoize.
Protoize actually has two primary functions. First, It converts
existing function declarations and definitions to prototype form.
Second, for cases in which functions are called before they have been
declared (i.e. points of implicit function declarations), protoize can
be instructed to insert new prototype style function declarations into
the source code. For implicit function declarations, protoize can
either insert the new (explicit) function declaration at the very
beginning of the block which contains the implicit declaration, or (at
the user's option) these explicit declarations can be inserted near
the tops of the source files where the implicit declarations occurred.
The insertion of these new (explicit) function declarations (by
protoize) assures that all function calls in your source files will be
checked for the correct number and types of parameters during
- 1 - Formatted: January 15, 2025
PROTOIZE(1) PROTOIZE(1)
21 January 1990
subsequent compilations.
Protoize supports the conversion of both large and small systems of C
source code to prototype form.
Protoize can perform the conversion of an entire program in one
(batch) step.
Protoize is able to convert entire systems of C source code because it
knows how to use information (gleaned by the C compiler) from one
source file to convert function definitions and declarations in that
same source file or in other source files (as required).
Each conversion of a system of source code to prototyped format
consists of two major steps. First, there is an information gathering
step. In this step, all of the source files that make up a given
executable program are recompiled using the GNU C compiler and using
the -fgen-aux-info option. These recompilations will be performed
automatically by protoize on an as needed basis.
As individual compilation steps are performed, you may notice that a
side-effect of these compilations is to create files with a .X suffix
in the same directory with the original base source files being
compiled. During compilation with -fgen-aux-info, one such .X file is
created for each base source file compiled. These files contain
information about function definitions and declarations and additional
coded information which can be used by protoize to convert your source
code automatically to prototyped format.
After a full set of .X files corresponding to all of the .c (i.e.
base source) files for an individual program have been created,
protoize performs the actual conversion step.
Execution of the protoize program causes your original source files to
be converted such that both their function declarations and their
function definitions are in prototyped format. After the conversion
of your system, you will be left with a set of similar (but converted)
source files with the same names as your original files.
Before it writes each converted file back to disk, protoize attempts
to rename the original file, giving it a .save suffix. It then
creates a new output file with the same name that the original file
had. This ensures that if there were any hard links to the original
input files, these will not be altered by the conversion process.
WARNING! If for any given original file, a save file already exists,
protoize will assume that the existing save file contains a backup of
- 2 - Formatted: January 15, 2025
PROTOIZE(1) PROTOIZE(1)
21 January 1990
the original file as it existed before any conversions were applied.
Thus, if there is an existing save file, protoize will not overwrite
this existing save file, and no new backup of that particular original
file will be made during that run of protoize.
An important safety feature of protoize is that it normally only tries
to convert files for which you have both read and write permissions.
Also, protoize will normally only convert files located in directories
that you have both search and write permissions for.
Another safety feature is that protoize will not normally convert
files which are located in system include directories. A system
include directory is defined by protoize as either /usr/include (or
any of its subdirectories) or a directory whose full absolute pathname
includes either gcc-include or g++-include.
Most of the above safety features can be overridden by using the -f
(force) option (see below), but even when -f is used, you cannot force
the conversion of files for which you do not at least have read
permission, or files in directories that you do not at least have
write permission for.
Note that protoize will make no attempt to convert definitions or
declarations of functions which accept a variable number of arguments
and which are written using the varargs conventions. All such
function definitions and declarations must be converted manually to
the stdarg conventions. Warnings are automatically issued for varargs
function definitions and declarations which are left unconverted by
protoize.
OPTIONS
Protoize recognizes the following options:
-V Version number. Causes the current version number to be printed
on stderr.
-q Quiet mode. Normally, protoize may issue many verbose warnings
concerning noteworthy conditions. These warnings can often be
helpful to the overall conversion effort. Users who prefer not
to see such messages can use the -q option which suppresses most
such warnings.
-f Force mode. Use of this option overrides the normal safety
features of protoize. It allows for attempts to convert system
include files, and files not writable by you. These conversions
are still subject to all normal file protections provided by the
operating system. This option should be used only with extreme
caution. It can be especially dangerous to use this option when
logged on as root. Note that when this option is used, you are
allowed to convert even files that you do not have write access
to. So long as you have write access to the containing
- 3 - Formatted: January 15, 2025
PROTOIZE(1) PROTOIZE(1)
21 January 1990
directory, conversion may occur.
-n No convert mode. Do not actually perform any conversions on base
source files or on include files. Rather, simply do all steps
leading up to conversion and then print a list (to stdout) of the
names of all files which would actually be modified if the
conversions were actually performed. This option may be useful
to you if you are converting a system of source files that you
are unfamiliar with. In such cases, you may need to verify ahead
of time that include files which belong to other people or to
other projects will not be modified by running protoize. Use of
this option also implicitly enables keep mode. (See the -k option
below.)
-k Keep mode. Normally, protoize reads the information in the .X
files created by the GNU C compiler, and then immediately deletes
these files (since they will no longer be valid or useful after
conversion). When the -k option is used however, the .X files
are not deleted during conversion.
-N No save mode. When this option is used, no attempt is made to
make backups of original files (by renaming them such that they
have an added .save suffix). Use this option with extreme
caution, and only when you have previously backed up all of the
files that might be converted by running protoize. (See the -n
option above.)
-c <cc opts>
Specify compile options. The -c option can be used as a means of
passing on important compilation options to the C compiler. It
may often be necessary to use this option to pass command line
preprocessor definitions on to the compilation step. Note that
The compile options must be given as a single argument to
protoize. If you have more than one compilation option, you will
have to quote the entire set of compilation options in order to
keep the shell from treating them as separate arguments to
protoize. Note also that certain options are automatically
suppressed by protoize and cannot be passed on to the compiler
(i.e. -g, -O, -c, -S, and -o are suppressed).
-C C++ conversion mode. Normally, protoize writes its (converted)
output files back to files of the same names as the original
(unconverted) input files. In C++ conversion mode, after each
output file is written, a check is made to see if the given
output file has a .c suffix. If it does, then the given file is
renamed, and its suffix is changed to .C. This makes the output
file acceptable as a C++ input file for either the GNU C++
compiler or for the Cfront translator.
- 4 - Formatted: January 15, 2025
PROTOIZE(1) PROTOIZE(1)
21 January 1990
-l Add explicit local declarations. This option causes protoize to
insert explicit declarations for functions that were only
implicitly declared in the original source code. When the -l
option is used, lists of additional new explicit function
declarations are inserted near the starts of blocks where
explicit function declarations took place. (See also the -g
option below.)
-g Add explicit global declarations. This option causes protoize to
insert explicit declarations for functions that were only
implicitly declared in your original source code. When the -g
option is used, a list of additional new explicit function
declarations is inserted just before the first function
definition in each individual source file that previously
contained implicit declarations. (See also the -l option above.)
-B <dir>
Alternate library directory option. Use this option to specify
that protoize should attempt to find the file SYSCALLS.c.X in the
alternate directory indicated in the option.
EXAMPLES
Assume that you have a directory with all of the files for your system
in it. Also assume that your system consists of two executable
programs, one built from the files s1.c, s2.c, and s3.c, and the other
built from the files s4.c and s5.c. Finally, assume that these source
files share some common include files.
In order to properly convert such a system of programs, you would need
to perform the steps shown below.
protoize s1.c s2.c s3.c
protoize s4.c s5.c
In the example above, the first invocation of protoize causes three .X
files (called s1.c.X, s2.c.X, and s3.c.X) to be created. These files
are generated automatically by protoize (which invokes the GNU C
compiler to create them). These files contain information about
function definitions and declarations both for their corresponding .c
files and for any files which are included by these base .c files.
After protoize has invoked the compiler for each of the files which
make up prog1, it performs the actual conversion of these base files
(and may perform some conversion of their include files depending upon
the information available in the .X files). Finally, after performing
all necessary conversions, protoize automatically deletes the files
s1.c.X, s2.c.X, and s3.c.X.
- 5 - Formatted: January 15, 2025
PROTOIZE(1) PROTOIZE(1)
21 January 1990
After performing the conversion for prog1, (as illustrated above) you
would then request protoize to convert all of the files which make up
prog2 in a similar fashion. This step would create two more .X files
(called s4.c.X and s5.c.X). As with the conversion of prog1, protoize
will automatically generate any needed .X files (by invoking the GNU C
compiler), will perform the conversion of all of the given base source
files (and possibly do some conversion on include files), and will
finish up by automatically deleting the .X files that were generated
during this run.
You may occasionally find that you need to convert a particular
program which consists of several base source files, some of which
must be compiled with unusual options. In such cases, you can still
convert the program via a special mechanism. For each base source
file which requires special compilation options, you can create a
corresponding .X file for the base file (before invoking protoize).
You would do this by invoking the GNU C compiler directly with the
required special options, and with the -fgen-aux-info option.
Protoize is smart enough to use existing .X files (when they are
available and when they are up to date) so creating .X files ahead of
time with the GNU C compiler is an easy way to accommodate unusual
compilation options for individual base files.
Note that protoize checks each preexisting .X file before it tries to
use it in order to insure that it is up-to-date with respect to all of
the source files that it contains information about. If this check
fails, protoize will automatically invoke the GNU C compiler (with
default options) to recreate the needed .X file.
CAVEATS
The protoize program doesn't just get information from your own .X
files. Every time protoize executes, it also reads a file
SYSCALLS.c.X from some standard installation directory (if it exists)
to obtain a pre-written set of function prototypes for various
standard system-supplied functions. These prototypes are effectively
added to the set of prototypes which protoize can use to perform
prototype substitutions on your source files. If the source code for
any individual programs that you are converting contains its own
definitions for functions with the same names as standard system-
supplied functions, protoize is intelligent enough to allow the
parameter typing from your own function definitions to take precedence
over the information contained in the SYSCALLS.c.X file.
Protoize changes (and possibly adds to) your original source code in
ways which may require you to rearrange the placement of other items
in your code. Specifically, it is often necessary to move around type
definitions or declarations for enum, struct, and union types.
Usage of protoize may cause source lines to grow quite long and
thereby become difficult to read and to edit. Fortunately, protoize
- 6 - Formatted: January 15, 2025
PROTOIZE(1) PROTOIZE(1)
21 January 1990
is intelligent enough to automatically break up very long lines
containing newly inserted function prototypes whenever the length of
any given output line would otherwise exceed 79 columns (including
tabs to standard UNIX tab stops).
Note that in traditional (K&R) C, it was not possible to declare
parameter types for function pointer parameters and variables. Such
function pointer variables could only be declared with empty parameter
lists in traditional C. Unfortunately, this means that protoize
typically has no adequate source of information from which to
manufacture appropriate (prototyped) formal argument lists for such
function pointer variables. Thus, declarations of function pointer
variables and parameters will not be properly converted by protoize.
In the case of function pointer variables, protoize currently
performs no conversion whatsoever. In the case of function pointer
parameters however, protoize will attempt to do half-hearted
conversions by manufacturing formal parameter lists for such
parameters. These manufactured formal parameter lists will look like
`...'.
It is naive to assume that the conversions performed by protoize are
sufficient to make your source code completely compatible with ANSI C
or C++. The automatic conversion of your source files via protoize is
only one step (albeit a big one) towards full conversion. A full
conversion may also require lots of editing "by hand".
Protoize only converts function declarations and definitions. No
conversion of types (such as function types and pointer-to-function
types) contained in typedef statements is attempted. These must be
converted manually.
When converting to full prototype format, it may often be the case
that complete information regarding the types of function parameters
is not actually available in the original (K&R) code. This will
almost always be the case for parameters whose types are pointer-to-
function types. For pointer-to-function parameters, it it customary
(in K&R C) to omit the types of the arguments which the pointed-to
function expects to receive. In cases where the argument types for
function pointer parameters are not present in the original source
code, protoize notes this lack of complete information in a useful
(but harmless) way. After conversion, the (prototyped) parameter
lists for pointer-to-function parameters are represented in the
converted files as comments which contain the string "???". You can
easily locate all such strings after conversion (using your favorite
editor) and replace them with more complete information regarding the
true parameter profile of the pointed-to functions.
- 7 - Formatted: January 15, 2025
PROTOIZE(1) PROTOIZE(1)
21 January 1990
WARNINGS
There are numerous possible warning and error messages which protoize
may issue for strange circumstances (e.g. missing input files, etc.)
or for noteworthy conditions in the source code being converted.
These should all be self-explanatory. If any message is not self-
explanatory, it's a bug. Please report it.
FILES
/usr/local/bin/gcc GNU C compiler
/usr/local/bin/protoize the protoize program
/usr/local/lib/SYSCALLS.c.X aux info file for system functions
SEE ALSO
gcc(1), g++(1), unprotoize(1)
BUGS
Protoize can easily be confused by source code which has macro calls
in the vicinity of something which it has to convert. Fortunately,
such cases seem to be rare in practice. This is an inherent problem
with the compiler based approach to information gathering and will
likely never be fixed. When it does become confused, protoize will
still proceed to convert the file it is working on as much as
possible. Only the particularly confusing function definitions and
declarations will fail to be converted. These can subsequently be
converted manually.
Due to the method currently used to gather information, protoize will
fail to convert function declarations and definitions which are
located in conditional compilation sections which were preprocessed
out during the creation of the .X files used for conversion. You can
generally work around this problem by doing repeated conversion steps
using protoize, each with a different set of compilation options
(i.e. preprocessor symbol definitions) but assuring complete
conversion can currently only be done by visual inspection.
Currently, protoize attempts to find function definitions which were
preprocessed out and to issues warnings for such cases. A later
revision of protoize may also be able to detect cases where function
declarations have been preprocessed out and to issue appropriate
warnings for those cases also.
Currently, protoize makes no attempt to convert declarations of
pointer to function types, variables, or fields.
- 8 - Formatted: January 15, 2025
PROTOIZE(1) PROTOIZE(1)
21 January 1990
Currently, varargs functions definitions and declarations must be
converted by hand to use the stdarg convention. It is possible that a
subsequent version of protoize will make some attempt to do these
conversions automatically.
Protoize may get confused if it finds that it has 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.
Bugs (and requests for reasonable enhancements) should be reported to
bug-gcc@prep.ai.mit.edu. Bugs may actually be fixed if they can be
easily reproduced, so it is in your interest to report them in such a
way that reproduction is easy.
COPYING
Copyright (c) 1989, 1990 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.
AUTHORS
Written by Ronald F. Guilmette at the Microelectronics and Computer
Technology Corporation (MCC). Generously donated by MCC to the Free
Software Foundation.
See the GNU C Compiler Manual for a list of contributors to GNU C.
- 9 - Formatted: January 15, 2025
