GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CEXTRACT (1)

NAME

cextract, CDOCNAME - C prototype/documentation extractor

CONTENTS

Synopsis
Description
Command Line Options
Vms
Copyright
Files
See Also
Authors
Vms
Bugs

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.
+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 /* 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]
+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 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.

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.

Search for    or go to Top of page |  Section 1 |  Main Index


--> CEXTRACT (1) 30 October 1992

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.