diff options
Diffstat (limited to 'gcc/proto-man')
| -rwxr-xr-x | gcc/proto-man | 904 |
1 files changed, 0 insertions, 904 deletions
diff --git a/gcc/proto-man b/gcc/proto-man deleted file mode 100755 index bd1a3e2..0000000 --- a/gcc/proto-man +++ /dev/null @@ -1,904 +0,0 @@ -#ifndef UNPRO -#define THISPROG PROTOIZE -#define thisprog protoize -#define Thisprog Protoize -#define otherprog unprotoize -#define from_convention varargs -#define to_convention stdarg -#else -#define THISPROG UNPROTOIZE -#define thisprog unprotoize -#define Thisprog Unprotoize -#define otherprog protoize -#define from_convention stdarg -#define to_convention varargs -#endif -.\" Man page file for the thisprog program. -.\" This is badly out of date, especially concerning -.\" the way of deciding which files to convert. -.\" Really all this information should be updated and put in gcc.texinfo. -.\" -.\" Written by Ron Guilmette (rfg@mcc.com). -.\" -.\" Copyright (C) 1989, 1990 Free Software Foundation, Inc. -.\" -.\" This file is part of GNU CC. -.\" -.\" GNU CC is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License as published by -.\" the Free Software Foundation; either version 1, or (at your option) -.\" any later version. -.\" -.\" GNU CC is distributed in the hope that it will be useful, -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" along with GNU CC; see the file COPYING. If not, write to -.\" the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. -.\" -.TH THISPROG 1 "21 January 1990" "" -.SH NAME -#ifndef UNPRO -thisprog \- convert K&R C source code to ANSI C prototype format -#else -thisprog \- convert ANSI C source code to K&R C (unprototyped) format -#endif -.SH SYNOPSIS -.B thisprog -[ -#ifndef UNPRO -.B -VqfnkNlgC -] [ -.B -B -.I <dir> -#else -.B -VqfnkN -] [ -.B -i -.I <str> -#endif -] [ -.B -c -.I <cc opts> -] [ -.I file\c -\&... ] -.SH DESCRIPTION -.fi -.ad b -.I Thisprog -aids in the conversion of -#ifndef UNPRO -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++. -#else -ANSI C source code files to K&R C source code files without function prototypes -. -This conversion is useful for porting ANSI C programs to -machines for which no ANSI C compiler is available. -#endif -.PP -.I Thisprog -is designed to be used in conjunction -with the GNU C compiler. The GNU C compiler does preliminary -.I "information gathering" -about functions by analyzing the files to be converted. -The GNU C compiler may be invoked automatically as a result of -running -.I thisprog -so it is important to have it properly installed before attempting -to convert source files via -.I thisprog. -#ifndef UNPRO -.PP -.I Thisprog -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 -.I implicit -function declarations), -.I thisprog -can be instructed to -insert new prototype style function declarations -into the source code. -For implicit function declarations, -.I thisprog -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 thisprog) assures that -.B all -function calls in your source files will be -checked for the correct -number and types of parameters -during subsequent compilations. -#endif -.PP -.I Thisprog -supports the conversion of both large and small systems of C source -code to -#ifndef UNPRO -prototype -#else -unprototyped -#endif -form. -.I Thisprog -can perform the conversion of an -entire program in one (batch) step. -#ifndef UNPRO -.PP -.I Thisprog -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). -#endif -.PP -Each conversion of a system of source code to -#ifndef UNPRO -prototyped -#else -unprototyped -#endif -format consists of two major steps. First, there is an -.I "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 -.B -fgen-aux-info -option. -These recompilations will be performed automatically by -.I thisprog -on an -.I as needed -basis. -.PP -As individual compilation steps are performed, you may notice -that a side-effect of these compilations is to create files with a -.B .X -suffix in the same directory with the original -.I base -source files being compiled. -During compilation with -.B -fgen-aux-info, -one such -.B .X -file is created for -each -.I base -source file compiled. These files contain -information about function definitions and declarations and -additional coded information which can be used by -.I thisprog -to convert your source code -automatically to -#ifndef UNPRO -prototyped -#else -unprototyped -#endif -format. -.PP -After a full set of -.B .X -files corresponding to all of the -.B .c -(i.e. -.I base -source) files for an individual -program -have been created, -.I thisprog -performs the actual conversion step. -.PP -Execution of the -.I thisprog -program causes your original source files to be converted such that both -their function declarations and their function definitions are in -#ifndef UNPRO -prototyped -#else -unprototyped -#endif -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. -.PP -Before it writes each converted file back to disk, -.I thisprog -attempts to rename the original file, giving it a -.B .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. -.PP -WARNING! If for any given original file, a save file already exists, -.I thisprog -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, -.I thisprog -will not overwrite this existing save file, and no new backup of -that particular original file will be made during that run of -.I thisprog. -.PP -An important safety feature of -.I thisprog -is that it normally only tries to convert files for which you have both -read and write permissions. Also, -.I thisprog -will normally only convert files located in directories that you -have both search and write permissions for. -.PP -Another safety feature is that -.I thisprog -will not normally convert files which -are located in -.I system -include directories. -A -.I system -include directory is defined by -.I thisprog -as either -.B /usr/include -(or any of its subdirectories) -or a directory whose full absolute pathname includes -either -.B gcc-include -or -.B g++-include. -.PP -Most of the above safety features can be overridden by using the -.B \-f -(force) option (see below), -but even when -.B \-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. -.PP -Note that -.I thisprog -will make no attempt to convert definitions -#ifndef UNPRO -or declarations -#endif -of functions which accept a variable number of arguments -and which are written using the -.I from_convention -conventions. -All such function definitions -#ifndef UNPRO -and declarations -#endif -must be converted manually to the -.I to_convention -conventions. -Warnings are automatically issued for -.I from_convention -function definitions -#ifndef UNPRO -and declarations -#endif -which are left unconverted by -.I thisprog. -.SH OPTIONS -.I Thisprog -recognizes the following options: -.TP -.B \-V -Version number. Causes the current version number to be -printed on stderr. -.TP -.B \-q -Quiet mode. -Normally, -.I thisprog -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 -.B \-q -option which suppresses most such warnings. -.TP -.B \-f -Force mode. -Use of this option overrides the normal safety -features of -.I thisprog. -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 -.I 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. -.TP -.B \-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 -.I thisprog. -Use of this option also implicitly enables -.I keep mode. -(See the -.B \-k -option below.) -.TP -.B \-k -Keep mode. Normally, -.I thisprog -reads the information in the -.B .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 -.B \-k -option is used however, the -.B .X -files are not deleted during conversion. -.TP -.B -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 -.B .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 -.I thisprog. -(See the -.B -n -option above.) -.TP -.B \-c <cc opts> -Specify compile options. The -.B \-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 -.I thisprog. -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 -.I thisprog. -Note also that certain options are automatically suppressed by -.I thisprog -and cannot be passed on to the compiler (i.e. -.B "-g, -O, -c, -S," -and -.B "-o" -are suppressed). -#ifndef UNPRO -.TP -.B \-C -C++ conversion mode. -Normally, -.I thisprog -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 -.B .c -suffix. If it does, then the given file is renamed, and its suffix -is changed to -.B .C. -This makes the output file -acceptable as a C++ input file for either the GNU C++ compiler or -for the Cfront translator. -.TP -.B \-l -Add explicit local declarations. This option causes -.I thisprog -to insert -explicit declarations for functions that were only implicitly declared -in the original source code. When the -.B \-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 -.B \-g -option below.) -.TP -.B \-g -Add explicit global declarations. This option causes -.I thisprog -to insert -explicit declarations for functions that were only implicitly declared -in your original source code. When the -.B \-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 -.B \-l -option above.) -.TP -.B \-B <dir> -Alternate library directory option. Use this option to specify that -.I thisprog -should attempt to find the file -.B SYSCALLS.c.X -in the alternate directory indicated in the option. -#else -.TP -.B \-i <str> -Indent string option. -This option can be used to specify a string to use when indenting -lines containing declarations for formal parameter variables. -The default indentation string for such lines is a sequence of five spaces -(i.e.\ GNU style indentation) but you may use this option to specify -any other string that you like (e.g.\ a tab character). -Note that -the shell has its own interpretations for blanks and tabs, so you -will generally have to quotes the argument given in the -.B -i -option. -#endif -.SH 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 -.B s1.c, s2.c, -and -.B s3.c, -and the other built from the files -.B s4.c -and -.B s5.c. -Finally, assume that these source files share some common include files. -.PP -In order to properly convert such a system of programs, you -would need to perform the steps shown below. -.sp 1 -.in +0.5i -.ft B -thisprog s1.c s2.c s3.c -.br -thisprog s4.c s5.c -.sp 1 -.ft R -.in -0.5i -.PP -In the example above, the first invocation of -.I thisprog -causes three -.B .X -files (called -.B s1.c.X, s2.c.X, -and -.B s3.c.X) -to be created. -These files are generated automatically by -.I thisprog -(which invokes the GNU C compiler to create them). -These files contain information about function definitions and declarations -.I both -for their corresponding -.B .c -files and for any files -which are included by these -.I base -.B .c -files. -.PP -After -.I thisprog -has invoked the compiler for each of the files which make up -.I 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 -.B .X -files). -Finally, after performing all necessary conversions, -.I thisprog -automatically deletes the files -.B s1.c.X, s2.c.X, -and -.B s3.c.X. -.PP -After performing the conversion for -.I prog1, -(as illustrated above) -you would then -request -.I thisprog -to convert all of the files which make up -.I prog2 -in a similar fashion. -This step would create two more -.B .X -files (called -.B s4.c.X -and -.B s5.c.X). -As with the conversion of -.I prog1, -.I thisprog -will automatically generate any needed -.B .X -files (by invoking the GNU C compiler), -will perform the conversion of all of the given -.I base -source files (and possibly do some conversion on include files), -and will finish up by -automatically deleting the -.B .X -files that were generated during this run. -.PP -You may occasionally find that you need to convert a -particular program which -consists of several -.I 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 -.I base -source file which requires special compilation options, -you can create a corresponding -.B .X -file for the -.I base -file -.I (before -invoking -.I thisprog). -You would do this by invoking the GNU C compiler directly -with the required special options, and with the -.B -fgen-aux-info -option. -.I Thisprog -is smart enough to use existing -.B .X -files (when they are available and when they are up to date) so creating -.B .X -files ahead of time with the GNU C compiler -is an easy way to accommodate unusual compilation options for individual -.I base -files. -.PP -Note that -.I thisprog -checks each preexisting -.B .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, -.I thisprog -will automatically -invoke the GNU C compiler (with default options) to recreate the needed -.B .X file. -.SH CAVEATS -#ifndef UNPRO -The -.I thisprog -program doesn\'t just get information from your own -.B .X -files. Every time -.I thisprog -executes, it also reads a file -.B 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 -.I thisprog -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, -.I thisprog -is intelligent enough to allow the parameter typing from your own -function definitions to take precedence over the information -contained in the -.B SYSCALLS.c.X -file. -.PP -.I Thisprog -changes -#ifndef UNPRO -(and possibly adds to) -#endif -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 -.B "enum, struct," -and -.B union -types. -#ifndef UNPRO -.PP -Usage of -.I thisprog -may cause source lines to grow quite long and thereby become difficult -to read and to edit. Fortunately, -.I thisprog -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). -.PP -Note that in traditional (K&R) C, it was not possible to declare -parameter types for -.B "function pointer" -parameters and variables. -Such function pointer variables could only be -declared with empty parameter lists in traditional C. Unfortunately, -this means that -.I thisprog -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 -.I thisprog. -In the case of function pointer variables, -.I thisprog -currently performs no conversion whatsoever. -In the case of function pointer parameters however, -.I thisprog -will attempt to do half-hearted conversions by -manufacturing formal parameter lists for such parameters. -These manufactured formal parameter lists will look -like \`\.\.\.\'. -#endif -.PP -#endif -It is naive to assume that the conversions performed by -.I thisprog -are sufficient to make your source code completely compatible with -#ifndef UNPRO -ANSI C or C++. -#else -K&R C. -#endif -The automatic conversion of your source files via -.I thisprog -is only one step (albeit a big one) towards -full conversion. A full conversion may also require -lots of editing "by hand". -.PP -.I Thisprog -only converts function declarations and definitions. No conversion of -.I types -(such as function types and pointer-to-function types) -contained in -.B typedef -statements is attempted. These must be converted manually. -#ifdef UNPRO -.PP -Naive conversion of source code via -.I thisprog -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 -.I thisprog, -these implicit conversions will no longer take place within the function -calls which require them. -.PP -The only remedy for this problem (currently) is for users of -.I thisprog -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 -.B -Wconversion -option to GCC prior to conversion. The warnings produced by -.B -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 -.B -Wconversion -eliminated), conversion may be performed without any possibility of -generating code which is incorrect due to missed type conversions. -#else -.PP -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, -.I thisprog -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. -#endif -.SH WARNINGS -There are numerous possible warning and error messages which -.I thisprog -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. -.SH FILES -.ta 3.0i -/usr/local/bin/gcc GNU C compiler -.br -/usr/local/bin/thisprog the thisprog program -#ifndef UNPRO -.br -/usr/local/lib/SYSCALLS.c.X aux info file for system functions -#endif -.SH "SEE ALSO" -gcc(1), g++(1), otherprog(1) -.SH BUGS -.I Thisprog -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, -.I thisprog -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. -.PP -Due to the method currently used to gather information, -.I thisprog -will fail to convert function declarations and definitions which -are located in conditional compilation sections which were -.I "preprocessed out" -during the creation of the -.B .X -files used for conversion. -You can generally work around this problem by doing -repeated conversion steps using -.I thisprog, -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, -.I thisprog -attempts to find function definitions which were -.I "preprocessed out" -and to issues warnings for such cases. -A later revision of -.I thisprog -#ifndef UNPRO -may also be able to detect cases where function declarations -have been -.I "preprocessed out" -and to issue appropriate warnings for those cases also. -#else -may be able to convert both function declarations and function -definitions which have been -.I "preprocessed out." -#endif -.PP -Currently, -.I thisprog -makes no attempt to convert declarations of -.I "pointer to function" -types, variables, or fields. -#ifdef UNPRO -A later version of -.I thisprog -may attempt to perform conversions of these -declarative items also. -#endif -.PP -Currently, -.I from_convention -functions definitions -#ifndef UNPRO -and declarations -#endif -must be converted by hand to use the -.I to_convention -convention. -It is possible that a subsequent version of -.I thisprog -will make some attempt to do these conversions automatically. -.PP -.I Thisprog -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. -#ifdef UNPRO -.PP -.I Thisprog -can become confused when trying to convert a function -definition or declaration -which contains a declaration for a -.I 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. -#endif -.PP -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. -.SH COPYING -Copyright (c) 1989, 1990 Free Software Foundation, Inc. -.sp 1 -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. -.sp 1 -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. -.sp 1 -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. -.SH AUTHORS -Written by Ronald F.\ Guilmette at the Microelectronics and Computer Technology -Corporation (MCC). Generously donated by MCC to the Free Software -Foundation. -.sp 1 -See the GNU C Compiler Manual for a list of contributors to GNU C. |