.\" $Id: cproto.1 3.6 92/06/10 20:55:39 cthuang Exp $
.\"
.de EX		\"Begin example
.ne 5
.if n .sp 1
.if t .sp .5
.nf
.in +5n
..
.de EE		\"End example
.fi
.in -5n
.if n .sp 1
.if t .sp .5
..
.TH CPROTO 1 "April 7, 1992"
.SH NAME
cproto \- generate C function prototypes and convert function definitions
.SH SYNOPSIS
.B cproto
[ 
.I option \fP...\fI
] [
.I file \fP...\fI
]
.SH DESCRIPTION
.B Cproto
generates function prototypes for
functions defined in the specified C source files to the standard output.
The function definitions may be in the old style or ANSI C style.
Optionally,
.B cproto
also outputs declarations for any variables defined in the file.
If no
.I file
argument is given,
.B cproto
reads its input from the standard input.
.LP
By giving a command line option,
.B cproto
will also convert function definitions in the specified files from the
old style to the ANSI C style.
The original source files along with files specified by
.EX
#include "file"
.EE
directives appearing in the source code will be overwritten
with the converted code.
If no file names are given on the command line, then the program reads
the source code from the standard input and outputs the converted source
to the standard output.
.LP
If any comments appear in the parameter declarations for a function definition,
such as in the example,
.EX
main (argc, argv)
int argc;       /* number of arguments */
char *argv[];   /* arguments */
{
}
.EE
then the converted function definition will have the form
.EX
int
main (
    int argc,       /* number of arguments */
    char *argv[]   /* arguments */
)
{
}
.EE
Otherwise, the converted function definition will look like
.EX
int
main (int argc, char *argv[])
{
}
.EE
.LP
.B Cproto
can optionally convert function definitions from the ANSI style to the old
style.
In this mode, the program also converts function declarators and prototypes
that appear outside function bodies.
This is not a complete ANSI C to old C conversion.
The program does not change anything within function bodies.
.SH OPTIONS
.TP
.B \-a
Convert function definitions from the old style to the ANSI C style.
.TP
.B \-e
Output the keyword
.B extern
in front of every declaration having global scope.
.TP
.BI \-f n
Set the style of generated function prototypes where
.I n
is a number from 0 to 4.
For example, consider the function definition
.EX
main (argc, argv)
int argc;
char *argv[];
{
}
.EE
If the value is 0, then no prototypes are generated.
When set to 1, the output is:
.EX
int main(/*int argc, char *argv[]*/);
.EE
For a value of 2, the output has the form:
.EX
int main(int /*argc*/, char */*argv*/[]);
.EE
The default value is 3.
It produces the full function prototype:
.EX
int main(int argc, char *argv[]);
.EE
A value of 4 produces prototypes guarded by a macro:
.EX
int main P_((int argc, char *argv[]));
.EE
.TP
.B \-c
Omit the parameter comments in the prototypes generated by
the \-f1 and \-f2 options.
This option also omits the comments naming the source files from which
the prototypes were generated.
.TP
.BI \-m name
Set the name of the macro used to guard prototypes when option \-f4 is selected.
The default is "P_".
.TP
.B \-d
Omit the definition of the prototype macro named by the \-m option.
.TP
.B \-p
Disable promotion of formal parameters in old style function definitions.
By default, parameters of type
.B char
or
.B short
in old style function definitions are promoted to type
.B int
in the function prototype or converted ANSI C function definition.
Parameters of type
.B float
get promoted to 
.B double
as well.
.TP
.B \-q
Do not output any error messages when the program cannot read the
file specified in an
.I #include
directive.
.TP
.B \-s
By default,
.B cproto
only generates declarations for functions and variables having global scope.
This option will output
.B static
declarations as well.
.TP
.B \-t
Convert function definitions from the ANSI C style to the traditional style.
.TP
.B \-v
Also output declarations for variables defined in the source.
.LP
.nf
.BI \-P template
.BI \-F template
.BI \-C template
.fi
.in +5n
Set the output format for generated prototypes, function definitions,
and function definitions with parameter comments respectively.
The format is specified by a template in the form
.EX
" int main ( a, b )"
.EE
but you may replace each space in this string with any number of
whitespace characters.
For example, the option
.EX
-F"int main(\\n\\ta,\\n\\tb\\n\\t)"
.EE
will produce
.EX
int main(
        int argc,
        char *argv[]
        )
.EE
.TP
.BI \-D name\[=value\]
This option is passed through to the preprocessor and is used to define 
symbols for use with conditionals such as
.I #ifdef.
.TP
.BI \-U name
This option is passed through to the preprocessor and is used to remove
any definitions of this symbol.
.TP
.BI \-I directory
This option is passed through to the preprocessor and is used to specify
a directory to search for files that are referenced with 
.I #include.
.TP
.BI \-E cpp
Pipe the input files through the specified C preprocessor command
when generating prototypes.
By default, the program uses /lib/cpp.
.TP
.BI \-E 0
Do not run the C preprocessor.
.TP
.B \-V
Print version information.
.SH ENVIRONMENT
The environment variable CPROTO is scanned for
a list of options in the same format as the command line options.
.SH BUGS
If an untagged struct, union or enum declaration appears in
a generated function prototype or converted function definition,
the content of the declaration between the braces is empty.
.LP
The program does not pipe the source files through the C preprocessor when
it is converting function definitions.
Instead, it tries to handle preprocessor directives and macros itself
and can be confused by tricky macro expansions.
The conversion also discards some comments in the function definition
head.
.LP
The \-v option does not generate declarations for variables defined with the
.B extern
specifier.
This doesn't strictly conform to the C language standard but this rule
was implemented because include files commonly declare variables this way.
.LP
When the program encounters an error, it usually outputs the not very
descriptive message "syntax error".
.LP
Options that take string arguments only interpret the following
character escape sequences:
.EX
\\n	newline
\\t	tab
.EE
.SH AUTHOR
.nf
Chin Huang
cthuang@zerosan.UUCP
chin.huang@canrem.com
.fi
.SH "SEE ALSO"
cc(1),
cpp(1)