protoize - Unix, Linux Command

---

---

NAME

protoize, unprotoize - automatically add or remove function prototypes

SYNOPSIS

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 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:

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

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 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.)

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.