1protoize(1) GNU protoize(1)
2
6 protoize, unprotoize - automatically add or remove function prototypes
7
9 protoize [-CfgklNnqv] [-B DIRECTORY] [-c COMPILATION-OPTIONS] [-d
10 DIRECTORY] [-i STRING] [-p PROGRAM] [-x FILE] [FILE...]
11 unprotoize [-fkNnqv] [-c COMPILATION-OPTIONS] [-d DIRECTORY] [-i
13 STRING] [-p PROGRAM] [-x FILE] [FILE...]
14
16 protoize is an optional part of GCC. You can use it to add prototypes
17 to a program, thus converting the program to ANSI C in one respect.
18 The companion program unprotoize does the reverse: it removes argument
19 types from any prototypes that are found.
20 When you run these programs, you must specify a set of source files as
22 command line arguments. The conversion programs start out by compiling
23 these files to see what functions they define. The information gath‐
24 ered about a file FOO is saved in a file named FOO.X.
25 After scanning comes the actual conversion. The specified files are
27 all eligible to be converted; any files they include (whether sources
28 or just headers) are eligible as well.
29 But not all the eligible files are converted. By default, protoize and
31 unprotoize convert only source and header files in the current direc‐
32 tory. You can specify additional directories whose files should be
33 converted with the -d DIRECTORY option. You can also specify particu‐
34 lar files to exclude with the -x FILE option. A file is converted if
35 it is eligible, its directory name matches one of the specified direc‐
36 tory names, and its name within the directory has not been excluded.
37 Basic conversion with protoize consists of rewriting most function def‐
39 initions and function declarations to specify the types of the argu‐
40 ments. The only ones not rewritten are those for varargs functions.
41 protoize optionally inserts prototype declarations at the beginning of
43 the source file, to make them available for any calls that precede the
44 function's definition. Or it can insert prototype declarations with
45 block scope in the blocks where undeclared functions are called.
46 Basic conversion with unprotoize consists of rewriting most function
48 declarations to remove any argument types, and rewriting function defi‐
49 nitions to the old-style pre-ANSI form.
50 Both conversion programs print a warning for any function declaration
52 or definition that they can't convert. You can suppress these warnings
53 with the -q option.
54 The output from protoize or unprotoize replaces the original source
56 file. The original file is renamed to a name ending with .save. If
57 the .save file already exists, then the source file is simply dis‐
58 carded.
59 protoize and unprotoize both depend on gcc(1) to scan the program and
61 collect information about the functions it uses.
62 The options are as follows:
64 -B DIRECTORY
66 Look for the file SYSCALLS.c.X in directory, instead of the
67 usual directory (normally /usr/local/lib). This file contains
68 prototype information about standard system functions. This
69 option applies only to protoize.
70 -C Rename files to end in .C instead of .c. This is convenient if
72 you are converting a C program to C++. This option applies only
73 to protoize.
74 -c COMPILATION-OPTIONS
76 Use COMPILATION-OPTIONS as the options when running gcc(1) to
77 produce the .X files. The special option -aux-info is always
78 passed in addition, to tell gcc to write a .X file. Note that
79 the compilation options must be given as a single argument to
80 protoize or unprotoize. If you want to specify several gcc
81 options, you must quote the entire set of compilation options to
82 make them a single word in the shell. There are certain gcc
83 arguments that you cannot use, because they would produce the
84 wrong kind of output. These include -g, -O, -c, -S,-o. If you
85 include these in the COMPILATION-OPTIONS, they are ignored.
86 -d DIRECTORY
88 Specify additional directories whose files should be converted.
89 -g Add explicit global declarations. This means inserting explicit
91 declarations at the beginning of each source file for each func‐
92 tion that is called in the file and was not declared. These
93 declarations precede the first function definition that contains
94 a call to an undeclared function. This option applies only to
95 -i STRING
97 Indent old-style parameter declarations with the string STRING.
98 This option applies only to protoize. unprotoize converts pro‐
99 totyped function definitions to old-style function definitions,
100 where the arguments are declared between the argument list and
101 the initial {. By default, unprotoize uses five spaces as the
102 indentation. If you want to indent with just one space instead,
103 use -i " ".
104 -k Keep the .X files. Normally, they are deleted after conversion
106 is finished.
107 -l Add explicit local declarations. protoize with -l inserts a
109 prototype declaration for each function in each block which
110 calls the function without any declaration. This option applies
111 only to protoize.
112 -N Make no .save files. The original files are simply deleted.
114 Use this option with caution.
115 -n Make no real changes. This mode just prints information about
117 the conversions that would have been done without -n.
118 -p PROGRAM
120 Use the program PROGRAM as the compiler. Normally, the name gcc
121 is used.
122 -q Work quietly. Most warnings are suppressed.
124 -v Print the version number, just like -v for gcc.
126 -x FILE
128 List of files to exclude from the conversion process.
129 If you need special compiler options to compile one of your program's
131 source files, then you should generate that file's .X file specially,
132 by running gcc on that source file with the appropriate options and the
133 option -aux-info. Then run protoize on the entire set of files. pro‐
134 toize will use the existing .X file because it is newer than the source
135 file. For example:
136 You need to include the special files along with the rest in the pro‐
138 toize command, even though their .X files already exist, because other‐
139 wise they won't get converted.
140
142 gcc(1), and the Info entry for gcc, particularly Running protoize sec‐
143 tion.
144
146 Ron Guilmette implemented the protoize and unprotoize tools.
147
149 See the GCC manual for the contributors to GCC.
150
152 The conversion programs protoize and unprotoize can sometimes change a
153 source file in a way that won't work unless you rearrange it.
154 protoize can insert references to a type name or type tag before the
156 definition, or in a file where they are not defined.
157 If this happens, compiler error messages should indicate where the new
159 references are, so fixing the file by hand is straightforward.
160 There are some C constructs which protoize cannot figure out. For
162 example, it can't determine argument types for declaring a pointer-to-
163 function variable; this must be done by hand. protoize inserts a com‐
164 ment containing ??? each time it finds such a variable; all such vari‐
165 ables can be found by searching for this string. ANSI C does not
166 require declaring the argument types of pointer-to-function types.
167 Using unprotoize can easily introduce bugs. If the program relied on
169 prototypes to bring about conversion of arguments, these conversions
170 will not take place in the program without prototypes. One case in
171 which you can be sure unprotoize is safe is when you are removing pro‐
172 totypes that were made with protoize; if the program worked before
173 without any prototypes, it will work again without them.
174 You can find all the places where this problem might occur by compiling
176 the program with the -Wconversion option. It prints a warning whenever
177 an argument is converted.
178 Both conversion programs can be confused if there are macro calls in
180 and around the text to be converted. In other words, the standard syn‐
181 tax for a declaration or definition must not result from expanding a
182 macro. This problem is inherent in the design of C and cannot be
183 fixed. If only a few functions have confusing macro calls, you can
184 easily convert them manually.
185 protoize cannot get the argument types for a function whose definition
187 was not actually compiled due to preprocessing conditionals. When this
188 happens, protoize changes nothing in regard to such a function. pro‐
189 toize tries to detect such instances and warn about them.
190 You can generally work around this problem by using protoize step by
192 step, each time specifying a different set of -D options for compila‐
193 tion, until all of the functions have been converted. There is no
194 automatic way to verify that you have got them all, however.
195 Confusion may result if there is an occasion to convert a function dec‐
197 laration or definition in a region of source code where there is more
198 than one formal parameter list present. Thus, attempts to convert code
199 containing multiple (conditionally compiled) versions of a single func‐
200 tion header (in the same vicinity) may not produce the desired (or
201 expected) results.
202 If you plan on converting source files which contain such code, it is
204 recommended that you first make sure that each conditionally compiled
205 region of source code which contains an alternative function header
206 also contains at least one additional follower token (past the final
207 right parenthesis of the function header). This should circumvent the
208 problem.
209 unprotoize can become confused when trying to convert a function defi‐
211 nition or declaration which contains a declaration for a pointer-to-
212 function formal argument which has the same name as the function being
213 defined or declared. We recommand you avoid such choices of formal
214 parameter names.
215 It might be necessary to correct some of the indentation by hand and
217 break long lines. (The conversion programs don't write lines longer
218 than eighty characters in any case.)
219
221 For instructions on reporting bugs, see the GCC manual.
222
224 Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
225 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
226 Permission is granted to make and distribute verbatim copies of this
228 manual provided the copyright notice and this permission notice are
229 preserved on all copies.
230 Permission is granted to copy and distribute modified versions of this
232 manual under the conditions for verbatim copying, provided that the
233 entire resulting derived work is distributed under the terms of a per‐
234 mission notice identical to this one.
235 Permission is granted to copy and distribute translations of this man‐
237 ual into another language, under the above conditions for modified ver‐
238 sions, except that this permission notice may be included in transla‐
239 tions approved by the Free Software Foundation instead of in the origi‐
240 nal English.
241GCC 8 December 2006 protoize(1)