Education Sampler 1992 [NeXTSTEP]/Education_1992_Sampler.iso/NeXT/GnuSource/cc-61.0.1/cc/proto-unproto.1

Text File | 1991-05-30 | 27KB | 902 lines

#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.
.\"
.\"     Written by Ron Guilmette ([e-mail]).
.\"
.\"     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 above 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 avaiable 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
[e-mail].  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.