905 lines
26 KiB
Plaintext
905 lines
26 KiB
Plaintext
#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.
|