CEXTRACT(1) CEXTRACT(1)
30 October 1992
NAME
cextract, CDOCNAME - C prototype/documentation extractor
SYNOPSIS
cextract [ -Q# ] [ +AaPpNnxZ ] [ -o ofile ] [ -Hstr -Yprog -B -b -V -v
] [[ -options ] filename... ] CDOCNAME [ -Q# ] [ +AaNnx ] [ -o outfile
] [ -Yprogram -B -b -V -v ] [[ -options ] filename... ]
DESCRIPTION
The cextract program is used to extract the function descriptions (aka
prototypes) from a list of C source files and send them out to the
standard output or a specified file. It may also be used to generate
basic documentation for a list of C source files.
The specific reason this program was written was to provide a method
of automatically generating header files, containing prototypes, for
all of the functions used throughout a multi-file project.
Along with the standard C preprocessing options, -D, -I, and -U, there
are options which allow more control of what form the output will
take.
To allow for conditional processing, cextract automatically predefines
the __CEXTRACT__ identifier. Preprocessor commands, such as "#if",
"#ifdef" and "#ifndef" may then be used to control what code is parsed
by cextract. If the CDOCNAME command is used, the program will also
define __CEXTDOC__.
The cextract program also supports the use of customization files. A
system configuration file will be read, and then any "NORMRC" file in
the user's home directory, and finally any "NORMRC" file in the
current directory. For a description of the format of the
customization file, see the cextrc(5) manual page.
COMMAND LINE OPTIONS
The cextract and CDOCNAME programs support both long and short command
line options. Also, a `+' sign before an option description means
that it can be either on or off, with a `+' prefix enabling that
option or a `-' prefix disabling it. The prefix of "no-" (or "no") is
also supported for disabling an option.
Most command line arguments may be used anywhere on the command line,
but a few must be used before any file parsing begins [such as the -N,
+Z and -x options], and one can only be the first argument on the
command line [the -Q flag].
+A, +sort-all
Sort the output, listing all functions in alphabetical order.
This option is not compatible with the +C flag, since functions
are sorted over the entire spectrum, not just for each file.
- 1 - Formatted: April 25, 2024
CEXTRACT(1) CEXTRACT(1)
30 October 1992
+a, +sort-by-files
Sort the output, listing functions alphabetically for each file.
Since this option sorts each file separately, it is compatible
with the +C flag, unlike the +A option. For cextract, the
default is to not do any sorting, while the CDOCNAME default is
to sort by files.
-b, -build-config
Automatically build a configuration file in the current directory
based on the current program settings.
-B, -system-build
Generate a system wide configuration file based on the current
program settings.
+C, +first-comments
Capture the first comment encountered in each file and include it
in the generated output. [default off]
+c, +comments, +yank-comments
Take the comment immediately preceding the function declaration
and send it as output along with the function prototype. [default
on]
-Dexpression, -define=expression
Define a macro, as per the C "#define" preprocessor statement.
+E, +externs
Place the string 'extern' before each function prototype.
[default on]
+F, +filename
Prepend the name of the file to the initial comment when it is
processed. This flag requires the +C option. [default off]
-f%##, -font-%-##
Specify what fonts are to be used when generating troff
documentation output. The font name is a one or two character
troff name which will be interpreted later by the troff
processor. Four fonts are used: `1' or `t' which is used only
for the title words "Function:" and "File:" [default value of
"C", Courier]; `2' or `c' which is used for comments [default
value of "CO", Courier Oblique]; `3' or `n' which is used for the
function name [default value of "B", Times Bold]; and `4' or `p'
for the parameter list [default value of "R", Times Roman]. Note
that the `%' character indicates the type being adjusted, and
"##" indicates the one or two character font name.
-Hstring, -header-string=string
During the normal extraction mode, enclose the output within the
sequence "#ifndef string", "#define string", ..., "#endif /*
- 2 - Formatted: April 25, 2024
CEXTRACT(1) CEXTRACT(1)
30 October 1992
string */". This method is used with many system header files
and prevents the header file from being parsed more than once.
If this option is not used, the output will be enclosed within a
"#ifndef __CEXTRACT__", "#endif /* __CEXTRACT__ */" sequence
instead.
-Idirectory, -include=directory
Add the indicated directory to the search path for include files
accessed via the "#include" preprocessor statement. This flag is
passed on to the C preprocessor.
+m, +multi-comments, +multiple-comments
If the -c flag is set, look for a "block" of multiple comments,
instead of a single comment. Comments with more than one newline
in between are considered separate. [default off]
-N, -roff-mode, -troff-mode
Enable documentation mode, sending output as -ms troff format.
-n, -doc-mode
Enable documentation mode, sending output as normal text. This
is the default mode of the CDOCNAME program.
-o outfile, -output-file outfile, -output-file=outfile
Send output to the specified file instead of the standard output.
The file name need not immediately follow the `-o' flag, but it
must be the first non-option argument. Warning: This will
overwrite any existing file of the same name.
+P, +dual-output
In extraction mode, generate both styles of C prototypes,
separated by using "#ifdef" and "#else" statements to test for
__STDC__. This option must precede any file arguments. [default
on]
+p, +ansi-code
Produce output in ANSI C prototype format; otherwise, produce
old-style declarations. This option must precede any file
arguments. [default off]
-qfile, -config-file=file
Read in the specified file and parse it for customization
commands.
-Q#, -read-config=#
An octal digit specifies which configuration files should be
read; 1 for the system configuration file, 2 for the $HOME/NORMRC
file and 4 for the "NORMRC" file in the current directory. Add
values to read multiple files. If no number is specified, a 0 is
assumed. This option must be the very first argument on the
command line. [default value of 7 reads all three files]
- 3 - Formatted: April 25, 2024
CEXTRACT(1) CEXTRACT(1)
30 October 1992
+r, +remove-names, +discard-names
Strip out the variable names when sending out the prototype
lists.
+S, +show-all, +show-anyway
If the -p flag is off, output the prototype list anyway, but
enclosed within comments. If the -P flag is set, comments and
commented prototypes should also be duplicated within the non-
ANSI portion of the output. [default on]
+s, +s:none|all|only, +statics, +statics: none|all|only
Indicate how static functions are to be treated. If "none" is
chosen, static functions will be ignored, if "only" then any
non-static functions will be ignored, and "any" indicates that
all functions will be included. If no selection is given, either
"any" (`+' flag), or "none" (`-' flag) will be used.
-T#, -tab-width=#
Specify the tab width used during documentation output. If no
value is given, or a value of zero is given, tabs are passed
though unformatted.
-Uname, -undefine=name
Undefine a macro. If "-Dname" was specified in a previous
argument, it is removed from the argument list; otherwise, this
option is passed on to the C preprocessor.
-V, -settings
Show the current settings of the various program options.
-v, -version-info
Display the version number of the program.
+W, +break-after-types, +break-types
When enabled, a newline will be inserted between the function
type and the function name in the function declarations.
+w#, +wrap-parameters=#
If the length of the parameter list for a function would cause it
to exceed a given number of columns [72 by default], a newline
will be inserted in place of a space character, so that the
function will not exceed that given length. The optional number
after the command will override a negation prefix if encountered.
-x, -extract-mode
Run cextract or CDOCNAME as a prototype extractor. This is the
default mode for cextract.
-Yprogram -cpp-program=program
Specify which program to use as the C preprocessor. This program
should resolve all of the C defines and preprocessor statements
- 4 - Formatted: April 25, 2024
CEXTRACT(1) CEXTRACT(1)
30 October 1992
while, hopefully, leaving comments intact.
+Z, -merge-output
Combine the ANSI and K&R C output of the cextract on one line, to
create a much more compact header file.
VMS
Configuration files are also supported under VMS. The default
configuration files for VMS systems are sys$library:cext.cnf,
sys$login:cext.cnf, and cext.cnf.
Since the VMS C compiler strips out comments, the documentation mode
and comment options are not very useful. Using the GNU C preprocessor
instead might be a possible solution.
COPYRIGHT
The code is freely distributable and there are no restrictions other
than the fact that it not be used for monetary gain and that copyright
notices must be kept intact.
Both cextract and CDOCNAME may be used to generate proprietary source
code or documentation, but its own source code may not be used as a
part of any proprietary programs.
The header files and documentation generated by cextract and CDOCNAME
are not subject to this COPYRIGHT notice because they are derived from
the source code which was read in by the program to create the output.
FILES
SYSCXTRC, $HOME/NORMRC, NORMRC
The list of configuration files, and the order in which they are
read in.
SEE ALSO
cc(1), cextrc(5)
AUTHORS
Adam Bryant
adb@cs.bu.edu
initial VMS port by John Carr
jrcarr@iup.bitnet
special thanks to comp.sources.reviewed reviewers, without whom this
program would be much less useful.
VMS
On VMS systems, only the longer command line options are available,
and the '/' character is used to specify command line options.
- 5 - Formatted: April 25, 2024
CEXTRACT(1) CEXTRACT(1)
30 October 1992
BUGS
1) As far as I know, there is no way to tell the normal VMS C compiler
not to strip out comments. This renders the comment extraction and
documentation mode portions rather useless to VMS sites. Getting the
GNU C preprocessor for such sites is recommended.
2) Cextract has problems with function pointers and structure
definitions within the parameter list, using typedefs for such
declarations is recommended.
3) Does not yet fully support C++ code.
4) It is dependent on the given C preprocessor, so will have any
limitations (such as maximum #defines) which the C preprocessor has.
If any other bugs are detected, please notify the author.
- 6 - Formatted: April 25, 2024
