protoize - convert K&R C source code to ANSI C prototype format

---

SYNOPSIS

DESCRIPTION

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

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

-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

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.

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

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

WARNINGS

FILES

SEE ALSO

BUGS

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.

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

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

See the GNU C Compiler Manual for a list of contributors to GNU C.

Created by unroff & hp-tools. © by Hans-Peter Bischof. All Rights Reserved (1997).

Last modified 21/April/97