add documentation (straight copy from egcs)

2 files changed, 399 insertions, 3 deletions

diff --git a/gnu/usr.bin/gcc/Makefile.bsd-wrapper b/gnu/usr.bin/gcc/Makefile.bsd-wrapper
index afc124df950..ee25cced936 100644
--- a/gnu/usr.bin/gcc/Makefile.bsd-wrapper
+++ b/gnu/usr.bin/gcc/Makefile.bsd-wrapper
@@ -1,9 +1,9 @@
-#	$OpenBSD: Makefile.bsd-wrapper,v 1.44 2004/01/31 20:25:36 espie Exp $
+#	$OpenBSD: Makefile.bsd-wrapper,v 1.45 2004/01/31 20:27:58 espie Exp $
 
 #MAN=		cccp.1 gcc.1 gcc-local.1 protoize.1 gcov.1
-MAN=		gcc.1 cpp.1 gcov.1 gcc-local.1
+MAN=		gcc.1 cpp.1 gcov.1 gcc-local.1 protoize.1
 #MLINKS+=	cccp.1 cpp.1
-#MLINKS+=	protoize.1 unprotoize.1
+MLINKS+=	protoize.1 unprotoize.1
 MLINKS+=	gcc.1 cc.1 cpp.1 ccpp.1
 
 BINDIR=/usr/bin
diff --git a/gnu/usr.bin/gcc/protoize.1 b/gnu/usr.bin/gcc/protoize.1
new file mode 100644
index 00000000000..8f45f2f633d
--- /dev/null
+++ b/gnu/usr.bin/gcc/protoize.1
@@ -0,0 +1,396 @@
+.\" Copyright (c) 1991, 1992, 1993, 1994 Free Software Foundation
+.\" See section COPYING for conditions for redistribution
+.\"
+.\" $OpenBSD: protoize.1,v 1.1 2004/01/31 20:27:58 espie Exp $
+.Dd January 14, 2003
+.Dt PROTOIZE 1
+.Os
+.Sh NAME
+.Nm protoize, unprotoize
+.Nd automatically add or remove function prototypes
+.Sh SYNOPSIS
+.Nm protoize
+.Bk -words
+.Op Fl CfgklNnqv
+.Op Fl B Ar directory
+.Op Fl c Ar COMPILATION-OPTIONS
+.Op Fl d Ar directory ...
+.Op Fl i Ar string
+.Op Fl p Ar program
+.Op Fl x Ar
+.Ar
+.Ek
+.Nm unprotoize
+.Bk -words
+.Op Fl fkNnqv
+.Op Fl c Ar COMPILATION-OPTIONS
+.Op Fl d Ar directory ...
+.Op Fl i Ar string
+.Op Fl p Ar program
+.Op Fl x Ar
+.Ar
+.Ek
+.Sh DESCRIPTION
+.Nm protoize
+is an optional part of GNU C.
+You can use it to add prototypes to a program,
+thus converting the program to ANSI C in one respect.
+The companion program
+.Nm unprotoize
+does the reverse: it removes argument types from any prototypes that are found.
+.Pp
+When you run these programs, you must specify a set of source files
+as command line arguments.
+The conversion programs start out by compiling these files
+to see what functions they define.
+The information gathered about a file
+.Ar FOO
+is saved in a file named
+.Ar FOO.X .
+.Pp
+After scanning comes the actual conversion.
+The specified files are all eligible to be converted;
+any files they include
+.Pq whether sources or just headers
+are eligible as well.
+.Pp
+But not all the eligible files are converted.
+By default,
+.Nm protoize
+and
+.Nm unprotoize
+convert only source and header files in the current directory.
+You can specify additional directories whose files
+should be converted with the
+.Sq Fl d Ar directory ...
+option.
+You can also specify particular files to exclude with the
+.Sq Fl x Ar
+option.
+A file is converted if it is eligible, its directory name matches one of the
+specified directory names, and its name within the directory has not
+been excluded.
+.Pp
+Basic conversion with
+.Nm protoize
+consists of rewriting most function definitions and function declarations
+to specify the types of the arguments.
+The only ones not rewritten are those for varargs functions.
+.Pp
+.Nm protoize
+optionally inserts prototype declarations at the beginning of the source file,
+to make them available for any calls that precede the function's definition.
+Or it can insert prototype declarations with block scope
+in the blocks where undeclared functions are called.
+.Pp
+Basic conversion with
+.Nm unprotoize
+consists of rewriting most function declarations to remove any argument types,
+and rewriting function definitions to the old-style pre-ANSI form.
+.Pp
+Both conversion programs print a warning for any function
+declaration or definition that they can't convert.
+You can suppress these warnings with the
+.Fl q
+option.
+.Pp
+The output from
+.Nm protoize
+or
+.Nm unprotoize
+replaces the original source file.
+The original file is renamed to a name ending with
+.Sq .save .
+If the
+.Sq .save
+file already exists, then the source file is simply discarded.
+.Pp
+.Nm protoize
+and
+.Nm unprotoize
+both depend on
+.Xr gcc 1
+to scan the program and collect information about the functions it uses.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl B Ar directory
+Look for the file
+.Sq SYSCALLS.c.X
+in
+.Ar directory ,
+instead of the usual directory
+.Pq normally Pa /usr/local/lib .
+This file contains prototype information about standard system functions.
+This option applies only to
+.Nm protoize .
+.It Fl C
+Rename files to end in
+.Sq .C
+instead of
+.Sq \&.c .
+This is convenient if you are converting a C program to C++.
+This option applies only to
+.Nm protoize .
+.It Fl c Ar COMPILATION-OPTIONS
+Use
+.Ar COMPILATION-OPTIONS
+as the options when running
+.Xr gcc 1
+to produce the
+.Sq .X
+files.
+The special option
+.Fl aux-info
+is always passed in addition, to tell gcc to write a
+.Sq .X
+file.
+.Pp
+Note that the compilation options must be given as a single argument to
+.Nm protoize
+or
+.Nm unprotoize .
+If you want to specify several gcc options, you must quote the entire set of
+compilation options to make them a single word in the shell.
+.Pp
+There are certain gcc arguments that you cannot use, because they
+would produce the wrong kind of output.
+These include
+.Fl g ,
+.Fl O ,
+.Fl c ,
+.Fl S ,
+and
+.Fl o .
+If you include these in the
+.Ar COMPILATION-OPTIONS ,
+they are ignored.
+.It Fl d Ar directory
+Specify additional directories whose files should be converted.
+.It Fl g
+Add explicit global declarations.
+This means inserting explicit declarations at the beginning of each
+source file for each function that is called in the file and was not declared.
+These declarations precede the first function definition that contains a
+call to an undeclared function.
+This option applies only to
+.Nm protoize .
+.It Fl i Ar string
+Indent old-style parameter declarations with the string
+.Ar string .
+This option applies only to
+.Nm protoize .
+.Pp
+.Nm unprotoize
+converts prototyped function definitions to old-style
+function definitions, where the arguments are declared between the
+argument list and the initial
+.Sq { .
+By default,
+.Nm unprotoize
+uses five spaces as the indentation.
+If you want to indent with just one space instead, use
+.Fl i
+.Sq \ \& .
+.It Fl k
+Keep the
+.Sq .X
+files.
+Normally, they are deleted after conversion is finished.
+.It Fl l
+Add explicit local declarations.
+.Nm protoize
+with
+.Fl l
+inserts a prototype declaration for each function in each block which calls
+the function without any declaration.
+This option applies only to
+.Nm protoize .
+.It Fl N
+Make no
+.Sq .save
+files.
+The original files are simply deleted.
+Use this option with caution.
+.It Fl n
+Make no real changes.
+This mode just prints information about the conversions
+that would have been done without
+.Fl n .
+.It Fl p Ar program
+Use the program
+.Ar program
+as the compiler.
+Normally, the name
+.Sq gcc
+is used.
+.It Fl q
+Work quietly.
+Most warnings are suppressed.
+.It Fl v
+Print the version number, just like
+.Fl v
+for gcc.
+.It Fl x Ar
+List of files to exclude from the conversion process.
+.El
+.Pp
+If you need special compiler options to compile one of your program's
+source files, then you should generate that file's
+.Sq .X
+file specially, by running gcc on that source file with
+the appropriate options and the option
+.Fl aux-info .
+Then run
+.Nm protoize
+on the entire set of files.
+.Nm protoize
+will use the existing
+.Sq .X
+file because it is newer than the source file.
+For example:
+.Pp
+.Dl $ gcc -Dfoo=bar file1.c -aux-info
+.Dl $ protoize *.c
+.Pp
+You need to include the special files along with the rest in the
+.Nm protoize
+command, even though their
+.Sq .X
+files already exist, because otherwise they won't get converted.
+.Pp
+.Bf -symbolic
+Note: most of this information is out of date and superseded by the
+EGCS install procedures.
+It is provided for historical reference only.
+.Ef
+.Sh SEE ALSO
+.Xr gcc 1 ,
+.Xr gcc-local 1
+.Sh HISTORY
+Ron Guilmette implemented the
+.Nm protoize
+and
+.Nm unprotoize
+tools.
+.Sh AUTHORS
+See the GNU CC manual for the contributors to GNU CC.
+.Sh CAVEATS
+The conversion programs
+.Nm protoize
+and
+.Nm unprotoize
+can sometimes change a source file in a way that won't work
+unless you rearrange it.
+.Pp
+.Nm protoize
+can insert references to a type name or type tag before
+the definition, or in a file where they are not defined.
+.Pp
+If this happens, compiler error messages should indicate where the
+new references are, so fixing the file by hand is straightforward.
+.Pp
+There are some C constructs which
+.Nm protoize
+cannot figure out.
+For example, it can't determine argument types for declaring a
+pointer-to-function variable; this must be done by hand.
+.Nm protoize
+inserts a comment containing
+.Sq ???
+each time it finds such a variable;
+all such variables can be found by searching for this string.
+ANSI C does not require declaring the argument types of
+pointer-to-function types.
+.Pp
+Using
+.Nm unprotoize
+can easily introduce bugs.
+If the program relied on prototypes to bring about conversion of arguments,
+these conversions will not take place in the program without prototypes.
+One case in which you can be sure
+.Nm unprotoize
+is safe is when you are removing prototypes that were made with
+.Nm protoize ;
+if the
+program worked before without any prototypes, it will work again
+without them.
+.Pp
+You can find all the places where this problem might occur by
+compiling the program with the
+.Fl Wconversion
+option.
+It prints a warning whenever an argument is converted.
+.Pp
+Both conversion programs can be confused if there are macro calls
+in and around the text to be converted.
+In other words, the standard syntax for a declaration or definition
+must not result from expanding a macro.
+This problem is inherent in the design of C and cannot be fixed.
+If only a few functions have confusing macro calls,
+you can easily convert them manually.
+.Pp
+.Nm protoize
+cannot get the argument types for a function whose definition was not
+actually compiled due to preprocessing conditionals.
+When this happens,
+.Nm protoize
+changes nothing in regard to such a function.
+.Nm protoize
+tries to detect such instances and warn about them.
+.Pp
+You can generally work around this problem by using
+.Nm protoize
+step by step, each time specifying a different set of
+.Fl D
+options for compilation, until all of the functions have been converted.
+There is no automatic way to verify that you have got them all, however.
+.Pp
+Confusion may result if there is an occasion to convert a function
+declaration or definition in a region of source code where there
+is more than one formal parameter list present.
+Thus, attempts to convert code containing multiple
+.Pq conditionally compiled
+versions of a single function header
+.Pq in the same vicinity
+may not produce the desired
+.Pq or expected
+results.
+.Pp
+If you plan on converting source files which contain such code,
+it is recommended that you first make sure that each conditionally
+compiled region of source code which contains an alternative
+function header also contains at least one additional follower
+token (past the final right parenthesis of the function header).
+This should circumvent the problem.
+.Pp
+.Nm unprotoize
+can become confused when trying to convert a function
+definition or declaration which contains a declaration for a
+pointer-to-function formal argument which has the same name as the
+function being defined or declared.
+We recommand you avoid such choices of formal parameter names.
+.Pp
+It might be necessary to correct some of the indentation by hand and
+break long lines.
+(The conversion programs don't write lines longer than eighty characters
+in any case.)
+.Sh BUGS
+For instructions on reporting bugs, see the GCC manual.
+.Sh COPYING
+Copyright 1991, 1992, 1993 Free Software Foundation, Inc.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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.