Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CEXTRACT(1)		    General Commands Manual		   CEXTRACT(1)

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  sup-
       ported 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 com-
       mand 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  de-
	      fault 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	direc-
	      tory 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.  [de-
	      fault on]

       -Dexpression, -define=expression
	      Define a macro, as per the C "#define" preprocessor statement.

       +E, +externs
	      Place  the  string 'extern' before each function prototype. [de-
	      fault 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 documen-
	      tation 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  pa-
	      rameter list [default value of "R", Times	Roman].	 Note that the
	      `%' character indicates the type being adjusted, and "##"	 indi-
	      cates 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 in-
	      stead.

       -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  new-
	      line 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  out-
	      put.   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, sepa-
	      rated 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 argu-
	      ments.  [default off]

       -qfile, -config-file=file
	      Read in the specified file and parse it for  customization  com-
	      mands.

       -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 di-
	      rectory.	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 en-
	      closed within comments. If the -P	flag is	set, comments and com-
	      mented 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,  ei-
	      ther "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 argu-
	      ment, it is removed from the argument list; otherwise, this  op-
	      tion 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 new-
	      line 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  encoun-
	      tered.

       -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  pro-
	      gram should resolve all of the C defines and preprocessor	state-
	      ments 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 configu-
       ration  files  for  VMS	systems	 are   sys$library:cext.cnf,   sys$lo-
       gin: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  defini-
       tions  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	 limi-
       tations (such as	maximum	#defines) which	the C preprocessor has.

       If any other bugs are detected, please notify the author.

				30 October 1992			   CEXTRACT(1)

NAME | SYNOPSIS | DESCRIPTION | COMMAND LINE OPTIONS | VMS | COPYRIGHT | FILES | SEE ALSO | AUTHORS | VMS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cextract&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help