diff options
Diffstat (limited to 'gnu/egcs')
| -rw-r--r-- | gnu/egcs/gcc/protoize.1 | 320 |
1 files changed, 175 insertions, 145 deletions
diff --git a/gnu/egcs/gcc/protoize.1 b/gnu/egcs/gcc/protoize.1 index fd17482a691..eb59eca8177 100644 --- a/gnu/egcs/gcc/protoize.1 +++ b/gnu/egcs/gcc/protoize.1 @@ -1,9 +1,9 @@ .\" Copyright (c) 1991, 1992, 1993, 1994 Free Software Foundation .\" See section COPYING for conditions for redistribution .\" -.\" $OpenBSD: protoize.1,v 1.2 2003/03/18 13:14:02 david Exp $ +.\" $OpenBSD: protoize.1,v 1.3 2003/09/03 14:27:12 jmc Exp $ .Dd January 14, 2003 -.Dt PROTOIZE 1 +.Dt PROTOIZE 1 .Os .Sh NAME .Nm protoize, unprotoize @@ -17,7 +17,7 @@ .Op Fl d Ar directory ... .Op Fl i Ar string .Op Fl p Ar program -.Op Fl x Ar +.Op Fl x Ar .Ar .Ek .Nm unprotoize @@ -32,63 +32,65 @@ .Ek .Sh DESCRIPTION .Nm protoize -is an optional part of GNU C. You can use it -to add prototypes to a program, thus converting the program to ANSI C -in one respect. The companion program +is an optional part of GNU C. +You can use it to add prototypes to a program, +thus converting the program to ANSI C in one respect. +The companion program .Nm unprotoize -does the reverse: it removes argument types from any -prototypes that are found. +does the reverse: it removes argument types from any prototypes that are found. .Pp 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 -.Ar FOO +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 +.Ar FOO is saved in a file named .Ar FOO.X . .Pp -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. +After scanning comes the actual conversion. +The specified files are all eligible to be converted; +any files they include +.Pq whether sources or just headers +are eligible as well. .Pp -But not all the eligible files are converted. By default, +But not all the eligible files are converted. +By default, .Nm protoize and .Nm unprotoize -convert only source and header files in the -current directory. You can specify additional directories whose files -should be converted with the +convert only source and header files in the current directory. +You can specify additional directories whose files +should be converted with the .Sq Fl d Ar directory ... -option. You can also -specify particular files to exclude with the +option. +You can also specify particular files to exclude with the .Sq Fl x Ar -option. A file -is converted if it is eligible, its directory name matches one of the +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. .Pp Basic conversion with .Nm 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. +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. .Pp .Nm 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. +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. .Pp Basic conversion with .Nm unprotoize -consists of rewriting most -function declarations to remove any argument types, and rewriting -function definitions to the old-style pre-ANSI form. +consists of rewriting most function declarations to remove any argument types, +and rewriting function definitions to the old-style pre-ANSI form. .Pp Both conversion programs print a warning for any function -declaration or definition that they can't convert. You can suppress -these warnings with the +declaration or definition that they can't convert. +You can suppress these warnings with the .Fl q option. .Pp @@ -96,56 +98,64 @@ The output from .Nm protoize or .Nm 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. +replaces the original source file. +The original file is renamed to a name ending with +.Sq .save . +If the +.Sq .save +file already exists, then the source file is simply discarded. .Pp .Nm protoize and .Nm unprotoize both depend on .Xr gcc 1 -to scan the -program and collect information about the functions it uses. +to scan the program and collect information about the functions it uses. .Pp The options are as follows: .Bl -tag -width Ds .It Fl B Ar directory -Look for the file `SYSCALLS.c.X' in +Look for the file +.Sq SYSCALLS.c.X +in .Ar directory , -instead of the -usual directory +instead of the usual directory .Pq normally Pa /usr/local/lib . -This file contains -prototype information about standard system functions. This option -applies only to +This file contains prototype information about standard system functions. +This option applies only to .Nm protoize . .It Fl C -Rename files to end in `.C' instead of `.c'. This is convenient -if you are converting a C program to C++. This option applies -only to +Rename files to end in +.Sq .C +instead of +.Sq \&.c . +This is convenient if you are converting a C program to C++. +This option applies only to .Nm protoize . .It Fl c Ar COMPILATION-OPTIONS Use .Ar COMPILATION-OPTIONS -as the options when running `gcc' to -produce the `.X' files. The special option +as the options when running +.Xr gcc 1 +to produce the +.Sq .X +files. +The special option .Fl aux-info -is always -passed in addition, to tell `gcc' to write a `.X' file. +is always passed in addition, to tell gcc to write a +.Sq .X +file. .Pp -Note that the compilation options must be given as a single -argument to +Note that the compilation options must be given as a single argument to .Nm protoize or .Nm unprotoize . -If you want to specify -several `gcc' options, you must quote the entire set of +If you want to specify several gcc options, you must quote the entire set of compilation options to make them a single word in the shell. .Pp -There are certain `gcc' arguments that you cannot use, because they -would produce the wrong kind of output. These include +There are certain gcc arguments that you cannot use, because they +would produce the wrong kind of output. +These include .Fl g , .Fl O , .Fl c , @@ -158,11 +168,12 @@ they are ignored. .It Fl d Ar directory Specify additional directories whose files should be converted. .It Fl g -Add explicit global declarations. This means inserting explicit -declarations at the beginning of each source file for each function -that is called in the file and was not declared. These -declarations precede the first function definition that contains a -call to an undeclared function. This option applies only to +Add explicit global declarations. +This means inserting explicit declarations at the beginning of each +source file for each function that is called in the file and was not declared. +These declarations precede the first function definition that contains a +call to an undeclared function. +This option applies only to .Nm protoize . .It Fl i Ar string Indent old-style parameter declarations with the string @@ -173,89 +184,104 @@ This option applies only to .Nm unprotoize converts prototyped function definitions to old-style function definitions, where the arguments are declared between the -argument list and the initial `{'. By default, +argument list and the initial +.Sq { . +By default, .Nm unprotoize -uses -five spaces as the indentation. If you want to indent with just -one space instead, use +uses five spaces as the indentation. +If you want to indent with just one space instead, use .Fl i -" ". +.Sq \ \& . .It Fl k -Keep the `.X' files. Normally, they are deleted after conversion -is finished. +Keep the +.Sq .X +files. +Normally, they are deleted after conversion is finished. .It Fl l Add explicit local declarations. .Nm protoize with .Fl l -inserts a -prototype declaration for each function in each block which calls -the function without any declaration. This option applies only to +inserts a prototype declaration for each function in each block which calls +the function without any declaration. +This option applies only to .Nm protoize . .It Fl N -Make no `.save' files. The original files are simply deleted. +Make no +.Sq .save +files. +The original files are simply deleted. Use this option with caution. .It Fl n -Make no real changes. This mode just prints information about the -conversions that would have been done without +Make no real changes. +This mode just prints information about the conversions +that would have been done without .Fl n . .It Fl p Ar program Use the program .Ar program -as the compiler. Normally, the name `gcc' is used. +as the compiler. +Normally, the name +.Sq gcc +is used. .It Fl q -Work quietly. Most warnings are suppressed. +Work quietly. +Most warnings are suppressed. .It Fl v Print the version number, just like .Fl v -for `gcc'. +for gcc. .It Fl x Ar List of files to exclude from the conversion process. .El .Pp 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 +source files, then you should generate that file's +.Sq .X +file specially, by running gcc on that source file with +the appropriate options and the option .Fl aux-info . Then run .Nm protoize -on the entire set of -files. +on the entire set of files. .Nm protoize -will use the existing `.X' file because it is newer -than the source file. For example: +will use the existing +.Sq .X +file because it is newer than the source file. +For example: .Pp -.Cm $ gcc -Dfoo=bar file1.c -aux-info -.br -.Cm $ protoize *.c +.Dl $ gcc -Dfoo=bar file1.c -aux-info +.Dl $ protoize *.c .Pp You need to include the special files along with the rest in the .Nm protoize -command, even though their `.X' files already exist, because -otherwise they won't get converted. -.Pp -.Sy "Note: most of this information is out of date and superseded by the" -.Sy "EGCS install procedures. It is provided for historical reference only." +command, even though their +.Sq .X +files already exist, because otherwise they won't get converted. +.Pp +.Bf -symbolic +Note: most of this information is out of date and superseded by the +EGCS install procedures. +It is provided for historical reference only. +.Ef .Sh SEE ALSO -.Xr gcc 1 -.Sh AUTHORS -See the GNU CC manual for the contributors to GNU CC. +.Xr gcc 1 , +.Xr gcc-local 1 .Sh HISTORY Ron Guilmette implemented the .Nm protoize and .Nm unprotoize tools. -.Sh BUGS -For instructions on reporting bugs, see the GCC manual. +.Sh AUTHORS +See the GNU CC manual for the contributors to GNU CC. .Sh CAVEATS The conversion programs .Nm protoize and .Nm unprotoize -can sometimes -change a source file in a way that won't work unless you rearrange it. +can sometimes change a source file in a way that won't work +unless you rearrange it. .Pp .Nm protoize can insert references to a type name or type tag before @@ -270,20 +296,21 @@ cannot figure out. For example, it can't determine argument types for declaring a pointer-to-function variable; this must be done by hand. .Nm 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 +inserts a comment containing +.Sq ??? +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. .Pp Using .Nm 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. +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 .Nm unprotoize -is safe is when you -are removing prototypes that were made with +is safe is when you are removing prototypes that were made with .Nm protoize ; if the program worked before without any prototypes, it will work again @@ -291,47 +318,47 @@ without them. .Pp You can find all the places where this problem might occur by compiling the program with the -.Fl Ar Wconversion -option. It prints a -warning whenever an argument is converted. +.Fl Wconversion +option. +It prints a warning whenever an argument is converted. .Pp 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. +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. .Pp .Nm protoize -cannot get the argument types for a function whose -definition was not actually compiled due to preprocessing -conditionals. When this happens, +cannot get the argument types for a function whose definition was not +actually compiled due to preprocessing conditionals. +When this happens, .Nm protoize -changes nothing in -regard to such a function. +changes nothing in regard to such a function. .Nm protoize -tries to detect such -instances and warn about them. +tries to detect such instances and warn about them. .Pp You can generally work around this problem by using .Nm protoize -step -by step, each time specifying a different set of +step by step, each time specifying a different set of .Fl 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. +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. .Pp 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. -.Pp -If you plan on converting source files which contain such code, it -is recommended that you first make sure that each conditionally +is more than one formal parameter list present. +Thus, attempts to convert code containing multiple +.Pq conditionally compiled +versions of a single function header +.Pq in the same vicinity +may not produce the desired +.Pq or expected +results. +.Pp +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). @@ -341,12 +368,15 @@ This should circumvent the problem. 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. +function being defined or declared. +We recommand you avoid such choices of formal parameter names. .Pp -It might ne 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.) +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.) +.Sh BUGS +For instructions on reporting bugs, see the GCC manual. .Sh COPYING Copyright 1991, 1992, 1993 Free Software Foundation, Inc. .Pp |