add directory gnu
This commit is contained in:
gohigh
904
gnu/gcc/gcc-2.2.2/proto-man
Normal file
904
gnu/gcc/gcc-2.2.2/proto-man
Normal file
@@ -0,0 +1,904 @@
|
||||
#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.
|
||||
Reference in New Issue
Block a user