|
|
|
Unprotoize 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 unprotoize so it is important to have it properly installed before attempting to convert source files via unprotoize.
Unprotoize supports the conversion of both large and small systems of C source code to unprototyped form. Unprotoize can perform the conversion of an entire program in one (batch) step.
Each conversion of a system of source code to unprototyped 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 unprotoize 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 unprotoize to convert your source code automatically to unprototyped 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, unprotoize performs the actual conversion step.
Execution of the unprotoize program causes your original source files to be converted such that both their function declarations and their function definitions are in unprototyped 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, unprotoize 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, unprotoize 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, unprotoize will not overwrite this existing save file, and no new backup of that particular original file will be made during that run of unprotoize.
An important safety feature of unprotoize is that it normally only tries to convert files for which you have both read and write permissions. Also, unprotoize will normally only convert files located in directories that you have both search and write permissions for.
Another safety feature is that unprotoize will not normally convert files which are located in system include directories. A system include directory is defined by unprotoize 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 unprotoize will make no attempt to convert definitions of functions which accept a variable number of arguments and which are written using the stdarg conventions. All such function definitions must be converted manually to the varargs conventions. Warnings are automatically issued for stdarg function definitions which are left unconverted by unprotoize.
In order to properly convert such a system of programs, you would need to perform the steps shown below.
unprotoize s1.c s2.c s3.c
unprotoize s4.c s5.c
In the example above, the first invocation of unprotoize causes three .X files (called s1.c.X, s2.c.X, and s3.c.X) to be created. These files are generated automatically by unprotoize (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 unprotoize 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, unprotoize 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 unprotoize 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, unprotoize 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 unprotoize). You would do this by invoking the GNU C compiler directly with the required special options, and with the -fgen-aux-info option. Unprotoize 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 unprotoize 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, unprotoize will automatically invoke the GNU C compiler (with default options) to recreate the needed .X file.
Unprotoize 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.
Naive conversion of source code via unprotoize may introduce bugs into the resulting (converted) code unless you are very careful. The reason for this is rather subtle. Basically, when a call is made to a prototyped function, the types of some of the parameter values in the call may be implicitly converted to the types of the corresponding formal parameters (as declared in the function prototype). These implicit conversions can (occasionally) involve changes of representation for the passed values (for instance from int to float). Unfortunately, once your code has been converted via unprotoize, these implicit conversions will no longer take place within the function calls which require them.
The only remedy for this problem (currently) is for users of unprotoize to make sure that explicit casts are inserted into calls which will force these type conversions to occur even in the absence of function prototypes. Users can determine the exact set of places where such explicit casts may be required by compiling all code to be converted using the -Wconversion option to GCC prior to conversion. The warnings produced by -Wconversion will indicate those places in the original source code where explicit casts must be inserted. Once these explicit casts have been manually inserted (and the warnings from -Wconversion eliminated), conversion may be performed without any possibility of generating code which is incorrect due to missed type conversions.
Due to the method currently used to gather information, unprotoize 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 unprotoize, 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, unprotoize attempts to find function definitions which were preprocessed out and to issues warnings for such cases. A later revision of unprotoize may be able to convert both function declarations and function definitions which have been preprocessed out.
Currently, unprotoize makes no attempt to convert declarations of pointer to function types, variables, or fields. A later version of unprotoize may attempt to perform conversions of these declarative items also.
Currently, stdarg functions definitions must be converted by hand to use the varargs convention. It is possible that a subsequent version of unprotoize will make some attempt to do these conversions automatically.
Unprotoize 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.
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. Such unfortunate choices of formal parameter names are discouraged.
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.
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.
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