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

FreeBSD Manual Pages


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

       c2man - generate	manual pages from C source code

       c2man [ option ...  ] [ file ...	 ]

       c2man  reads  C source code files in which comments have	been strategi-
       cally placed, and outputs manual	page(s)	documenting each function  de-
       fined  or declared (via a prototype), and optionally each variable with
       global scope.  Function definitions and declarations may	be in the  old
       style or	ISO/ANSI style.	 If no file argument is	given, c2man takes its
       input from the standard input.

       If a .h file is written as a formal interface description when  prepar-
       ing an interface	spec, c2man can	generate all the manual	pages required
       for the spec at one fell	swoop, and then	keep them up to	date automati-
       cally as	the interface changes.

       Since  c2man  will accept either	function definitions or	prototypes, it
       can be used on either .c	or .h files.  If the input is a	 header	 file,
       any  files specified by -i options are assumed to be prerequisites, and
       get parsed before the input file.  (Any	file  whose  extension	begins
       with ``h'', matched case-insensitively, is considered a header file.)

       This is potentially a huge win for most programmers that	just love doc-
       umenting	their functions, and updating the documentation	every time  it
       changes.	 Here's	an example, named example.h:

	 enum Place
	     HOME,	/* Home, Sweet Home */
	     WORK,	/* where I spend lots of time */
	     MOVIES,	/* Saturday nights mainly */
	     CITY,	/* New York, New York */
	     COUNTRY	/* Bob's Country Bunker	*/

	  * do some useful work	for a change.
	  * This function will actually	get some productive
	  * work done, if you are really lucky.
	  * returns the	number of milliseconds in a second.
	 int dowork(int	count,	      /* how much work to do */
		    enum Place where, /* where to do the work */
		    long fiveoclock   /* when to knock off */);


	    % c2man example.h

       is  run,	 this produces a file named dowork.3 which can be processed by
       man(1) or used as:

	    % nroff -man dowork.3

       to produce:

	  dowork(3)    UNIX Programmer's Manual	   dowork(3)

		 dowork	- do some useful work for a change.

		 #include <example.h>

		 int dowork
		      int count,
		      enum Place where,
		      long fiveoclock

		 int count
			How much work to do.

		 enum Place where
			Where to do the	work.

			Possible values	for an enum Place are as follows:
			HOME	 Home, Sweet Home.
			WORK	 Where I spend lots of time.
			MOVIES	 Saturday nights mainly.
			CITY	 New York, New York.
			COUNTRY	 Bob's Country Bunker.

		 long fiveoclock
			When to	knock off.

		 This function will actually  get  some	 productive  work
		 done, if you are really lucky.

		 The number of milliseconds in a second.

   Output Generation
       By default, a separate output file is generated for each	global identi-
       fier (i.e. function or variable)	documented by c2man.

       Much of c2man's information is extracted	from the comment placed	 imme-
       diately before the declaration/definition of the	identifier being docu-
       mented; this comment is taken to	describe the identifier	 and  must  be
       present,	 or the	identifier will	be ignored entirely.  In the case of a
       variable	declaration/definition,	this comment may instead be placed af-
       ter it starting on the same line.

       Global variables	are not	documented, unless the -v option is used.

       Identifiers declared static are ignored by default unless the file is a
       header file (which is most useful with inline functions)	or the -s  op-
       tion is used.

       Declarations  with the extern keyword are ignored unless	they appear in
       a header	file; note that	this does not include function definitions.

   Sections Generated Automatically
       Each manual page	starts with a NAME section, listing the	name(s)	of the
       identifier(s)  documented, along	with a terse description.  By default,
       this description	is the first line or sentence of the comment  describ-
       ing  the	 identifier.   With the	-g option, it is found after the first
       dash (-)	in the first comment of	the file, and the -G option  specifies
       it explicitly.

       The SYNOPSIS section begins with	an #include line if the	source file is
       a header.  After	this is	an external declaration	for the	 identifier(s)
       being documented.

       Information  in the PARAMETERS section is gleaned from the comments im-
       mediately before	or after each parameter	declaration. A comment after a
       parameter  can  follow the comma	that separates that parameter from the
       next, if	the comment starts on the same line and	is the only  remaining
       thing  on  that	line.  Leading	underscores  in	 a  parameter name are
       stripped	when printed in	the manual page.

       If the manual page is for a group of functions  (i.e.   -g  or  -G  op-
       tions),	identical  parameters  (in  both name and type)	common to more
       than one	function are described only once if only one has a comment (as
       in the ctype example below).

       If  a  parameter	 is an enumerated type,	all the	possible values	it can
       take are	output,	along with their descriptions.	These descriptions are
       gleaned	from  the  comments surrounding	the enum identifiers where the
       type was	defined.  Comments describing enum identifiers are placed in a
       similar	manner to those	that describe function parameters.  enum iden-
       tifiers that begin with an underscore are ignored, which	is useful  for
       padding or _NUMBER_OF_...  values which aren't normally used by someone
       calling the function.  If none of the identifiers in an enumerated type
       has a comment, c2man will bunch them together to	save space.

       The  DESCRIPTION	 section  contains  everything after the first line or
       sentence	of the comment describing the identifier, up  until  the  word
       ``returns''  at the start of a line, matched case-insensitively and op-
       tionally	followed by a colon (:).  In the case of a variable of enumer-
       ated type, it will also list all	the values it can hold.

       The  RETURNS  section  contains anything	after that. Any	of these lines
       that begin with a single	word followed by a colon  or  a	 tab  generate
       tagged  paragraphs  so  that  lists of possible return values and error
       codes look neat.	 If the	function is void, don't	put anything like "Re-
       turns:  nothing"	 in  the  comment, since it's a	waste of space.	If the
       identifier is a function	returning an  enumerated  type,	 its  possible
       values will be listed here.

       The RETURNS section is also added if there is a comment after the func-
       tion return type.
       /* Sample function */
       char *		   /* NULL if failed string otherwise */
       The RETURNS section will	contain	 the  full  contents  of  the  comment
       (stripping  the	optional  leading asterisk). It	is not possible	to use
       both methods to specify a description for the  return  value.  In  that
       case  the  comment after	the return type	supersedes whatever was	speci-
       fied for	the return value in the	comment	above the function.

       Finally,	a SEE ALSO section is generated,  referencing  all  the	 other
       manual pages generated, if any.

       The  RETURNS,  PARAMETERS and SEE ALSO sections are omitted entirely if
       they aren't needed.

   Comment Style and Placement
       Both C and C++ style comments are recognized, with separate consecutive
       single-line  comments  coalesced	 into a	single block.  When looking at
       comments, c2man ignores everything before the first alpha-numeric char-
       acter.  After  that,  it	ignores	leading	white-space, leading asterisks
       and leading slashes on all subsequent lines, and	ignores	 all  trailing
       lines  thus  rendered blank. If that leaves nothing, the	comment	is ig-
       nored entirely.	This makes it very flexible in supporting popular com-
       ment boxing.

       Comments	 can be	placed with considerable flexibility so	that most com-
       menting styles are supported.
       /* commas after the comments. */
       enum Place
	   HOME	      /* Home, Sweet Home */,
	   WORK	      /* where I spend lots of time */,
	   MOVIES     /* Saturday nights mainly	*/,
	   CITY	      /* New York, New York */,
	   COUNTRY    /* Bob's Country Bunker */
       /* the comment needn't go on the	same line,
	* if the comma goes after the comment.
       enum Place
	    /* Home, Sweet Home	*/,
	    /* where I spend lots of time */,
	    /* Saturday	nights mainly */,
	    /* New York, New York */,
	    /* Bob's Country Bunker */
       /* the comment can go before it too. */
       enum Place
	   /* Home, Sweet Home */
	   /* where I spend lots of time */
	   /* Saturday nights mainly */
	   /* New York,	New York */
	   /* Bob's Country Bunker */
       But the following example is NOT	equivalent because the commas are  be-
       tween the identifier and	the its	associated comment, and	the comment is
       on a different line.  Each comment actually applies to the wrong	 iden-
       tifier, so this will result in very misleading output.
       enum Place
	    /* Home, Sweet Home	*/
	    /* where I spend lots of time */
	    /* Saturday	nights mainly */
	    /* New York, New York */
	    /* Bob's Country Bunker */

       Since  enum  identifiers	 sometimes fall	into logical groups, a comment
       before such an identifier will be taken to apply	to the next few	in the
       list,  provided that the	comments describing each individual identifier
       are placed after	them. Also, there must be a blank line separating  the
       comment describing the next logical group and the comment at the	end of
       the previous line, or the two will be coalesced and incorrectly treated
       as a single comment for the previous enumerator.
       /* include logical grouping comments. */
       enum Place
	   /* These take up most of the	week */
	   HOME,      /* Home, Sweet Home */
	   WORK,      /* where I spend lots of time */

	   /* More for special occasions */
	   MOVIES,     /* Saturday nights mainly */
	   CITY,      /* New York, New York */

	   /* The real favourite */
	   COUNTRY    /* Bob's Country Bunker */

       That  may  all  sound  a	bit complex, but the upshot is that c2man will
       usually know which identifier a comment is associated with, unless  you
       do something truly bizarre.

   Processing of Comment Contents
       Basic  punctuation and capitalisation corrections are made in each sec-
       tion for	neatness, and the typesetting program used to process the out-
       put  will  generally reformat line breaks according to the width	of the
       output device. Blank lines in a comment will be	preserved,  and	 lines
       starting	with a dash (-), an asterisk (*), or a numbered	point ((n), n)
       or n.), will cause a line break,	allowing simple	bulleted  or  numbered

       Lines beginning with a tab after	the comment leader will	be output ver-
       batim without reformatting, to allow source code	to be embedded in  the

       Typesetter  specific commands may be included for more complex process-
       ing, although this isn't	recommended since it ties you to a  particular

   Grouped Manual Pages
       Simple,	closely	 related objects can be	grouped	together onto a	single
       page with the -g	or -G options. By default, this	results	 in  a	single
       output  file with multiple links	so that	it can be accessed by the name
       of the input file, or of	any identifier documented.   For  example,  if
       ctype.h contains:

	 /* ctype.h - character	classification functions */

	 /* character is alphanumeric
	  * returns 0 if the character doesn't fit the
	  * classification; non-zero (but not necessarily 1)
	  * if it does.
	 inline	int isalnum(int	c /* the character to classify */);

	 /* character is a letter */
	 inline	int isalpha(int	c);

	 /* character is a control character */
	 inline	int iscntrl(int	c);

	 /* character is a digit */
	 inline	int isdigit(int	c);

	 /* character is a graphic */
	 inline	int isgraph(int	c);

	 /* character is a lower case letter */
	 inline	int islower(int	c);

	 /* character is printable */
	 inline	int isprint(int	c);

	 /* character is punctuation */
	 inline	int ispunct(int	c);

	 /* character is a a form of whitespace	*/
	 inline	int isspace(int	c);

	 /* character is an upper case letter */
	 inline	int isupper(int	c);

	 /* character is a hexadecimal digit */
	 inline	int isxdigit(int c);

       then using:

	    % c2man -g ctype.h


	  ctype(3)     UNIX Programmer's Manual	    ctype(3)

		 isalnum,  isalpha,  iscntrl,  isdigit,	isgraph, islower,
		 isprint, ispunct, isspace, isupper, isxdigit -	character
		 classification	functions

		 #include <ctype.h>

		 inline	int isalnum(int	c);

		 inline	int isalpha(int	c);

		 inline	int iscntrl(int	c);

		 inline	int isdigit(int	c);

		 inline	int isgraph(int	c);

		 inline	int islower(int	c);

		 inline	int isprint(int	c);

		 inline	int ispunct(int	c);

		 inline	int isspace(int	c);

		 inline	int isupper(int	c);

		 inline	int isxdigit(int c);

		 int c	The character to classify.

		 Character is alphanumeric.

		 Character is a	letter.

		 Character is a	control	character.

		 Character is a	digit.

		 Character is a	graphic.

		 Character is a	lower case letter.

		 Character is printable.

		 Character is punctuation.

		 Character is a	a form of whitespace.

		 Character is an upper case letter.

		 Character is a	hexadecimal digit.

		 0  if the character doesn't fit the classification; non-
		 zero (but not necessarily 1) if it does.

   Extra Sections
       Additional sections not otherwise recognized by c2man can  be  included
       in  the	manual	page  by  including them in the	comment	describing the
       identifier.  A section heading is preceded in the comment by  an	 empty
       line (after removal of leading asterisks), and is the only word on it's
       line, or	is a word followed by a	colon (:), or is a line	ending with  a
       colon, so section names with spaces are allowed,	like "Return value:".

       Section	heading	 names are capitalized,	and the	names DESCRIPTION, RE-
       TURNS and NAME are recognized specially so you can name them explicitly
       if  you like.  FUNCTION,	PROCEDURE and ROUTINE are also recognised, and
       treated identically to NAME.
	* Have a quick puff.
	* Warning: Smoking causes lung cancer
       void go_for_a_smoke();
       Generates a manual page with a WARNING section.

       -odir  Write generated files into directory dir rather than the current
	      directory.   If dir is specified as -, generated pages are writ-
	      ten to the standard output, separated by form-feeds.

       -v     Also output declarations for variables defined in	the file.

       -s     Output manual pages for all static identifiers.

       -g     Group all	the info generated together into a  single  page  (ala
	      ctype(3)),  reading  the	single-line  terse description for the
	      NAME section from	the line of the	first comment in the file.  If
	      this  first  line	 contains a dash (-) surrounded	by whitespace,
	      the terse	description is taken starting after the	dash.  If mul-
	      tiple  files  are	specified, the first such suitable comment en-
	      countered	is used. A link	to the output file is  made  for  each
	      identifier documented, according to the -l option.

	      Like  -g,	 but using the specified terse description rather than
	      reading it from the file.

       -k     Don't attempt to fix up capitalization and punctuation.

       -b     If a function lacks a preceding comment, look  for  one  immedi-
	      ately following the curly-brace at the top of the	function body.
	      The comment must appear before anything else.

       -B     Apply -b strictly.  Only look for	the description	of a  function
	      at the top of its	body.

       -l h|s|f|n|r
	      Select  how  the	output	for a grouped manual page is linked to
	      files named after	all identifiers	documented on the page.	  Hard
	      link  (h)	is the default,	as it uses the least space.  Soft link
	      (s), where supported, allows a find(1) command with ``-type  f''
	      to easily	skip the duplicated pages.  Separate file (f) contain-
	      ing a file include directive is the traditional UNIX method.  No
	      link  (n)	is useful for generating printed documentation without
	      duplicated pages;	only a single file, named according to the  -n
	      option,  is generated.  Remove (r) is like No link, but also re-
	      moves any	previously generated links/files named after the iden-
	      tifiers  documented. Useful for cleaning up after	accidents with
	      the other	link options.

	      In all cases, any	existing links will be	removed	 before	 being

       -n     Name  the	 documentation output file after the input file.  When
	      generating grouped manual	pages, this will be the	file to	 which
	      others  are linked.  For non-grouped manual pages, if documenta-
	      tion for more than  one  identifier  is  generated,  information
	      about  the  last identifier will overwrite information about all
	      the previous ones.



	      Insert a #include	line referencing the  specified	 file  in  the
	      SYNOPSIS	section,  using	 the  ``<file>'' form by default.  Any
	      number of	-i options may be specified to build up	a list of pre-
	      requisites.  If using the	second form, you may need to quote the
	      quotation	marks, lest they get removed by	the shell.

	      Exclude sectionname from the generated man pages.	  This	option
	      may be repeated to exclude a number of sections.

	      Prepend  header-path to the name of the header file when an #in-
	      clude line is automatically generated in the SYNOPSIS section.

       -L     Lazy option: Only	list parameters	in the PARAMETERS  section  if
	      they  are	documented by a	comment	in the source. By default, pa-
	      rameters with no comment are described as	 ``Not	Documented.'',
	      to encourage the programmer to comment them.

	      Set the output typesetting language as well as language specific
	      options.	options	is a comma delimited list of  options.	 Nroff
	      (n) is the default, LaTeX	(l) , Texinfo (t) , HTML (h) , AutoDoc
	      (a).  , or Raw text (r).	Texinfo	specific options are s,	t,  n,
	      and C.

	      In Texinfo mode, each section is normally	coded as a ``heading''
	      rather than a ``section''.  This prevents	the section name  from
	      appearing	 in  the table of contents.  If	the option t is	given,
	      the name of the man page is used for the title of	the NAME  sec-
	      tion,  and  is encoded as	a ``section'', placing it in the table
	      of contents.  Subsequent sections	are encoded  as	 ``headings''.
	      Texinfo  supports	multiple levels	of headings; the desired level
	      may be specified via the sn option, where	n starts at 0 for  the
	      ``chapter	 level''  and works down.  A top level node is created
	      for the man page,	except when in embedded	mode (the c2man	-e op-
	      tion).   If  the n option	is specified, a	node is	created	in em-
	      bedded mode, but without Up, Previous, or	Next pointers;	 these
	      must be filled in	(Texinfo mode in emacs does a good job of it).
	      The C option capitalizes the section titles.  Usually  they  are
	      printed as specified (which is usually upper case).

       -e     Prepares the output so it	can be embedded	in texts of the	output
	      typesetting language.

       -Mname Set the name of the manual in which the page will	go.

	      Set the default manual section, used as  the  extension  on  the
	      output files.  section defaults to ``3'' for nroff, ``texi'' for
	      Texinfo ,	``html'' for HTML and ``tex''  for  LaTeX  output,  as
	      specified	 via the -T option.  This setting can be overridden by
	      the -O?.ext options for finer control.

	      Provides for finer control of the	output files, allowing a  dif-
	      ferent  output  subdirectory  and	 extension to be specified for
	      these different classes of  objects:  functions  (f),  variables
	      (v), static functions (F)	and static variables (V).

	      If  subdir  is  specified,  the selected class of	output will be
	      written in that subdirectory under the directory given by	the -o
	      option if	specified, otherwise under the current directory.

	      If  .ext	is  specified, it will be used as the extension	on the
	      output files of the selected class, instead of the default based
	      on  the -S option	(if specified),	or the typesetting output for-
	      mat specified by the -T option.

	      For example, the following command will generate nroff(1)	 style
	      output under the /usr/local/man hierarchy, documenting functions
	      in section 3 (/usr/local/man/man3/*.3), global variables in sec-
	      tion  3v (/usr/local/man/man3/*.3v), static functions in section
	      9	(/usr/local/man/man9/*.9) and static variables in  section  9v

		   %  c2man  -o/usr/local/man  -v -s -Ofman3.3 -Ovman3.3v -OF-
		   man9.9 -OVman9.9v input.c

	      The -O options will have no effect if -o-	is used	 to  write  to
	      standard output, and -Ov,	-OF and	-OV will have no effect	unless
	      their classes of output are enabled via the appropriate  -v  and
	      -s options.

	      Set  the	format used to output the prototype for	functions with
	      more than	1 parameter in each manual page; functions  with  zero
	      or  1  parameters	 are always output as one line.	 The format is
	      specified	by a template in the form
	      "	int f (	a, b )"
	      but you may replace each space in	this string with any number of
	      whitespace characters.  For example, the option
	      -F"int f(\n\ta,\n\tb\n\t)"
	      int main(
		      int argc,
		      char *argv[]
	      int main
		      int argc,
		      char *argv[]

	      Run  a different C preprocessor than normal (use -V to determine
	      the configured default).	You must include any options  required
	      to prevent it from stripping comments, which is normally the de-
	      fault preprocessor behaviour.  For example, to use gcc's cpp in-

		   % c2man -P "gcc -E -C"

	      This option is passed through to the preprocessor	and is used to
	      define symbols for use with conditionals such as #ifdef.

       -Uname This option is passed through to the preprocessor	and is used to
	      remove any definitions of	this symbol.

	      This option is passed through to the preprocessor	and is used to
	      specify a	directory to search for	files that are referenced with

       -V     Print version information	and cpp	parameters.

	      A	few example input files, showing different commenting styles.

       man(1), apropos(1), catman(8), cproto(1), cc(1),	cpp(1)

       c2man's	error  messages	 are  not very helpful,	so make	sure your code
       compiles	before trying c2man.  If the code compiles OK  but  c2man  re-
       jects  it,  it may be because a comment is in a position	c2man does not
       accept, or you are using	a compiler extension not  strictly  conforming
       to  standard  C.	  c2man	defines	the preprocessor symbol	__C2MAN__ with
       its major version number	to allow you to	work around such  problems  by
       surrounding them	with #ifndef __C2MAN__.

       An  error  at the very end of a function	may indicate that the comments
       at the beginning	are badly placed.

       c2man was originally written by:

	    Graham Stoney
	    Canon Information Systems Research Australia
	    (please send bug reports here)

       Many thanks are due to the many other Internet contributors since then,
       and  to	Chin  Huang, the author	of cproto from which it	was originally

       The -F option only interprets the following character escape sequences:
       \n   newline
       \t   tab

       A comment before	a preprocessor directive will be considered  to	 apply
       to the identifier that immediately follows, if it has no	comment	of its
       own.  This is because the preprocessor directive	gets  removed  by  cpp
       before c2man looks at it.

       Comments	 aren't	legal in some of the more obscure places that they are
       in C.

       Heavy use of #define in a program may  yield  somewhat  obscure	manual

       c2man's	output backends	may not	be entirely consistent,	but then users
       of different formatters tend to have different tastes.

			       February	25, 2000		      C2MAN(1)


Want to link to this manual page? Use this URL:

home | help