Quick Navigator

Search Site

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

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages
CEXTRC(5) FreeBSD File Formats Manual CEXTRC(5)

cextrc - C prototype/documentation extractor customization file format


The programs cextract(1) and CDOCNAME(1) extract function prototypes from C source code and create header and documentation files respectively. The NORMRC customization files allow users to specify which options are set for those programs, without having to always use the command line.
The configuration files are read prior to the parsing of the command line options, as well as whenever the `-q' flag is encountered.

The file should be a normal text file, with each customization command on a separate line. Blank lines and any line beginning with a `#' will be ignored.
Any command preceded by the string "doc-only " will only be used in documentation mode, and any command preceded by "extract-only " will only be used in extraction mode.
Commands which are preceded by either a `!' or the string "no-" or "no" will be interpreted as disabling that option, if appropriate.

The full list of configuration commands is given below.
If dual-output and merge-output modes are not enabled, produce output in ANSI C format, with full prototyping. This command does not do anything when used in documentation mode.
When enabled, a newline will be inserted between the function type and the function name in the function declarations.
Extract the comment immediately before the function definition, and display it upon output.
config-file: file
Read in the specified file and parse it for configuration commands.
cpp-program: program
Specify which program is to be used as a C preprocessor. This program should resolve all C defines and while, hopefully, leaving the comments intact.
Enable documentation mode with normal text output. This is the default setting for CDOCNAME(1).
define: expression
Pass the specified expression to the C preprocessor with a "-D" string prepended to it. This command is equivalent to the `-D' command line option.
Provide output in both ANSI and K&R C formats, separated by an "#if __STDC__" ... "#else" ... "#endif" construct. This command does not do anything when used in documentation mode or if the merge-output option is enabled.
Prepend an "extern" to each function description upon output.
Enable extraction mode and generate output which can be used as a C header file defining the prototypes for all of the functions which are encountered. The is the default mode for cextract(1).
Include in the output the initial comment encountered in each file.
If the "first-comments" option is enabled, prepend the name of each file to the output of initial comments.
font % ##
Assign a troff font "##" to a given font type `%', when using troff documentation mode. The possible font types are `1' or `t', `2' or `c', `3' or `n', and `4' or `p' for the title, comment, name, and parameter list respectively. The troff font "##" is a normal one or two character troff font, such as "CO" for Courier Oblique.
header-string: string
When in extraction mode, enclose the output within preprocessor directives testing for the definition of string. This method is used with many system header files, to insure that they are not "#include"d more than once. If this option is not used, the output will be enclosed within a "#ifndef __CEXTRACT__", "#endif /* __CEXTRACT__ */" sequence instead.
include: directory
Pass the specified directory to the C preprocessor with a "-I" string prepended to it. This command is equivalent to the `-I' command-line option.
Merge the ANSI and K&R output into a single line of output to make it take up less space. A macro is used to expand the parameter list for ANSI compilers. This option overrides both the dual-output and ansi-code options. There is no affect if the documentation mode is enabled.
When extracting comments, assume that consecutive comments are actually one single comment. This allows people that place comment delimiters at the beginning and end of each line to have their comments properly captured.
output-file: outfile
Store the output in the specified file.
Replace the first string which matches a variable, type, or both (as selected) with the second string. The format is:
replace [all/type/variable] " string1" "string2"
For example, on Sun machines, the automatic "FILE" replacement could be accomplished using a command like:
replace type "struct _iobuf" "FILE"
However, this should not need to be entered by the average user since it is handled automatically by cextract(1), as is the varargs system.
Remove variable names from the prototype list prior to output.
Enable documentation mode with troff -ms format output. This option is overridden by the doc-mode or extract-mode options.
When output is K&R C, display prototypes in comments. When dual-output is enabled, display comments and prototypes in both sections; otherwise, display comments and prototypes only in the ANSI C portion. This option does nothing in documentation mode.
When extracting comments from a file, take only one comment, discarding all preceding comments. This option is the reverse of the multi-comments option.
Alphabetically sort all of the functions from all of the files before generating output.
For each file processed, sort all of the functions prior to output.
statics: none
statics: any
statics: only
Select the method for how static functions should be treated. If "none" is selected, statics will be ignored. If "only" is selected, non-static functions will be ignored. Finally, "any" indicates that all functions will be extracted. If no selection is made, it will be the same as selecting "any" or (with a preceding `!') "none".
tab-width: width
Set the tab width to be an integer number width. This works only during documentation generation.
undefine: name
Undefine any previously defined macro. If none is encountered, pass the specified expression to the C preprocessor with a "-U" string prepended to it. This command is equivalent to the `-U' command-line option.
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.

configuration files.

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.

cextract(1), CDOCNAME(1)

Adam Bryant
initial VMS port by John Carr jrcarr@iup.bitnet
3 September 1992

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

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