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  -  CEXTRC (5)

NAME

cextrc - C prototype/documentation extractor customization file format

CONTENTS

Synopsis
Description
Format
Commands
Files
Vms
See Also
Author

SYNOPSIS

NORMRC

DESCRIPTION

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.

FORMAT

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.

COMMANDS

The full list of configuration commands is given below.
ansi-code 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.
break-after-types
break-types When enabled, a newline will be inserted between the function type and the function name in the function declarations.
comments
yank-comments 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.
doc-mode 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.
dual-output 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.
externs Prepend an "extern" to each function description upon output.
extract-mode 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).
first-comments Include in the output the initial comment encountered in each file.
filename
prepend-filename 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-output 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.
multi-comments
multiple-comments 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 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-names
discard-names Remove variable names from the prototype list prior to output.
roff-mode
troff-mode Enable documentation mode with troff -ms format output. This option is overridden by the doc-mode or extract-mode options.
show-all
show-anyway 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.
single-comments When extracting comments from a file, take only one comment, discarding all preceding comments. This option is the reverse of the multi-comments option.
sort-all Alphabetically sort all of the functions from all of the files before generating output.
sort-by-files For each file processed, sort all of the functions prior to output.
statics
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.

FILES

SYSCXTRC, $HOME/NORMRC, NORMRC configuration files.

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.

SEE ALSO

cextract(1), CDOCNAME(1)

AUTHOR

Adam Bryant
adb@bu.edu

initial VMS port by John Carr jrcarr@iup.bitnet

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


--> CEXTRC (5) 3 September 1992

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