c-main.template.doc

c_main - main written in C language

SYNOPSIS

       <mod>/src/<program>.c
       	    /test/<program>.c
      
       <mod>
	   |/ws/src/<program>.c
	   |   /test/<program>.c
	   |/lcu/src/<program>.c
		/test/<program>.c
 

DESCRIPTION

A main written in C language shall be written using the convention established in the "VLT-PRO-ESO-10000-0228, 1.0 10/03/93 VLT Software Programming Standards".

An empty template is provided by getTemplate(7) in the "code" menu. Complete the template according to the following instruction:

   /**********.. .  .
   * E.S.O. - VLT project
   *
   * <program_name>.c	   <<<<the file name shall be the same as the program!
   *
   * who       when	   what
   * --------  ----------  -------------------- 
   * NNNNNNNN  yyyy-mm-dd  created
   */|------------------| <<<<in the template these two fields are changed
			      according to the current value of username and date.


   >>>> the following is used to generate the "man page"<<<
   /** 
    * @addtogroup <exec_group_name> <title>	 >> define a group for all the executable of the module
    *  This is the group for module executables    >> give a decription of the content of the group
    */
 
   /**
    *  @defgroup <program_name>     >> define a group for the specific command
    *  @ingroup <exec_group_name>   >> this group will be part of the generale executable group of the module
    *  @{			    >> the following will be part of the group
    */

   /** 
    * @page <program_name>	 >> define the page of the command documentation
    * Short description of the command  >> give a  brief description of program
    *
    * @section Synopsis        >> open the section synopis
    * <program_name> [<par_1> [<par_2>  . . . [<par_n>]]] 
    *
    *    @param <par_1> <description and grammar rules for the first parameter>
    *		     ....................................
    *    @param <par_2> ....................................
    *    @param <par_n> <description and grammar rules for the n-th parameter>
    *     ................
    *
    *    @return <ret_value_1> <message> <diagnostic of the error>
    *				       .........................
    *    @return <ret_value_2> <message> .........................
    *    ................
    *
    *
    * @section Description	  >> open the section description
    *	<detailed explanation of the functionality> 
    *	...............................................
    *	...............................................
    *    @see (optional)
    *
    * @section Files	       >> open the section files
    *	<file_1>  <access> <meaning and purpose of the file>
    *				.................................
    *	<file_2>  <access> ....................................
    *	......
    * @section Environment  >> open the section  Environment
    *	<var_1>   <access> <meaning and purpose of the variable>
    *			   ....................................
    *	<var_2>   <access> ....................................
    *	......
    * @section Commands       >> open the section commands
    *	<Command_1>  brief description of the action performed 
    *			  .........................................
    *	<Command_2>  .........................................
    *	......
    * @section Cautions (optional)
    *	......
    *
    * @section Examples (optional)
    *	......
    *
    * @bug (optional)	>> if added, it will be added in the global bug list file generated by doxygen in the "related pages"
    *	......
    */
   /** @}*/

   
   #ifndef __vxworks   >>> predefined Macros Candidates: 
			   __vxworks #vxworks in general
			   _WRS_KERNEL #vxWorks kernel
			   __RTP__ # vxWorks application process (currently not used in VLT and can be replaced by 'defined(__vxworks) && !defined(_WRS_KERNEL)'
   #define _POSIX_C_SOURCE 1	<<<< if you delete this line you SHALL comment
				     why POSIX does not apply for this file
				     The purpose of the Macro is, to intentionally break the build if non agreed feature sets are used.
				     For Linux you might need to remove the settings in the case that intentionally non-Posix functions will be called by the sourcecode.
				     For VxWorks Kernel you might want to keep #define _POSIX... if you are sure that this sourcecode should not use any VxWorks specific functions
				     For VxWorks Application processes (currently not used by VLT) you can independently decide between allowing VxWorks extensions over Posix only
   #endif
   #include "vltPort.h"
				   >>>>do not change the following line<<<<
   ATTRIBUTE_UNUSED static const char *rcsId="@(#) $I>-<d$"; 
   /* 
    * System Headers 
    */  		  >>>Remember: system include SHALL be between <> <<<<
   #include <.....>		   /* ........ */  <<<<except for obvious files,
   #include <.....>		   /* ........ */      say why you need this include
   .......  
   
   /*
    * Local Headers 
    */  		  >>>Remember: local include SHALL be between "" <<<<
   #include "........." 	   /* ........ */  <<<<except for obvious files,
   #include "........." 	   /* ........ */      say why you need this include
   
   /* 
    * Signal catching functions  
    */
   .......
   .......
   .......
   
   /* 
    *Local functions  
    */
   .......
   .......
   .......
   
   
   /* 
    * Main
    */
   
   #ifndef DOXYGEN	     >>> if added the main code fragment will be ignored by Doxygen, 
                             >>>> and only the "man page" documentation from the group will be generated 
   int main (int argc, char *argv[])
   {
       .
       .
      code 
       .
       .
   }
   #endif /*!DOXYGEN*/
   
   /*___oOo___*/

 

Example

   /**
   * @addtogroup ModExec module name executables
   *  This is the group for module executables
   */

   /**
   *  @defgroup CommandName
   *  @ingroup ModExec
   *  @{
   */

   /** 
   * @page CommandPageName CommandName
   * short description of the command
   *
   * @section Synopsis
   * \e Command [-v] \<host\> \<command\> [\<params\>] [\<data\>]
   *
   *   @param -v enable verbose mode\n
   *
   *   @return 0 if everything OK
   *   @return 1 on error
   *
   *
   * @section Description
   * Description...
   *
   * @section Files
   * @section Environment
   * @section Examples
   */
   *   /** @}**/
 

Click here CommandName to see the generated documentation for a command