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
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
- 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
- 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
- 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
- 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'
- 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
- 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"
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
- 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
- Alphabetically sort all of the functions from all of the files before
- 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
- 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.
- SYSCXTRC, $HOME/NORMRC, NORMRC
- 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
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
initial VMS port by John Carr