scripts/kernel-doc

   1 #!/usr/bin/perl -w
   2
   3 use strict;
   4
   5 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
   6 ## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
   7 ## Copyright (C) 2001  Simon Huggins                             ##
   8 ## Copyright (C) 2005-2012  Randy Dunlap                         ##
   9 ## Copyright (C) 2012  Dan Luedtke                               ##
  10 ##                                                               ##
  11 ## #define enhancements by Armin Kuster <akuster@mvista.com>     ##
  12 ## Copyright (c) 2000 MontaVista Software, Inc.                  ##
  13 ##                                                               ##
  14 ## This software falls under the GNU General Public License.     ##
  15 ## Please read the COPYING file for more information             ##
  16
  17 # 18/01/2001 -  Cleanups
  18 #               Functions prototyped as foo(void) same as foo()
  19 #               Stop eval'ing where we don't need to.
  20 # -- huggie@earth.li
  21
  22 # 27/06/2001 -  Allowed whitespace after initial "/**" and
  23 #               allowed comments before function declarations.
  24 # -- Christian Kreibich <ck@whoop.org>
  25
  26 # Still to do:
  27 #       - add perldoc documentation
  28 #       - Look more closely at some of the scarier bits :)
  29
  30 # 26/05/2001 -  Support for separate source and object trees.
  31 #               Return error code.
  32 #               Keith Owens <kaos@ocs.com.au>
  33
  34 # 23/09/2001 - Added support for typedefs, structs, enums and unions
  35 #              Support for Context section; can be terminated using empty line
  36 #              Small fixes (like spaces vs. \s in regex)
  37 # -- Tim Jansen <tim@tjansen.de>
  38
  39 # 25/07/2012 - Added support for HTML5
  40 # -- Dan Luedtke <mail@danrl.de>
  41
  42 #
  43 # This will read a 'c' file and scan for embedded comments in the
  44 # style of gnome comments (+minor extensions - see below).
  45 #
  46
  47 # Note: This only supports 'c'.
  48
  49 # usage:
  50 # kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
  51 #            [ -no-doc-sections ]
  52 #            [ -function funcname [ -function funcname ...] ]
  53 #            c file(s)s > outputfile
  54 # or
  55 #            [ -nofunction funcname [ -function funcname ...] ]
  56 #            c file(s)s > outputfile
  57 #
  58 #  Set output format using one of -docbook -html -html5 -text or -man.
  59 #  Default is man.
  60 #  The -list format is for internal use by docproc.
  61 #
  62 #  -no-doc-sections
  63 #       Do not output DOC: sections
  64 #
  65 #  -function funcname
  66 #       If set, then only generate documentation for the given function(s) or
  67 #       DOC: section titles.  All other functions and DOC: sections are ignored.
  68 #
  69 #  -nofunction funcname
  70 #       If set, then only generate documentation for the other function(s)/DOC:
  71 #       sections. Cannot be used together with -function (yes, that's a bug --
  72 #       perl hackers can fix it 8))
  73 #
  74 #  c files - list of 'c' files to process
  75 #
  76 #  All output goes to stdout, with errors to stderr.
  77
  78 #
  79 # format of comments.
  80 # In the following table, (...)? signifies optional structure.
  81 #                         (...)* signifies 0 or more structure elements
  82 # /**
  83 #  * function_name(:)? (- short description)?
  84 # (* @parameterx: (description of parameter x)?)*
  85 # (* a blank line)?
  86 #  * (Description:)? (Description of function)?
  87 #  * (section header: (section description)? )*
  88 #  (*)?*/
  89 #
  90 # So .. the trivial example would be:
  91 #
  92 # /**
  93 #  * my_function
  94 #  */
  95 #
  96 # If the Description: header tag is omitted, then there must be a blank line
  97 # after the last parameter specification.
  98 # e.g.
  99 # /**
 100 #  * my_function - does my stuff
 101 #  * @my_arg: its mine damnit
 102 #  *
 103 #  * Does my stuff explained.
 104 #  */
 105 #
 106 #  or, could also use:
 107 # /**
 108 #  * my_function - does my stuff
 109 #  * @my_arg: its mine damnit
 110 #  * Description: Does my stuff explained.
 111 #  */
 112 # etc.
 113 #
 114 # Besides functions you can also write documentation for structs, unions,
 115 # enums and typedefs. Instead of the function name you must write the name
 116 # of the declaration;  the struct/union/enum/typedef must always precede
 117 # the name. Nesting of declarations is not supported.
 118 # Use the argument mechanism to document members or constants.
 119 # e.g.
 120 # /**
 121 #  * struct my_struct - short description
 122 #  * @a: first member
 123 #  * @b: second member
 124 #  *
 125 #  * Longer description
 126 #  */
 127 # struct my_struct {
 128 #     int a;
 129 #     int b;
 130 # /* private: */
 131 #     int c;
 132 # };
 133 #
 134 # All descriptions can be multiline, except the short function description.
 135 #
 136 # You can also add additional sections. When documenting kernel functions you
 137 # should document the "Context:" of the function, e.g. whether the functions
 138 # can be called form interrupts. Unlike other sections you can end it with an
 139 # empty line.
 140 # Example-sections should contain the string EXAMPLE so that they are marked
 141 # appropriately in DocBook.
 142 #
 143 # Example:
 144 # /**
 145 #  * user_function - function that can only be called in user context
 146 #  * @a: some argument
 147 #  * Context: !in_interrupt()
 148 #  *
 149 #  * Some description
 150 #  * Example:
 151 #  *    user_function(22);
 152 #  */
 153 # ...
 154 #
 155 #
 156 # All descriptive text is further processed, scanning for the following special
 157 # patterns, which are highlighted appropriately.
 158 #
 159 # 'funcname()' - function
 160 # '$ENVVAR' - environmental variable
 161 # '&struct_name' - name of a structure (up to two words including 'struct')
 162 # '@parameter' - name of a parameter
 163 # '%CONST' - name of a constant.
 164
 165 ## init lots of data
 166
 167 my $errors = 0;
 168 my $warnings = 0;
 169 my $anon_struct_union = 0;
 170
 171 # match expressions used to find embedded type information
 172 my $type_constant = '\%([-_\w]+)';
 173 my $type_func = '(\w+)\(\)';
 174 my $type_param = '\@(\w+)';
 175 my $type_struct = '\&((struct\s*)*[_\w]+)';
 176 my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
 177 my $type_env = '(\$\w+)';
 178
 179 # Output conversion substitutions.
 180 #  One for each output format
 181
 182 # these work fairly well
 183 my %highlights_html = ( $type_constant, "<i>\$1</i>",
 184                         $type_func, "<b>\$1</b>",
 185                         $type_struct_xml, "<i>\$1</i>",
 186                         $type_env, "<b><i>\$1</i></b>",
 187                         $type_param, "<tt><b>\$1</b></tt>" );
 188 my $local_lt = "\\\\\\\\lt:";
 189 my $local_gt = "\\\\\\\\gt:";
 190 my $blankline_html = $local_lt . "p" . $local_gt;       # was "<p>"
 191
 192 # html version 5
 193 my %highlights_html5 = ( $type_constant, "<span class=\"const\">\$1</span>",
 194                         $type_func, "<span class=\"func\">\$1</span>",
 195                         $type_struct_xml, "<span class=\"struct\">\$1</span>",
 196                         $type_env, "<span class=\"env\">\$1</span>",
 197                         $type_param, "<span class=\"param\">\$1</span>" );
 198 my $blankline_html5 = $local_lt . "br /" . $local_gt;
 199
 200 # XML, docbook format
 201 my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
 202                         $type_constant, "<constant>\$1</constant>",
 203                         $type_func, "<function>\$1</function>",
 204                         $type_struct_xml, "<structname>\$1</structname>",
 205                         $type_env, "<envar>\$1</envar>",
 206                         $type_param, "<parameter>\$1</parameter>" );
 207 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
 208
 209 # gnome, docbook format
 210 my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
 211                          $type_func, "<function>\$1</function>",
 212                          $type_struct, "<structname>\$1</structname>",
 213                          $type_env, "<envar>\$1</envar>",
 214                          $type_param, "<parameter>\$1</parameter>" );
 215 my $blankline_gnome = "</para><para>\n";
 216
 217 # these are pretty rough
 218 my %highlights_man = ( $type_constant, "\$1",
 219                        $type_func, "\\\\fB\$1\\\\fP",
 220                        $type_struct, "\\\\fI\$1\\\\fP",
 221                        $type_param, "\\\\fI\$1\\\\fP" );
 222 my $blankline_man = "";
 223
 224 # text-mode
 225 my %highlights_text = ( $type_constant, "\$1",
 226                         $type_func, "\$1",
 227                         $type_struct, "\$1",
 228                         $type_param, "\$1" );
 229 my $blankline_text = "";
 230
 231 # list mode
 232 my %highlights_list = ( $type_constant, "\$1",
 233                         $type_func, "\$1",
 234                         $type_struct, "\$1",
 235                         $type_param, "\$1" );
 236 my $blankline_list = "";
 237
 238 # read arguments
 239 if ($#ARGV == -1) {
 240     usage();
 241 }
 242
 243 my $kernelversion;
 244 my $dohighlight = "";
 245
 246 my $verbose = 0;
 247 my $output_mode = "man";
 248 my $output_preformatted = 0;
 249 my $no_doc_sections = 0;
 250 my %highlights = %highlights_man;
 251 my $blankline = $blankline_man;
 252 my $modulename = "Kernel API";
 253 my $function_only = 0;
 254 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
 255                 'July', 'August', 'September', 'October',
 256                 'November', 'December')[(localtime)[4]] .
 257   " " . ((localtime)[5]+1900);
 258
 259 # Essentially these are globals.
 260 # They probably want to be tidied up, made more localised or something.
 261 # CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
 262 # could cause "use of undefined value" or other bugs.
 263 my ($function, %function_table, %parametertypes, $declaration_purpose);
 264 my ($type, $declaration_name, $return_type);
 265 my ($newsection, $newcontents, $prototype, $brcount, %source_map);
 266
 267 if (defined($ENV{'KBUILD_VERBOSE'})) {
 268         $verbose = "$ENV{'KBUILD_VERBOSE'}";
 269 }
 270
 271 # Generated docbook code is inserted in a template at a point where
 272 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
 273 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
 274 # We keep track of number of generated entries and generate a dummy
 275 # if needs be to ensure the expanded template can be postprocessed
 276 # into html.
 277 my $section_counter = 0;
 278
 279 my $lineprefix="";
 280
 281 # states
 282 # 0 - normal code
 283 # 1 - looking for function name
 284 # 2 - scanning field start.
 285 # 3 - scanning prototype.
 286 # 4 - documentation block
 287 my $state;
 288 my $in_doc_sect;
 289
 290 #declaration types: can be
 291 # 'function', 'struct', 'union', 'enum', 'typedef'
 292 my $decl_type;
 293
 294 my $doc_special = "\@\%\$\&";
 295
 296 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 297 my $doc_end = '\*/';
 298 my $doc_com = '\s*\*\s*';
 299 my $doc_com_body = '\s*\* ?';
 300 my $doc_decl = $doc_com . '(\w+)';
 301 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
 302 my $doc_content = $doc_com_body . '(.*)';
 303 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 304
 305 my %constants;
 306 my %parameterdescs;
 307 my @parameterlist;
 308 my %sections;
 309 my @sectionlist;
 310 my $sectcheck;
 311 my $struct_actual;
 312
 313 my $contents = "";
 314 my $section_default = "Description";    # default section
 315 my $section_intro = "Introduction";
 316 my $section = $section_default;
 317 my $section_context = "Context";
 318
 319 my $undescribed = "-- undescribed --";
 320
 321 reset_state();
 322
 323 while ($ARGV[0] =~ m/^-(.*)/) {
 324     my $cmd = shift @ARGV;
 325     if ($cmd eq "-html") {
 326         $output_mode = "html";
 327         %highlights = %highlights_html;
 328         $blankline = $blankline_html;
 329     } elsif ($cmd eq "-html5") {
 330         $output_mode = "html5";
 331         %highlights = %highlights_html5;
 332         $blankline = $blankline_html5;
 333     } elsif ($cmd eq "-man") {
 334         $output_mode = "man";
 335         %highlights = %highlights_man;
 336         $blankline = $blankline_man;
 337     } elsif ($cmd eq "-text") {
 338         $output_mode = "text";
 339         %highlights = %highlights_text;
 340         $blankline = $blankline_text;
 341     } elsif ($cmd eq "-docbook") {
 342         $output_mode = "xml";
 343         %highlights = %highlights_xml;
 344         $blankline = $blankline_xml;
 345     } elsif ($cmd eq "-list") {
 346         $output_mode = "list";
 347         %highlights = %highlights_list;
 348         $blankline = $blankline_list;
 349     } elsif ($cmd eq "-gnome") {
 350         $output_mode = "gnome";
 351         %highlights = %highlights_gnome;
 352         $blankline = $blankline_gnome;
 353     } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
 354         $modulename = shift @ARGV;
 355     } elsif ($cmd eq "-function") { # to only output specific functions
 356         $function_only = 1;
 357         $function = shift @ARGV;
 358         $function_table{$function} = 1;
 359     } elsif ($cmd eq "-nofunction") { # to only output specific functions
 360         $function_only = 2;
 361         $function = shift @ARGV;
 362         $function_table{$function} = 1;
 363     } elsif ($cmd eq "-v") {
 364         $verbose = 1;
 365     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
 366         usage();
 367     } elsif ($cmd eq '-no-doc-sections') {
 368             $no_doc_sections = 1;
 369     }
 370 }
 371
 372 # continue execution near EOF;
 373
 374 sub usage {
 375     print "Usage: $0 [ -docbook | -html | -html5 | -text | -man | -list ]\n";
 376     print "         [ -no-doc-sections ]\n";
 377     print "         [ -function funcname [ -function funcname ...] ]\n";
 378     print "         [ -nofunction funcname [ -nofunction funcname ...] ]\n";
 379     print "         [ -v ]\n";
 380     print "         c source file(s) > outputfile\n";
 381     print "         -v : verbose output, more warnings & other info listed\n";
 382     exit 1;
 383 }
 384
 385 # get kernel version from env
 386 sub get_kernel_version() {
 387     my $version = 'unknown kernel version';
 388
 389     if (defined($ENV{'KERNELVERSION'})) {
 390         $version = $ENV{'KERNELVERSION'};
 391     }
 392     return $version;
 393 }
 394
 395 ##
 396 # dumps section contents to arrays/hashes intended for that purpose.
 397 #
 398 sub dump_section {
 399     my $file = shift;
 400     my $name = shift;
 401     my $contents = join "\n", @_;
 402
 403     if ($name =~ m/$type_constant/) {
 404         $name = $1;
 405 #       print STDERR "constant section '$1' = '$contents'\n";
 406         $constants{$name} = $contents;
 407     } elsif ($name =~ m/$type_param/) {
 408 #       print STDERR "parameter def '$1' = '$contents'\n";
 409         $name = $1;
 410         $parameterdescs{$name} = $contents;
 411         $sectcheck = $sectcheck . $name . " ";
 412     } elsif ($name eq "@\.\.\.") {
 413 #       print STDERR "parameter def '...' = '$contents'\n";
 414         $name = "...";
 415         $parameterdescs{$name} = $contents;
 416         $sectcheck = $sectcheck . $name . " ";
 417     } else {
 418 #       print STDERR "other section '$name' = '$contents'\n";
 419         if (defined($sections{$name}) && ($sections{$name} ne "")) {
 420                 print STDERR "Error(${file}:$.): duplicate section name '$name'\n";
 421                 ++$errors;
 422         }
 423         $sections{$name} = $contents;
 424         push @sectionlist, $name;
 425     }
 426 }
 427
 428 ##
 429 # dump DOC: section after checking that it should go out
 430 #
 431 sub dump_doc_section {
 432     my $file = shift;
 433     my $name = shift;
 434     my $contents = join "\n", @_;
 435
 436     if ($no_doc_sections) {
 437         return;
 438     }
 439
 440     if (($function_only == 0) ||
 441         ( $function_only == 1 && defined($function_table{$name})) ||
 442         ( $function_only == 2 && !defined($function_table{$name})))
 443     {
 444         dump_section($file, $name, $contents);
 445         output_blockhead({'sectionlist' => \@sectionlist,
 446                           'sections' => \%sections,
 447                           'module' => $modulename,
 448                           'content-only' => ($function_only != 0), });
 449     }
 450 }
 451
 452 ##
 453 # output function
 454 #
 455 # parameterdescs, a hash.
 456 #  function => "function name"
 457 #  parameterlist => @list of parameters
 458 #  parameterdescs => %parameter descriptions
 459 #  sectionlist => @list of sections
 460 #  sections => %section descriptions
 461 #
 462
 463 sub output_highlight {
 464     my $contents = join "\n",@_;
 465     my $line;
 466
 467 #   DEBUG
 468 #   if (!defined $contents) {
 469 #       use Carp;
 470 #       confess "output_highlight got called with no args?\n";
 471 #   }
 472
 473     if ($output_mode eq "html" || $output_mode eq "html5" ||
 474         $output_mode eq "xml") {
 475         $contents = local_unescape($contents);
 476         # convert data read & converted thru xml_escape() into &xyz; format:
 477         $contents =~ s/\\\\\\/\&/g;
 478     }
 479 #   print STDERR "contents b4:$contents\n";
 480     eval $dohighlight;
 481     die $@ if $@;
 482 #   print STDERR "contents af:$contents\n";
 483
 484 #   strip whitespaces when generating html5
 485     if ($output_mode eq "html5") {
 486         $contents =~ s/^\s+//;
 487         $contents =~ s/\s+$//;
 488     }
 489     foreach $line (split "\n", $contents) {
 490         if (! $output_preformatted) {
 491             $line =~ s/^\s*//;
 492         }
 493         if ($line eq ""){
 494             if (! $output_preformatted) {
 495                 print $lineprefix, local_unescape($blankline);
 496             }
 497         } else {
 498             $line =~ s/\\\\\\/\&/g;
 499             if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
 500                 print "\\&$line";
 501             } else {
 502                 print $lineprefix, $line;
 503             }
 504         }
 505         print "\n";
 506     }
 507 }
 508
 509 # output sections in html
 510 sub output_section_html(%) {
 511     my %args = %{$_[0]};
 512     my $section;
 513
 514     foreach $section (@{$args{'sectionlist'}}) {
 515         print "<h3>$section</h3>\n";
 516         print "<blockquote>\n";
 517         output_highlight($args{'sections'}{$section});
 518         print "</blockquote>\n";
 519     }
 520 }
 521
 522 # output enum in html
 523 sub output_enum_html(%) {
 524     my %args = %{$_[0]};
 525     my ($parameter);
 526     my $count;
 527     print "<h2>enum " . $args{'enum'} . "</h2>\n";
 528
 529     print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
 530     $count = 0;
 531     foreach $parameter (@{$args{'parameterlist'}}) {
 532         print " <b>" . $parameter . "</b>";
 533         if ($count != $#{$args{'parameterlist'}}) {
 534             $count++;
 535             print ",\n";
 536         }
 537         print "<br>";
 538     }
 539     print "};<br>\n";
 540
 541     print "<h3>Constants</h3>\n";
 542     print "<dl>\n";
 543     foreach $parameter (@{$args{'parameterlist'}}) {
 544         print "<dt><b>" . $parameter . "</b>\n";
 545         print "<dd>";
 546         output_highlight($args{'parameterdescs'}{$parameter});
 547     }
 548     print "</dl>\n";
 549     output_section_html(@_);
 550     print "<hr>\n";
 551 }
 552
 553 # output typedef in html
 554 sub output_typedef_html(%) {
 555     my %args = %{$_[0]};
 556     my ($parameter);
 557     my $count;
 558     print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
 559
 560     print "<b>typedef " . $args{'typedef'} . "</b>\n";
 561     output_section_html(@_);
 562     print "<hr>\n";
 563 }
 564
 565 # output struct in html
 566 sub output_struct_html(%) {
 567     my %args = %{$_[0]};
 568     my ($parameter);
 569
 570     print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
 571     print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
 572     foreach $parameter (@{$args{'parameterlist'}}) {
 573         if ($parameter =~ /^#/) {
 574                 print "$parameter<br>\n";
 575                 next;
 576         }
 577         my $parameter_name = $parameter;
 578         $parameter_name =~ s/\[.*//;
 579
 580         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 581         $type = $args{'parametertypes'}{$parameter};
 582         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 583             # pointer-to-function
 584             print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
 585         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 586             # bitfield
 587             print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
 588         } else {
 589             print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
 590         }
 591     }
 592     print "};<br>\n";
 593
 594     print "<h3>Members</h3>\n";
 595     print "<dl>\n";
 596     foreach $parameter (@{$args{'parameterlist'}}) {
 597         ($parameter =~ /^#/) && next;
 598
 599         my $parameter_name = $parameter;
 600         $parameter_name =~ s/\[.*//;
 601
 602         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 603         print "<dt><b>" . $parameter . "</b>\n";
 604         print "<dd>";
 605         output_highlight($args{'parameterdescs'}{$parameter_name});
 606     }
 607     print "</dl>\n";
 608     output_section_html(@_);
 609     print "<hr>\n";
 610 }
 611
 612 # output function in html
 613 sub output_function_html(%) {
 614     my %args = %{$_[0]};
 615     my ($parameter, $section);
 616     my $count;
 617
 618     print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
 619     print "<i>" . $args{'functiontype'} . "</i>\n";
 620     print "<b>" . $args{'function'} . "</b>\n";
 621     print "(";
 622     $count = 0;
 623     foreach $parameter (@{$args{'parameterlist'}}) {
 624         $type = $args{'parametertypes'}{$parameter};
 625         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 626             # pointer-to-function
 627             print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
 628         } else {
 629             print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
 630         }
 631         if ($count != $#{$args{'parameterlist'}}) {
 632             $count++;
 633             print ",\n";
 634         }
 635     }
 636     print ")\n";
 637
 638     print "<h3>Arguments</h3>\n";
 639     print "<dl>\n";
 640     foreach $parameter (@{$args{'parameterlist'}}) {
 641         my $parameter_name = $parameter;
 642         $parameter_name =~ s/\[.*//;
 643
 644         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 645         print "<dt><b>" . $parameter . "</b>\n";
 646         print "<dd>";
 647         output_highlight($args{'parameterdescs'}{$parameter_name});
 648     }
 649     print "</dl>\n";
 650     output_section_html(@_);
 651     print "<hr>\n";
 652 }
 653
 654 # output DOC: block header in html
 655 sub output_blockhead_html(%) {
 656     my %args = %{$_[0]};
 657     my ($parameter, $section);
 658     my $count;
 659
 660     foreach $section (@{$args{'sectionlist'}}) {
 661         print "<h3>$section</h3>\n";
 662         print "<ul>\n";
 663         output_highlight($args{'sections'}{$section});
 664         print "</ul>\n";
 665     }
 666     print "<hr>\n";
 667 }
 668
 669 # output sections in html5
 670 sub output_section_html5(%) {
 671     my %args = %{$_[0]};
 672     my $section;
 673
 674     foreach $section (@{$args{'sectionlist'}}) {
 675         print "<section>\n";
 676         print "<h1>$section</h1>\n";
 677         print "<p>\n";
 678         output_highlight($args{'sections'}{$section});
 679         print "</p>\n";
 680         print "</section>\n";
 681     }
 682 }
 683
 684 # output enum in html5
 685 sub output_enum_html5(%) {
 686     my %args = %{$_[0]};
 687     my ($parameter);
 688     my $count;
 689     my $html5id;
 690
 691     $html5id = $args{'enum'};
 692     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
 693     print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
 694     print "<h1>enum " . $args{'enum'} . "</h1>\n";
 695     print "<ol class=\"code\">\n";
 696     print "<li>";
 697     print "<span class=\"keyword\">enum</span> ";
 698     print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
 699     print "</li>\n";
 700     $count = 0;
 701     foreach $parameter (@{$args{'parameterlist'}}) {
 702         print "<li class=\"indent\">";
 703         print "<span class=\"param\">" . $parameter . "</span>";
 704         if ($count != $#{$args{'parameterlist'}}) {
 705             $count++;
 706             print ",";
 707         }
 708         print "</li>\n";
 709     }
 710     print "<li>};</li>\n";
 711     print "</ol>\n";
 712
 713     print "<section>\n";
 714     print "<h1>Constants</h1>\n";
 715     print "<dl>\n";
 716     foreach $parameter (@{$args{'parameterlist'}}) {
 717         print "<dt>" . $parameter . "</dt>\n";
 718         print "<dd>";
 719         output_highlight($args{'parameterdescs'}{$parameter});
 720         print "</dd>\n";
 721     }
 722     print "</dl>\n";
 723     print "</section>\n";
 724     output_section_html5(@_);
 725     print "</article>\n";
 726 }
 727
 728 # output typedef in html5
 729 sub output_typedef_html5(%) {
 730     my %args = %{$_[0]};
 731     my ($parameter);
 732     my $count;
 733     my $html5id;
 734
 735     $html5id = $args{'typedef'};
 736     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
 737     print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
 738     print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
 739
 740     print "<ol class=\"code\">\n";
 741     print "<li>";
 742     print "<span class=\"keyword\">typedef</span> ";
 743     print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
 744     print "</li>\n";
 745     print "</ol>\n";
 746     output_section_html5(@_);
 747     print "</article>\n";
 748 }
 749
 750 # output struct in html5
 751 sub output_struct_html5(%) {
 752     my %args = %{$_[0]};
 753     my ($parameter);
 754     my $html5id;
 755
 756     $html5id = $args{'struct'};
 757     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
 758     print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
 759     print "<hgroup>\n";
 760     print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
 761     print "<h2>". $args{'purpose'} . "</h2>\n";
 762     print "</hgroup>\n";
 763     print "<ol class=\"code\">\n";
 764     print "<li>";
 765     print "<span class=\"type\">" . $args{'type'} . "</span> ";
 766     print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
 767     print "</li>\n";
 768     foreach $parameter (@{$args{'parameterlist'}}) {
 769         print "<li class=\"indent\">";
 770         if ($parameter =~ /^#/) {
 771                 print "<span class=\"param\">" . $parameter ."</span>\n";
 772                 print "</li>\n";
 773                 next;
 774         }
 775         my $parameter_name = $parameter;
 776         $parameter_name =~ s/\[.*//;
 777
 778         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 779         $type = $args{'parametertypes'}{$parameter};
 780         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 781             # pointer-to-function
 782             print "<span class=\"type\">$1</span> ";
 783             print "<span class=\"param\">$parameter</span>";
 784             print "<span class=\"type\">)</span> ";
 785             print "(<span class=\"args\">$2</span>);";
 786         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 787             # bitfield
 788             print "<span class=\"type\">$1</span> ";
 789             print "<span class=\"param\">$parameter</span>";
 790             print "<span class=\"bits\">$2</span>;";
 791         } else {
 792             print "<span class=\"type\">$type</span> ";
 793             print "<span class=\"param\">$parameter</span>;";
 794         }
 795         print "</li>\n";
 796     }
 797     print "<li>};</li>\n";
 798     print "</ol>\n";
 799
 800     print "<section>\n";
 801     print "<h1>Members</h1>\n";
 802     print "<dl>\n";
 803     foreach $parameter (@{$args{'parameterlist'}}) {
 804         ($parameter =~ /^#/) && next;
 805
 806         my $parameter_name = $parameter;
 807         $parameter_name =~ s/\[.*//;
 808
 809         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 810         print "<dt>" . $parameter . "</dt>\n";
 811         print "<dd>";
 812         output_highlight($args{'parameterdescs'}{$parameter_name});
 813         print "</dd>\n";
 814     }
 815     print "</dl>\n";
 816     print "</section>\n";
 817     output_section_html5(@_);
 818     print "</article>\n";
 819 }
 820
 821 # output function in html5
 822 sub output_function_html5(%) {
 823     my %args = %{$_[0]};
 824     my ($parameter, $section);
 825     my $count;
 826     my $html5id;
 827
 828     $html5id = $args{'function'};
 829     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
 830     print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
 831     print "<hgroup>\n";
 832     print "<h1>" . $args{'function'} . "</h1>";
 833     print "<h2>" . $args{'purpose'} . "</h2>\n";
 834     print "</hgroup>\n";
 835     print "<ol class=\"code\">\n";
 836     print "<li>";
 837     print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
 838     print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
 839     print "</li>";
 840     $count = 0;
 841     foreach $parameter (@{$args{'parameterlist'}}) {
 842         print "<li class=\"indent\">";
 843         $type = $args{'parametertypes'}{$parameter};
 844         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 845             # pointer-to-function
 846             print "<span class=\"type\">$1</span> ";
 847             print "<span class=\"param\">$parameter</span>";
 848             print "<span class=\"type\">)</span> ";
 849             print "(<span class=\"args\">$2</span>)";
 850         } else {
 851             print "<span class=\"type\">$type</span> ";
 852             print "<span class=\"param\">$parameter</span>";
 853         }
 854         if ($count != $#{$args{'parameterlist'}}) {
 855             $count++;
 856             print ",";
 857         }
 858         print "</li>\n";
 859     }
 860     print "<li>)</li>\n";
 861     print "</ol>\n";
 862
 863     print "<section>\n";
 864     print "<h1>Arguments</h1>\n";
 865     print "<p>\n";
 866     print "<dl>\n";
 867     foreach $parameter (@{$args{'parameterlist'}}) {
 868         my $parameter_name = $parameter;
 869         $parameter_name =~ s/\[.*//;
 870
 871         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 872         print "<dt>" . $parameter . "</dt>\n";
 873         print "<dd>";
 874         output_highlight($args{'parameterdescs'}{$parameter_name});
 875         print "</dd>\n";
 876     }
 877     print "</dl>\n";
 878     print "</section>\n";
 879     output_section_html5(@_);
 880     print "</article>\n";
 881 }
 882
 883 # output DOC: block header in html5
 884 sub output_blockhead_html5(%) {
 885     my %args = %{$_[0]};
 886     my ($parameter, $section);
 887     my $count;
 888     my $html5id;
 889
 890     foreach $section (@{$args{'sectionlist'}}) {
 891         $html5id = $section;
 892         $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
 893         print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
 894         print "<h1>$section</h1>\n";
 895         print "<p>\n";
 896         output_highlight($args{'sections'}{$section});
 897         print "</p>\n";
 898     }
 899     print "</article>\n";
 900 }
 901
 902 sub output_section_xml(%) {
 903     my %args = %{$_[0]};
 904     my $section;
 905     # print out each section
 906     $lineprefix="   ";
 907     foreach $section (@{$args{'sectionlist'}}) {
 908         print "<refsect1>\n";
 909         print "<title>$section</title>\n";
 910         if ($section =~ m/EXAMPLE/i) {
 911             print "<informalexample><programlisting>\n";
 912             $output_preformatted = 1;
 913         } else {
 914             print "<para>\n";
 915         }
 916         output_highlight($args{'sections'}{$section});
 917         $output_preformatted = 0;
 918         if ($section =~ m/EXAMPLE/i) {
 919             print "</programlisting></informalexample>\n";
 920         } else {
 921             print "</para>\n";
 922         }
 923         print "</refsect1>\n";
 924     }
 925 }
 926
 927 # output function in XML DocBook
 928 sub output_function_xml(%) {
 929     my %args = %{$_[0]};
 930     my ($parameter, $section);
 931     my $count;
 932     my $id;
 933
 934     $id = "API-" . $args{'function'};
 935     $id =~ s/[^A-Za-z0-9]/-/g;
 936
 937     print "<refentry id=\"$id\">\n";
 938     print "<refentryinfo>\n";
 939     print " <title>LINUX</title>\n";
 940     print " <productname>Kernel Hackers Manual</productname>\n";
 941     print " <date>$man_date</date>\n";
 942     print "</refentryinfo>\n";
 943     print "<refmeta>\n";
 944     print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
 945     print " <manvolnum>9</manvolnum>\n";
 946     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
 947     print "</refmeta>\n";
 948     print "<refnamediv>\n";
 949     print " <refname>" . $args{'function'} . "</refname>\n";
 950     print " <refpurpose>\n";
 951     print "  ";
 952     output_highlight ($args{'purpose'});
 953     print " </refpurpose>\n";
 954     print "</refnamediv>\n";
 955
 956     print "<refsynopsisdiv>\n";
 957     print " <title>Synopsis</title>\n";
 958     print "  <funcsynopsis><funcprototype>\n";
 959     print "   <funcdef>" . $args{'functiontype'} . " ";
 960     print "<function>" . $args{'function'} . " </function></funcdef>\n";
 961
 962     $count = 0;
 963     if ($#{$args{'parameterlist'}} >= 0) {
 964         foreach $parameter (@{$args{'parameterlist'}}) {
 965             $type = $args{'parametertypes'}{$parameter};
 966             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 967                 # pointer-to-function
 968                 print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
 969                 print "     <funcparams>$2</funcparams></paramdef>\n";
 970             } else {
 971                 print "   <paramdef>" . $type;
 972                 print " <parameter>$parameter</parameter></paramdef>\n";
 973             }
 974         }
 975     } else {
 976         print "  <void/>\n";
 977     }
 978     print "  </funcprototype></funcsynopsis>\n";
 979     print "</refsynopsisdiv>\n";
 980
 981     # print parameters
 982     print "<refsect1>\n <title>Arguments</title>\n";
 983     if ($#{$args{'parameterlist'}} >= 0) {
 984         print " <variablelist>\n";
 985         foreach $parameter (@{$args{'parameterlist'}}) {
 986             my $parameter_name = $parameter;
 987             $parameter_name =~ s/\[.*//;
 988
 989             print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
 990             print "   <listitem>\n    <para>\n";
 991             $lineprefix="     ";
 992             output_highlight($args{'parameterdescs'}{$parameter_name});
 993             print "    </para>\n   </listitem>\n  </varlistentry>\n";
 994         }
 995         print " </variablelist>\n";
 996     } else {
 997         print " <para>\n  None\n </para>\n";
 998     }
 999     print "</refsect1>\n";
1000
1001     output_section_xml(@_);
1002     print "</refentry>\n\n";
1003 }
1004
1005 # output struct in XML DocBook
1006 sub output_struct_xml(%) {
1007     my %args = %{$_[0]};
1008     my ($parameter, $section);
1009     my $id;
1010
1011     $id = "API-struct-" . $args{'struct'};
1012     $id =~ s/[^A-Za-z0-9]/-/g;
1013
1014     print "<refentry id=\"$id\">\n";
1015     print "<refentryinfo>\n";
1016     print " <title>LINUX</title>\n";
1017     print " <productname>Kernel Hackers Manual</productname>\n";
1018     print " <date>$man_date</date>\n";
1019     print "</refentryinfo>\n";
1020     print "<refmeta>\n";
1021     print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
1022     print " <manvolnum>9</manvolnum>\n";
1023     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1024     print "</refmeta>\n";
1025     print "<refnamediv>\n";
1026     print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
1027     print " <refpurpose>\n";
1028     print "  ";
1029     output_highlight ($args{'purpose'});
1030     print " </refpurpose>\n";
1031     print "</refnamediv>\n";
1032
1033     print "<refsynopsisdiv>\n";
1034     print " <title>Synopsis</title>\n";
1035     print "  <programlisting>\n";
1036     print $args{'type'} . " " . $args{'struct'} . " {\n";
1037     foreach $parameter (@{$args{'parameterlist'}}) {
1038         if ($parameter =~ /^#/) {
1039             my $prm = $parameter;
1040             # convert data read & converted thru xml_escape() into &xyz; format:
1041             # This allows us to have #define macros interspersed in a struct.
1042             $prm =~ s/\\\\\\/\&/g;
1043             print "$prm\n";
1044             next;
1045         }
1046
1047         my $parameter_name = $parameter;
1048         $parameter_name =~ s/\[.*//;
1049
1050         defined($args{'parameterdescs'}{$parameter_name}) || next;
1051         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1052         $type = $args{'parametertypes'}{$parameter};
1053         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1054             # pointer-to-function
1055             print "  $1 $parameter) ($2);\n";
1056         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1057             # bitfield
1058             print "  $1 $parameter$2;\n";
1059         } else {
1060             print "  " . $type . " " . $parameter . ";\n";
1061         }
1062     }
1063     print "};";
1064     print "  </programlisting>\n";
1065     print "</refsynopsisdiv>\n";
1066
1067     print " <refsect1>\n";
1068     print "  <title>Members</title>\n";
1069
1070     if ($#{$args{'parameterlist'}} >= 0) {
1071     print "  <variablelist>\n";
1072     foreach $parameter (@{$args{'parameterlist'}}) {
1073       ($parameter =~ /^#/) && next;
1074
1075       my $parameter_name = $parameter;
1076       $parameter_name =~ s/\[.*//;
1077
1078       defined($args{'parameterdescs'}{$parameter_name}) || next;
1079       ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1080       print "    <varlistentry>";
1081       print "      <term>$parameter</term>\n";
1082       print "      <listitem><para>\n";
1083       output_highlight($args{'parameterdescs'}{$parameter_name});
1084       print "      </para></listitem>\n";
1085       print "    </varlistentry>\n";
1086     }
1087     print "  </variablelist>\n";
1088     } else {
1089         print " <para>\n  None\n </para>\n";
1090     }
1091     print " </refsect1>\n";
1092
1093     output_section_xml(@_);
1094
1095     print "</refentry>\n\n";
1096 }
1097
1098 # output enum in XML DocBook
1099 sub output_enum_xml(%) {
1100     my %args = %{$_[0]};
1101     my ($parameter, $section);
1102     my $count;
1103     my $id;
1104
1105     $id = "API-enum-" . $args{'enum'};
1106     $id =~ s/[^A-Za-z0-9]/-/g;
1107
1108     print "<refentry id=\"$id\">\n";
1109     print "<refentryinfo>\n";
1110     print " <title>LINUX</title>\n";
1111     print " <productname>Kernel Hackers Manual</productname>\n";
1112     print " <date>$man_date</date>\n";
1113     print "</refentryinfo>\n";
1114     print "<refmeta>\n";
1115     print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
1116     print " <manvolnum>9</manvolnum>\n";
1117     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1118     print "</refmeta>\n";
1119     print "<refnamediv>\n";
1120     print " <refname>enum " . $args{'enum'} . "</refname>\n";
1121     print " <refpurpose>\n";
1122     print "  ";
1123     output_highlight ($args{'purpose'});
1124     print " </refpurpose>\n";
1125     print "</refnamediv>\n";
1126
1127     print "<refsynopsisdiv>\n";
1128     print " <title>Synopsis</title>\n";
1129     print "  <programlisting>\n";
1130     print "enum " . $args{'enum'} . " {\n";
1131     $count = 0;
1132     foreach $parameter (@{$args{'parameterlist'}}) {
1133         print "  $parameter";
1134         if ($count != $#{$args{'parameterlist'}}) {
1135             $count++;
1136             print ",";
1137         }
1138         print "\n";
1139     }
1140     print "};";
1141     print "  </programlisting>\n";
1142     print "</refsynopsisdiv>\n";
1143
1144     print "<refsect1>\n";
1145     print " <title>Constants</title>\n";
1146     print "  <variablelist>\n";
1147     foreach $parameter (@{$args{'parameterlist'}}) {
1148       my $parameter_name = $parameter;
1149       $parameter_name =~ s/\[.*//;
1150
1151       print "    <varlistentry>";
1152       print "      <term>$parameter</term>\n";
1153       print "      <listitem><para>\n";
1154       output_highlight($args{'parameterdescs'}{$parameter_name});
1155       print "      </para></listitem>\n";
1156       print "    </varlistentry>\n";
1157     }
1158     print "  </variablelist>\n";
1159     print "</refsect1>\n";
1160
1161     output_section_xml(@_);
1162
1163     print "</refentry>\n\n";
1164 }
1165
1166 # output typedef in XML DocBook
1167 sub output_typedef_xml(%) {
1168     my %args = %{$_[0]};
1169     my ($parameter, $section);
1170     my $id;
1171
1172     $id = "API-typedef-" . $args{'typedef'};
1173     $id =~ s/[^A-Za-z0-9]/-/g;
1174
1175     print "<refentry id=\"$id\">\n";
1176     print "<refentryinfo>\n";
1177     print " <title>LINUX</title>\n";
1178     print " <productname>Kernel Hackers Manual</productname>\n";
1179     print " <date>$man_date</date>\n";
1180     print "</refentryinfo>\n";
1181     print "<refmeta>\n";
1182     print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
1183     print " <manvolnum>9</manvolnum>\n";
1184     print "</refmeta>\n";
1185     print "<refnamediv>\n";
1186     print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
1187     print " <refpurpose>\n";
1188     print "  ";
1189     output_highlight ($args{'purpose'});
1190     print " </refpurpose>\n";
1191     print "</refnamediv>\n";
1192
1193     print "<refsynopsisdiv>\n";
1194     print " <title>Synopsis</title>\n";
1195     print "  <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
1196     print "</refsynopsisdiv>\n";
1197
1198     output_section_xml(@_);
1199
1200     print "</refentry>\n\n";
1201 }
1202
1203 # output in XML DocBook
1204 sub output_blockhead_xml(%) {
1205     my %args = %{$_[0]};
1206     my ($parameter, $section);
1207     my $count;
1208
1209     my $id = $args{'module'};
1210     $id =~ s/[^A-Za-z0-9]/-/g;
1211
1212     # print out each section
1213     $lineprefix="   ";
1214     foreach $section (@{$args{'sectionlist'}}) {
1215         if (!$args{'content-only'}) {
1216                 print "<refsect1>\n <title>$section</title>\n";
1217         }
1218         if ($section =~ m/EXAMPLE/i) {
1219             print "<example><para>\n";
1220             $output_preformatted = 1;
1221         } else {
1222             print "<para>\n";
1223         }
1224         output_highlight($args{'sections'}{$section});
1225         $output_preformatted = 0;
1226         if ($section =~ m/EXAMPLE/i) {
1227             print "</para></example>\n";
1228         } else {
1229             print "</para>";
1230         }
1231         if (!$args{'content-only'}) {
1232                 print "\n</refsect1>\n";
1233         }
1234     }
1235
1236     print "\n\n";
1237 }
1238
1239 # output in XML DocBook
1240 sub output_function_gnome {
1241     my %args = %{$_[0]};
1242     my ($parameter, $section);
1243     my $count;
1244     my $id;
1245
1246     $id = $args{'module'} . "-" . $args{'function'};
1247     $id =~ s/[^A-Za-z0-9]/-/g;
1248
1249     print "<sect2>\n";
1250     print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
1251
1252     print "  <funcsynopsis>\n";
1253     print "   <funcdef>" . $args{'functiontype'} . " ";
1254     print "<function>" . $args{'function'} . " ";
1255     print "</function></funcdef>\n";
1256
1257     $count = 0;
1258     if ($#{$args{'parameterlist'}} >= 0) {
1259         foreach $parameter (@{$args{'parameterlist'}}) {
1260             $type = $args{'parametertypes'}{$parameter};
1261             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1262                 # pointer-to-function
1263                 print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
1264                 print "     <funcparams>$2</funcparams></paramdef>\n";
1265             } else {
1266                 print "   <paramdef>" . $type;
1267                 print " <parameter>$parameter</parameter></paramdef>\n";
1268             }
1269         }
1270     } else {
1271         print "  <void>\n";
1272     }
1273     print "  </funcsynopsis>\n";
1274     if ($#{$args{'parameterlist'}} >= 0) {
1275         print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
1276         print "<tgroup cols=\"2\">\n";
1277         print "<colspec colwidth=\"2*\">\n";
1278         print "<colspec colwidth=\"8*\">\n";
1279         print "<tbody>\n";
1280         foreach $parameter (@{$args{'parameterlist'}}) {
1281             my $parameter_name = $parameter;
1282             $parameter_name =~ s/\[.*//;
1283
1284             print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
1285             print "   <entry>\n";
1286             $lineprefix="     ";
1287             output_highlight($args{'parameterdescs'}{$parameter_name});
1288             print "    </entry></row>\n";
1289         }
1290         print " </tbody></tgroup></informaltable>\n";
1291     } else {
1292         print " <para>\n  None\n </para>\n";
1293     }
1294
1295     # print out each section
1296     $lineprefix="   ";
1297     foreach $section (@{$args{'sectionlist'}}) {
1298         print "<simplesect>\n <title>$section</title>\n";
1299         if ($section =~ m/EXAMPLE/i) {
1300             print "<example><programlisting>\n";
1301             $output_preformatted = 1;
1302         } else {
1303         }
1304         print "<para>\n";
1305         output_highlight($args{'sections'}{$section});
1306         $output_preformatted = 0;
1307         print "</para>\n";
1308         if ($section =~ m/EXAMPLE/i) {
1309             print "</programlisting></example>\n";
1310         } else {
1311         }
1312         print " </simplesect>\n";
1313     }
1314
1315     print "</sect2>\n\n";
1316 }
1317
1318 ##
1319 # output function in man
1320 sub output_function_man(%) {
1321     my %args = %{$_[0]};
1322     my ($parameter, $section);
1323     my $count;
1324
1325     print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
1326
1327     print ".SH NAME\n";
1328     print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
1329
1330     print ".SH SYNOPSIS\n";
1331     if ($args{'functiontype'} ne "") {
1332         print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
1333     } else {
1334         print ".B \"" . $args{'function'} . "\n";
1335     }
1336     $count = 0;
1337     my $parenth = "(";
1338     my $post = ",";
1339     foreach my $parameter (@{$args{'parameterlist'}}) {
1340         if ($count == $#{$args{'parameterlist'}}) {
1341             $post = ");";
1342         }
1343         $type = $args{'parametertypes'}{$parameter};
1344         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1345             # pointer-to-function
1346             print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
1347         } else {
1348             $type =~ s/([^\*])$/$1 /;
1349             print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
1350         }
1351         $count++;
1352         $parenth = "";
1353     }
1354
1355     print ".SH ARGUMENTS\n";
1356     foreach $parameter (@{$args{'parameterlist'}}) {
1357         my $parameter_name = $parameter;
1358         $parameter_name =~ s/\[.*//;
1359
1360         print ".IP \"" . $parameter . "\" 12\n";
1361         output_highlight($args{'parameterdescs'}{$parameter_name});
1362     }
1363     foreach $section (@{$args{'sectionlist'}}) {
1364         print ".SH \"", uc $section, "\"\n";
1365         output_highlight($args{'sections'}{$section});
1366     }
1367 }
1368
1369 ##
1370 # output enum in man
1371 sub output_enum_man(%) {
1372     my %args = %{$_[0]};
1373     my ($parameter, $section);
1374     my $count;
1375
1376     print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1377
1378     print ".SH NAME\n";
1379     print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
1380
1381     print ".SH SYNOPSIS\n";
1382     print "enum " . $args{'enum'} . " {\n";
1383     $count = 0;
1384     foreach my $parameter (@{$args{'parameterlist'}}) {
1385         print ".br\n.BI \"    $parameter\"\n";
1386         if ($count == $#{$args{'parameterlist'}}) {
1387             print "\n};\n";
1388             last;
1389         }
1390         else {
1391             print ", \n.br\n";
1392         }
1393         $count++;
1394     }
1395
1396     print ".SH Constants\n";
1397     foreach $parameter (@{$args{'parameterlist'}}) {
1398         my $parameter_name = $parameter;
1399         $parameter_name =~ s/\[.*//;
1400
1401         print ".IP \"" . $parameter . "\" 12\n";
1402         output_highlight($args{'parameterdescs'}{$parameter_name});
1403     }
1404     foreach $section (@{$args{'sectionlist'}}) {
1405         print ".SH \"$section\"\n";
1406         output_highlight($args{'sections'}{$section});
1407     }
1408 }
1409
1410 ##
1411 # output struct in man
1412 sub output_struct_man(%) {
1413     my %args = %{$_[0]};
1414     my ($parameter, $section);
1415
1416     print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
1417
1418     print ".SH NAME\n";
1419     print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
1420
1421     print ".SH SYNOPSIS\n";
1422     print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
1423
1424     foreach my $parameter (@{$args{'parameterlist'}}) {
1425         if ($parameter =~ /^#/) {
1426             print ".BI \"$parameter\"\n.br\n";
1427             next;
1428         }
1429         my $parameter_name = $parameter;
1430         $parameter_name =~ s/\[.*//;
1431
1432         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1433         $type = $args{'parametertypes'}{$parameter};
1434         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1435             # pointer-to-function
1436             print ".BI \"    " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
1437         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1438             # bitfield
1439             print ".BI \"    " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
1440         } else {
1441             $type =~ s/([^\*])$/$1 /;
1442             print ".BI \"    " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
1443         }
1444         print "\n.br\n";
1445     }
1446     print "};\n.br\n";
1447
1448     print ".SH Members\n";
1449     foreach $parameter (@{$args{'parameterlist'}}) {
1450         ($parameter =~ /^#/) && next;
1451
1452         my $parameter_name = $parameter;
1453         $parameter_name =~ s/\[.*//;
1454
1455         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1456         print ".IP \"" . $parameter . "\" 12\n";
1457         output_highlight($args{'parameterdescs'}{$parameter_name});
1458     }
1459     foreach $section (@{$args{'sectionlist'}}) {
1460         print ".SH \"$section\"\n";
1461         output_highlight($args{'sections'}{$section});
1462     }
1463 }
1464
1465 ##
1466 # output typedef in man
1467 sub output_typedef_man(%) {
1468     my %args = %{$_[0]};
1469     my ($parameter, $section);
1470
1471     print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1472
1473     print ".SH NAME\n";
1474     print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
1475
1476     foreach $section (@{$args{'sectionlist'}}) {
1477         print ".SH \"$section\"\n";
1478         output_highlight($args{'sections'}{$section});
1479     }
1480 }
1481
1482 sub output_blockhead_man(%) {
1483     my %args = %{$_[0]};
1484     my ($parameter, $section);
1485     my $count;
1486
1487     print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1488
1489     foreach $section (@{$args{'sectionlist'}}) {
1490         print ".SH \"$section\"\n";
1491         output_highlight($args{'sections'}{$section});
1492     }
1493 }
1494
1495 ##
1496 # output in text
1497 sub output_function_text(%) {
1498     my %args = %{$_[0]};
1499     my ($parameter, $section);
1500     my $start;
1501
1502     print "Name:\n\n";
1503     print $args{'function'} . " - " . $args{'purpose'} . "\n";
1504
1505     print "\nSynopsis:\n\n";
1506     if ($args{'functiontype'} ne "") {
1507         $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1508     } else {
1509         $start = $args{'function'} . " (";
1510     }
1511     print $start;
1512
1513     my $count = 0;
1514     foreach my $parameter (@{$args{'parameterlist'}}) {
1515         $type = $args{'parametertypes'}{$parameter};
1516         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1517             # pointer-to-function
1518             print $1 . $parameter . ") (" . $2;
1519         } else {
1520             print $type . " " . $parameter;
1521         }
1522         if ($count != $#{$args{'parameterlist'}}) {
1523             $count++;
1524             print ",\n";
1525             print " " x length($start);
1526         } else {
1527             print ");\n\n";
1528         }
1529     }
1530
1531     print "Arguments:\n\n";
1532     foreach $parameter (@{$args{'parameterlist'}}) {
1533         my $parameter_name = $parameter;
1534         $parameter_name =~ s/\[.*//;
1535
1536         print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
1537     }
1538     output_section_text(@_);
1539 }
1540
1541 #output sections in text
1542 sub output_section_text(%) {
1543     my %args = %{$_[0]};
1544     my $section;
1545
1546     print "\n";
1547     foreach $section (@{$args{'sectionlist'}}) {
1548         print "$section:\n\n";
1549         output_highlight($args{'sections'}{$section});
1550     }
1551     print "\n\n";
1552 }
1553
1554 # output enum in text
1555 sub output_enum_text(%) {
1556     my %args = %{$_[0]};
1557     my ($parameter);
1558     my $count;
1559     print "Enum:\n\n";
1560
1561     print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
1562     print "enum " . $args{'enum'} . " {\n";
1563     $count = 0;
1564     foreach $parameter (@{$args{'parameterlist'}}) {
1565         print "\t$parameter";
1566         if ($count != $#{$args{'parameterlist'}}) {
1567             $count++;
1568             print ",";
1569         }
1570         print "\n";
1571     }
1572     print "};\n\n";
1573
1574     print "Constants:\n\n";
1575     foreach $parameter (@{$args{'parameterlist'}}) {
1576         print "$parameter\n\t";
1577         print $args{'parameterdescs'}{$parameter} . "\n";
1578     }
1579
1580     output_section_text(@_);
1581 }
1582
1583 # output typedef in text
1584 sub output_typedef_text(%) {
1585     my %args = %{$_[0]};
1586     my ($parameter);
1587     my $count;
1588     print "Typedef:\n\n";
1589
1590     print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
1591     output_section_text(@_);
1592 }
1593
1594 # output struct as text
1595 sub output_struct_text(%) {
1596     my %args = %{$_[0]};
1597     my ($parameter);
1598
1599     print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
1600     print $args{'type'} . " " . $args{'struct'} . " {\n";
1601     foreach $parameter (@{$args{'parameterlist'}}) {
1602         if ($parameter =~ /^#/) {
1603             print "$parameter\n";
1604             next;
1605         }
1606
1607         my $parameter_name = $parameter;
1608         $parameter_name =~ s/\[.*//;
1609
1610         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1611         $type = $args{'parametertypes'}{$parameter};
1612         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1613             # pointer-to-function
1614             print "\t$1 $parameter) ($2);\n";
1615         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1616             # bitfield
1617             print "\t$1 $parameter$2;\n";
1618         } else {
1619             print "\t" . $type . " " . $parameter . ";\n";
1620         }
1621     }
1622     print "};\n\n";
1623
1624     print "Members:\n\n";
1625     foreach $parameter (@{$args{'parameterlist'}}) {
1626         ($parameter =~ /^#/) && next;
1627
1628         my $parameter_name = $parameter;
1629         $parameter_name =~ s/\[.*//;
1630
1631         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1632         print "$parameter\n\t";
1633         print $args{'parameterdescs'}{$parameter_name} . "\n";
1634     }
1635     print "\n";
1636     output_section_text(@_);
1637 }
1638
1639 sub output_blockhead_text(%) {
1640     my %args = %{$_[0]};
1641     my ($parameter, $section);
1642
1643     foreach $section (@{$args{'sectionlist'}}) {
1644         print " $section:\n";
1645         print "    -> ";
1646         output_highlight($args{'sections'}{$section});
1647     }
1648 }
1649
1650 ## list mode output functions
1651
1652 sub output_function_list(%) {
1653     my %args = %{$_[0]};
1654
1655     print $args{'function'} . "\n";
1656 }
1657
1658 # output enum in list
1659 sub output_enum_list(%) {
1660     my %args = %{$_[0]};
1661     print $args{'enum'} . "\n";
1662 }
1663
1664 # output typedef in list
1665 sub output_typedef_list(%) {
1666     my %args = %{$_[0]};
1667     print $args{'typedef'} . "\n";
1668 }
1669
1670 # output struct as list
1671 sub output_struct_list(%) {
1672     my %args = %{$_[0]};
1673
1674     print $args{'struct'} . "\n";
1675 }
1676
1677 sub output_blockhead_list(%) {
1678     my %args = %{$_[0]};
1679     my ($parameter, $section);
1680
1681     foreach $section (@{$args{'sectionlist'}}) {
1682         print "DOC: $section\n";
1683     }
1684 }
1685
1686 ##
1687 # generic output function for all types (function, struct/union, typedef, enum);
1688 # calls the generated, variable output_ function name based on
1689 # functype and output_mode
1690 sub output_declaration {
1691     no strict 'refs';
1692     my $name = shift;
1693     my $functype = shift;
1694     my $func = "output_${functype}_$output_mode";
1695     if (($function_only==0) ||
1696         ( $function_only == 1 && defined($function_table{$name})) ||
1697         ( $function_only == 2 && !defined($function_table{$name})))
1698     {
1699         &$func(@_);
1700         $section_counter++;
1701     }
1702 }
1703
1704 ##
1705 # generic output function - calls the right one based on current output mode.
1706 sub output_blockhead {
1707     no strict 'refs';
1708     my $func = "output_blockhead_" . $output_mode;
1709     &$func(@_);
1710     $section_counter++;
1711 }
1712
1713 ##
1714 # takes a declaration (struct, union, enum, typedef) and
1715 # invokes the right handler. NOT called for functions.
1716 sub dump_declaration($$) {
1717     no strict 'refs';
1718     my ($prototype, $file) = @_;
1719     my $func = "dump_" . $decl_type;
1720     &$func(@_);
1721 }
1722
1723 sub dump_union($$) {
1724     dump_struct(@_);
1725 }
1726
1727 sub dump_struct($$) {
1728     my $x = shift;
1729     my $file = shift;
1730     my $nested;
1731
1732     if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
1733         #my $decl_type = $1;
1734         $declaration_name = $2;
1735         my $members = $3;
1736
1737         # ignore embedded structs or unions
1738         $members =~ s/({.*})//g;
1739         $nested = $1;
1740
1741         # ignore members marked private:
1742         $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
1743         $members =~ s/\/\*\s*private:.*//gos;
1744         # strip comments:
1745         $members =~ s/\/\*.*?\*\///gos;
1746         $nested =~ s/\/\*.*?\*\///gos;
1747         # strip kmemcheck_bitfield_{begin,end}.*;
1748         $members =~ s/kmemcheck_bitfield_.*?;//gos;
1749         # strip attributes
1750         $members =~ s/__aligned\s*\(\d+\)//gos;
1751
1752         create_parameterlist($members, ';', $file);
1753         check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
1754
1755         output_declaration($declaration_name,
1756                            'struct',
1757                            {'struct' => $declaration_name,
1758                             'module' => $modulename,
1759                             'parameterlist' => \@parameterlist,
1760                             'parameterdescs' => \%parameterdescs,
1761                             'parametertypes' => \%parametertypes,
1762                             'sectionlist' => \@sectionlist,
1763                             'sections' => \%sections,
1764                             'purpose' => $declaration_purpose,
1765                             'type' => $decl_type
1766                            });
1767     }
1768     else {
1769         print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
1770         ++$errors;
1771     }
1772 }
1773
1774 sub dump_enum($$) {
1775     my $x = shift;
1776     my $file = shift;
1777
1778     $x =~ s@/\*.*?\*/@@gos;     # strip comments.
1779     $x =~ s/^#\s*define\s+.*$//; # strip #define macros inside enums
1780
1781     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
1782         $declaration_name = $1;
1783         my $members = $2;
1784
1785         foreach my $arg (split ',', $members) {
1786             $arg =~ s/^\s*(\w+).*/$1/;
1787             push @parameterlist, $arg;
1788             if (!$parameterdescs{$arg}) {
1789                 $parameterdescs{$arg} = $undescribed;
1790                 print STDERR "Warning(${file}:$.): Enum value '$arg' ".
1791                     "not described in enum '$declaration_name'\n";
1792             }
1793
1794         }
1795
1796         output_declaration($declaration_name,
1797                            'enum',
1798                            {'enum' => $declaration_name,
1799                             'module' => $modulename,
1800                             'parameterlist' => \@parameterlist,
1801                             'parameterdescs' => \%parameterdescs,
1802                             'sectionlist' => \@sectionlist,
1803                             'sections' => \%sections,
1804                             'purpose' => $declaration_purpose
1805                            });
1806     }
1807     else {
1808         print STDERR "Error(${file}:$.): Cannot parse enum!\n";
1809         ++$errors;
1810     }
1811 }
1812
1813 sub dump_typedef($$) {
1814     my $x = shift;
1815     my $file = shift;
1816
1817     $x =~ s@/\*.*?\*/@@gos;     # strip comments.
1818     while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1819         $x =~ s/\(*.\)\s*;$/;/;
1820         $x =~ s/\[*.\]\s*;$/;/;
1821     }
1822
1823     if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1824         $declaration_name = $1;
1825
1826         output_declaration($declaration_name,
1827                            'typedef',
1828                            {'typedef' => $declaration_name,
1829                             'module' => $modulename,
1830                             'sectionlist' => \@sectionlist,
1831                             'sections' => \%sections,
1832                             'purpose' => $declaration_purpose
1833                            });
1834     }
1835     else {
1836         print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
1837         ++$errors;
1838     }
1839 }
1840
1841 sub save_struct_actual($) {
1842     my $actual = shift;
1843
1844     # strip all spaces from the actual param so that it looks like one string item
1845     $actual =~ s/\s*//g;
1846     $struct_actual = $struct_actual . $actual . " ";
1847 }
1848
1849 sub create_parameterlist($$$) {
1850     my $args = shift;
1851     my $splitter = shift;
1852     my $file = shift;
1853     my $type;
1854     my $param;
1855
1856     # temporarily replace commas inside function pointer definition
1857     while ($args =~ /(\([^\),]+),/) {
1858         $args =~ s/(\([^\),]+),/$1#/g;
1859     }
1860
1861     foreach my $arg (split($splitter, $args)) {
1862         # strip comments
1863         $arg =~ s/\/\*.*\*\///;
1864         # strip leading/trailing spaces
1865         $arg =~ s/^\s*//;
1866         $arg =~ s/\s*$//;
1867         $arg =~ s/\s+/ /;
1868
1869         if ($arg =~ /^#/) {
1870             # Treat preprocessor directive as a typeless variable just to fill
1871             # corresponding data structures "correctly". Catch it later in
1872             # output_* subs.
1873             push_parameter($arg, "", $file);
1874         } elsif ($arg =~ m/\(.+\)\s*\(/) {
1875             # pointer-to-function
1876             $arg =~ tr/#/,/;
1877             $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
1878             $param = $1;
1879             $type = $arg;
1880             $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1881             save_struct_actual($param);
1882             push_parameter($param, $type, $file);
1883         } elsif ($arg) {
1884             $arg =~ s/\s*:\s*/:/g;
1885             $arg =~ s/\s*\[/\[/g;
1886
1887             my @args = split('\s*,\s*', $arg);
1888             if ($args[0] =~ m/\*/) {
1889                 $args[0] =~ s/(\*+)\s*/ $1/;
1890             }
1891
1892             my @first_arg;
1893             if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1894                     shift @args;
1895                     push(@first_arg, split('\s+', $1));
1896                     push(@first_arg, $2);
1897             } else {
1898                     @first_arg = split('\s+', shift @args);
1899             }
1900
1901             unshift(@args, pop @first_arg);
1902             $type = join " ", @first_arg;
1903
1904             foreach $param (@args) {
1905                 if ($param =~ m/^(\*+)\s*(.*)/) {
1906                     save_struct_actual($2);
1907                     push_parameter($2, "$type $1", $file);
1908                 }
1909                 elsif ($param =~ m/(.*?):(\d+)/) {
1910                     if ($type ne "") { # skip unnamed bit-fields
1911                         save_struct_actual($1);
1912                         push_parameter($1, "$type:$2", $file)
1913                     }
1914                 }
1915                 else {
1916                     save_struct_actual($param);
1917                     push_parameter($param, $type, $file);
1918                 }
1919             }
1920         }
1921     }
1922 }
1923
1924 sub push_parameter($$$) {
1925         my $param = shift;
1926         my $type = shift;
1927         my $file = shift;
1928
1929         if (($anon_struct_union == 1) && ($type eq "") &&
1930             ($param eq "}")) {
1931                 return;         # ignore the ending }; from anon. struct/union
1932         }
1933
1934         $anon_struct_union = 0;
1935         my $param_name = $param;
1936         $param_name =~ s/\[.*//;
1937
1938         if ($type eq "" && $param =~ /\.\.\.$/)
1939         {
1940             if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
1941                 $parameterdescs{$param} = "variable arguments";
1942             }
1943         }
1944         elsif ($type eq "" && ($param eq "" or $param eq "void"))
1945         {
1946             $param="void";
1947             $parameterdescs{void} = "no arguments";
1948         }
1949         elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1950         # handle unnamed (anonymous) union or struct:
1951         {
1952                 $type = $param;
1953                 $param = "{unnamed_" . $param . "}";
1954                 $parameterdescs{$param} = "anonymous\n";
1955                 $anon_struct_union = 1;
1956         }
1957
1958         # warn if parameter has no description
1959         # (but ignore ones starting with # as these are not parameters
1960         # but inline preprocessor statements);
1961         # also ignore unnamed structs/unions;
1962         if (!$anon_struct_union) {
1963         if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
1964
1965             $parameterdescs{$param_name} = $undescribed;
1966
1967             if (($type eq 'function') || ($type eq 'enum')) {
1968                 print STDERR "Warning(${file}:$.): Function parameter ".
1969                     "or member '$param' not " .
1970                     "described in '$declaration_name'\n";
1971             }
1972             print STDERR "Warning(${file}:$.):" .
1973                          " No description found for parameter '$param'\n";
1974             ++$warnings;
1975         }
1976         }
1977
1978         $param = xml_escape($param);
1979
1980         # strip spaces from $param so that it is one continuous string
1981         # on @parameterlist;
1982         # this fixes a problem where check_sections() cannot find
1983         # a parameter like "addr[6 + 2]" because it actually appears
1984         # as "addr[6", "+", "2]" on the parameter list;
1985         # but it's better to maintain the param string unchanged for output,
1986         # so just weaken the string compare in check_sections() to ignore
1987         # "[blah" in a parameter string;
1988         ###$param =~ s/\s*//g;
1989         push @parameterlist, $param;
1990         $parametertypes{$param} = $type;
1991 }
1992
1993 sub check_sections($$$$$$) {
1994         my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
1995         my @sects = split ' ', $sectcheck;
1996         my @prms = split ' ', $prmscheck;
1997         my $err;
1998         my ($px, $sx);
1999         my $prm_clean;          # strip trailing "[array size]" and/or beginning "*"
2000
2001         foreach $sx (0 .. $#sects) {
2002                 $err = 1;
2003                 foreach $px (0 .. $#prms) {
2004                         $prm_clean = $prms[$px];
2005                         $prm_clean =~ s/\[.*\]//;
2006                         $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2007                         # ignore array size in a parameter string;
2008                         # however, the original param string may contain
2009                         # spaces, e.g.:  addr[6 + 2]
2010                         # and this appears in @prms as "addr[6" since the
2011                         # parameter list is split at spaces;
2012                         # hence just ignore "[..." for the sections check;
2013                         $prm_clean =~ s/\[.*//;
2014
2015                         ##$prm_clean =~ s/^\**//;
2016                         if ($prm_clean eq $sects[$sx]) {
2017                                 $err = 0;
2018                                 last;
2019                         }
2020                 }
2021                 if ($err) {
2022                         if ($decl_type eq "function") {
2023                                 print STDERR "Warning(${file}:$.): " .
2024                                         "Excess function parameter " .
2025                                         "'$sects[$sx]' " .
2026                                         "description in '$decl_name'\n";
2027                                 ++$warnings;
2028                         } else {
2029                                 if ($nested !~ m/\Q$sects[$sx]\E/) {
2030                                     print STDERR "Warning(${file}:$.): " .
2031                                         "Excess struct/union/enum/typedef member " .
2032                                         "'$sects[$sx]' " .
2033                                         "description in '$decl_name'\n";
2034                                     ++$warnings;
2035                                 }
2036                         }
2037                 }
2038         }
2039 }
2040
2041 ##
2042 # takes a function prototype and the name of the current file being
2043 # processed and spits out all the details stored in the global
2044 # arrays/hashes.
2045 sub dump_function($$) {
2046     my $prototype = shift;
2047     my $file = shift;
2048
2049     $prototype =~ s/^static +//;
2050     $prototype =~ s/^extern +//;
2051     $prototype =~ s/^asmlinkage +//;
2052     $prototype =~ s/^inline +//;
2053     $prototype =~ s/^__inline__ +//;
2054     $prototype =~ s/^__inline +//;
2055     $prototype =~ s/^__always_inline +//;
2056     $prototype =~ s/^noinline +//;
2057     $prototype =~ s/__devinit +//;
2058     $prototype =~ s/__init +//;
2059     $prototype =~ s/__init_or_module +//;
2060     $prototype =~ s/__must_check +//;
2061     $prototype =~ s/__weak +//;
2062     $prototype =~ s/^#\s*define\s+//; #ak added
2063     $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
2064
2065     # Yes, this truly is vile.  We are looking for:
2066     # 1. Return type (may be nothing if we're looking at a macro)
2067     # 2. Function name
2068     # 3. Function parameters.
2069     #
2070     # All the while we have to watch out for function pointer parameters
2071     # (which IIRC is what the two sections are for), C types (these
2072     # regexps don't even start to express all the possibilities), and
2073     # so on.
2074     #
2075     # If you mess with these regexps, it's a good idea to check that
2076     # the following functions' documentation still comes out right:
2077     # - parport_register_device (function pointer parameters)
2078     # - atomic_set (macro)
2079     # - pci_match_device, __copy_to_user (long return type)
2080
2081     if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2082         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2083         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2084         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2085         $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2086         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2087         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2088         $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2089         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2090         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2091         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2092         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2093         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2094         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2095         $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2096         $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2097         $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
2098         $return_type = $1;
2099         $declaration_name = $2;
2100         my $args = $3;
2101
2102         create_parameterlist($args, ',', $file);
2103     } else {
2104         print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
2105         ++$errors;
2106         return;
2107     }
2108
2109         my $prms = join " ", @parameterlist;
2110         check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2111
2112     output_declaration($declaration_name,
2113                        'function',
2114                        {'function' => $declaration_name,
2115                         'module' => $modulename,
2116                         'functiontype' => $return_type,
2117                         'parameterlist' => \@parameterlist,
2118                         'parameterdescs' => \%parameterdescs,
2119                         'parametertypes' => \%parametertypes,
2120                         'sectionlist' => \@sectionlist,
2121                         'sections' => \%sections,
2122                         'purpose' => $declaration_purpose
2123                        });
2124 }
2125
2126 sub reset_state {
2127     $function = "";
2128     %constants = ();
2129     %parameterdescs = ();
2130     %parametertypes = ();
2131     @parameterlist = ();
2132     %sections = ();
2133     @sectionlist = ();
2134     $sectcheck = "";
2135     $struct_actual = "";
2136     $prototype = "";
2137
2138     $state = 0;
2139 }
2140
2141 sub tracepoint_munge($) {
2142         my $file = shift;
2143         my $tracepointname = 0;
2144         my $tracepointargs = 0;
2145
2146         if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
2147                 $tracepointname = $1;
2148         }
2149         if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
2150                 $tracepointname = $1;
2151         }
2152         if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2153                 $tracepointname = $2;
2154         }
2155         $tracepointname =~ s/^\s+//; #strip leading whitespace
2156         if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
2157                 $tracepointargs = $1;
2158         }
2159         if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
2160                 print STDERR "Warning(${file}:$.): Unrecognized tracepoint format: \n".
2161                              "$prototype\n";
2162         } else {
2163                 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
2164         }
2165 }
2166
2167 sub syscall_munge() {
2168         my $void = 0;
2169
2170         $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
2171 ##      if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
2172         if ($prototype =~ m/SYSCALL_DEFINE0/) {
2173                 $void = 1;
2174 ##              $prototype = "long sys_$1(void)";
2175         }
2176
2177         $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
2178         if ($prototype =~ m/long (sys_.*?),/) {
2179                 $prototype =~ s/,/\(/;
2180         } elsif ($void) {
2181                 $prototype =~ s/\)/\(void\)/;
2182         }
2183
2184         # now delete all of the odd-number commas in $prototype
2185         # so that arg types & arg names don't have a comma between them
2186         my $count = 0;
2187         my $len = length($prototype);
2188         if ($void) {
2189                 $len = 0;       # skip the for-loop
2190         }
2191         for (my $ix = 0; $ix < $len; $ix++) {
2192                 if (substr($prototype, $ix, 1) eq ',') {
2193                         $count++;
2194                         if ($count % 2 == 1) {
2195                                 substr($prototype, $ix, 1) = ' ';
2196                         }
2197                 }
2198         }
2199 }
2200
2201 sub process_state3_function($$) {
2202     my $x = shift;
2203     my $file = shift;
2204
2205     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2206
2207     if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
2208         # do nothing
2209     }
2210     elsif ($x =~ /([^\{]*)/) {
2211         $prototype .= $1;
2212     }
2213
2214     if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
2215         $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
2216         $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2217         $prototype =~ s@^\s+@@gos; # strip leading spaces
2218         if ($prototype =~ /SYSCALL_DEFINE/) {
2219                 syscall_munge();
2220         }
2221         if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
2222             $prototype =~ /DEFINE_SINGLE_EVENT/)
2223         {
2224                 tracepoint_munge($file);
2225         }
2226         dump_function($prototype, $file);
2227         reset_state();
2228     }
2229 }
2230
2231 sub process_state3_type($$) {
2232     my $x = shift;
2233     my $file = shift;
2234
2235     $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2236     $x =~ s@^\s+@@gos; # strip leading spaces
2237     $x =~ s@\s+$@@gos; # strip trailing spaces
2238     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2239
2240     if ($x =~ /^#/) {
2241         # To distinguish preprocessor directive from regular declaration later.
2242         $x .= ";";
2243     }
2244
2245     while (1) {
2246         if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
2247             $prototype .= $1 . $2;
2248             ($2 eq '{') && $brcount++;
2249             ($2 eq '}') && $brcount--;
2250             if (($2 eq ';') && ($brcount == 0)) {
2251                 dump_declaration($prototype, $file);
2252                 reset_state();
2253                 last;
2254             }
2255             $x = $3;
2256         } else {
2257             $prototype .= $x;
2258             last;
2259         }
2260     }
2261 }
2262
2263 # xml_escape: replace <, >, and & in the text stream;
2264 #
2265 # however, formatting controls that are generated internally/locally in the
2266 # kernel-doc script are not escaped here; instead, they begin life like
2267 # $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2268 # are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2269 # just before actual output; (this is done by local_unescape())
2270 sub xml_escape($) {
2271         my $text = shift;
2272         if (($output_mode eq "text") || ($output_mode eq "man")) {
2273                 return $text;
2274         }
2275         $text =~ s/\&/\\\\\\amp;/g;
2276         $text =~ s/\</\\\\\\lt;/g;
2277         $text =~ s/\>/\\\\\\gt;/g;
2278         return $text;
2279 }
2280
2281 # convert local escape strings to html
2282 # local escape strings look like:  '\\\\menmonic:' (that's 4 backslashes)
2283 sub local_unescape($) {
2284         my $text = shift;
2285         if (($output_mode eq "text") || ($output_mode eq "man")) {
2286                 return $text;
2287         }
2288         $text =~ s/\\\\\\\\lt:/</g;
2289         $text =~ s/\\\\\\\\gt:/>/g;
2290         return $text;
2291 }
2292
2293 sub process_file($) {
2294     my $file;
2295     my $identifier;
2296     my $func;
2297     my $descr;
2298     my $in_purpose = 0;
2299     my $initial_section_counter = $section_counter;
2300
2301     if (defined($ENV{'SRCTREE'})) {
2302         $file = "$ENV{'SRCTREE'}" . "/" . "@_";
2303     }
2304     else {
2305         $file = "@_";
2306     }
2307     if (defined($source_map{$file})) {
2308         $file = $source_map{$file};
2309     }
2310
2311     if (!open(IN,"<$file")) {
2312         print STDERR "Error: Cannot open file $file\n";
2313         ++$errors;
2314         return;
2315     }
2316
2317     $. = 1;
2318
2319     $section_counter = 0;
2320     while (<IN>) {
2321         while (s/\\\s*$//) {
2322             $_ .= <IN>;
2323         }
2324         if ($state == 0) {
2325             if (/$doc_start/o) {
2326                 $state = 1;             # next line is always the function name
2327                 $in_doc_sect = 0;
2328             }
2329         } elsif ($state == 1) { # this line is the function name (always)
2330             if (/$doc_block/o) {
2331                 $state = 4;
2332                 $contents = "";
2333                 if ( $1 eq "" ) {
2334                         $section = $section_intro;
2335                 } else {
2336                         $section = $1;
2337                 }
2338             }
2339             elsif (/$doc_decl/o) {
2340                 $identifier = $1;
2341                 if (/\s*([\w\s]+?)\s*-/) {
2342                     $identifier = $1;
2343                 }
2344
2345                 $state = 2;
2346                 if (/-(.*)/) {
2347                     # strip leading/trailing/multiple spaces
2348                     $descr= $1;
2349                     $descr =~ s/^\s*//;
2350                     $descr =~ s/\s*$//;
2351                     $descr =~ s/\s+/ /g;
2352                     $declaration_purpose = xml_escape($descr);
2353                     $in_purpose = 1;
2354                 } else {
2355                     $declaration_purpose = "";
2356                 }
2357
2358                 if (($declaration_purpose eq "") && $verbose) {
2359                         print STDERR "Warning(${file}:$.): missing initial short description on line:\n";
2360                         print STDERR $_;
2361                         ++$warnings;
2362                 }
2363
2364                 if ($identifier =~ m/^struct/) {
2365                     $decl_type = 'struct';
2366                 } elsif ($identifier =~ m/^union/) {
2367                     $decl_type = 'union';
2368                 } elsif ($identifier =~ m/^enum/) {
2369                     $decl_type = 'enum';
2370                 } elsif ($identifier =~ m/^typedef/) {
2371                     $decl_type = 'typedef';
2372                 } else {
2373                     $decl_type = 'function';
2374                 }
2375
2376                 if ($verbose) {
2377                     print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
2378                 }
2379             } else {
2380                 print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
2381                 " - I thought it was a doc line\n";
2382                 ++$warnings;
2383                 $state = 0;
2384             }
2385         } elsif ($state == 2) { # look for head: lines, and include content
2386             if (/$doc_sect/o) {
2387                 $newsection = $1;
2388                 $newcontents = $2;
2389
2390                 if (($contents ne "") && ($contents ne "\n")) {
2391                     if (!$in_doc_sect && $verbose) {
2392                         print STDERR "Warning(${file}:$.): contents before sections\n";
2393                         ++$warnings;
2394                     }
2395                     dump_section($file, $section, xml_escape($contents));
2396                     $section = $section_default;
2397                 }
2398
2399                 $in_doc_sect = 1;
2400                 $in_purpose = 0;
2401                 $contents = $newcontents;
2402                 if ($contents ne "") {
2403                     while ((substr($contents, 0, 1) eq " ") ||
2404                         substr($contents, 0, 1) eq "\t") {
2405                             $contents = substr($contents, 1);
2406                     }
2407                     $contents .= "\n";
2408                 }
2409                 $section = $newsection;
2410             } elsif (/$doc_end/) {
2411
2412                 if (($contents ne "") && ($contents ne "\n")) {
2413                     dump_section($file, $section, xml_escape($contents));
2414                     $section = $section_default;
2415                     $contents = "";
2416                 }
2417                 # look for doc_com + <text> + doc_end:
2418                 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2419                     print STDERR "Warning(${file}:$.): suspicious ending line: $_";
2420                     ++$warnings;
2421                 }
2422
2423                 $prototype = "";
2424                 $state = 3;
2425                 $brcount = 0;
2426 #               print STDERR "end of doc comment, looking for prototype\n";
2427             } elsif (/$doc_content/) {
2428                 # miguel-style comment kludge, look for blank lines after
2429                 # @parameter line to signify start of description
2430                 if ($1 eq "") {
2431                     if ($section =~ m/^@/ || $section eq $section_context) {
2432                         dump_section($file, $section, xml_escape($contents));
2433                         $section = $section_default;
2434                         $contents = "";
2435                     } else {
2436                         $contents .= "\n";
2437                     }
2438                     $in_purpose = 0;
2439                 } elsif ($in_purpose == 1) {
2440                     # Continued declaration purpose
2441                     chomp($declaration_purpose);
2442                     $declaration_purpose .= " " . xml_escape($1);
2443                     $declaration_purpose =~ s/\s+/ /g;
2444                 } else {
2445                     $contents .= $1 . "\n";
2446                 }
2447             } else {
2448                 # i dont know - bad line?  ignore.
2449                 print STDERR "Warning(${file}:$.): bad line: $_";
2450                 ++$warnings;
2451             }
2452         } elsif ($state == 3) { # scanning for function '{' (end of prototype)
2453             if ($decl_type eq 'function') {
2454                 process_state3_function($_, $file);
2455             } else {
2456                 process_state3_type($_, $file);
2457             }
2458         } elsif ($state == 4) {
2459                 # Documentation block
2460                 if (/$doc_block/) {
2461                         dump_doc_section($file, $section, xml_escape($contents));
2462                         $contents = "";
2463                         $function = "";
2464                         %constants = ();
2465                         %parameterdescs = ();
2466                         %parametertypes = ();
2467                         @parameterlist = ();
2468                         %sections = ();
2469                         @sectionlist = ();
2470                         $prototype = "";
2471                         if ( $1 eq "" ) {
2472                                 $section = $section_intro;
2473                         } else {
2474                                 $section = $1;
2475                         }
2476                 }
2477                 elsif (/$doc_end/)
2478                 {
2479                         dump_doc_section($file, $section, xml_escape($contents));
2480                         $contents = "";
2481                         $function = "";
2482                         %constants = ();
2483                         %parameterdescs = ();
2484                         %parametertypes = ();
2485                         @parameterlist = ();
2486                         %sections = ();
2487                         @sectionlist = ();
2488                         $prototype = "";
2489                         $state = 0;
2490                 }
2491                 elsif (/$doc_content/)
2492                 {
2493                         if ( $1 eq "" )
2494                         {
2495                                 $contents .= $blankline;
2496                         }
2497                         else
2498                         {
2499                                 $contents .= $1 . "\n";
2500                         }
2501                 }
2502         }
2503     }
2504     if ($initial_section_counter == $section_counter) {
2505         print STDERR "Warning(${file}): no structured comments found\n";
2506         if ($output_mode eq "xml") {
2507             # The template wants at least one RefEntry here; make one.
2508             print "<refentry>\n";
2509             print " <refnamediv>\n";
2510             print "  <refname>\n";
2511             print "   ${file}\n";
2512             print "  </refname>\n";
2513             print "  <refpurpose>\n";
2514             print "   Document generation inconsistency\n";
2515             print "  </refpurpose>\n";
2516             print " </refnamediv>\n";
2517             print " <refsect1>\n";
2518             print "  <title>\n";
2519             print "   Oops\n";
2520             print "  </title>\n";
2521             print "  <warning>\n";
2522             print "   <para>\n";
2523             print "    The template for this document tried to insert\n";
2524             print "    the structured comment from the file\n";
2525             print "    <filename>${file}</filename> at this point,\n";
2526             print "    but none was found.\n";
2527             print "    This dummy section is inserted to allow\n";
2528             print "    generation to continue.\n";
2529             print "   </para>\n";
2530             print "  </warning>\n";
2531             print " </refsect1>\n";
2532             print "</refentry>\n";
2533         }
2534     }
2535 }
2536
2537
2538 $kernelversion = get_kernel_version();
2539
2540 # generate a sequence of code that will splice in highlighting information
2541 # using the s// operator.
2542 foreach my $pattern (keys %highlights) {
2543 #   print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
2544     $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
2545 }
2546
2547 # Read the file that maps relative names to absolute names for
2548 # separate source and object directories and for shadow trees.
2549 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2550         my ($relname, $absname);
2551         while(<SOURCE_MAP>) {
2552                 chop();
2553                 ($relname, $absname) = (split())[0..1];
2554                 $relname =~ s:^/+::;
2555                 $source_map{$relname} = $absname;
2556         }
2557         close(SOURCE_MAP);
2558 }
2559
2560 foreach (@ARGV) {
2561     chomp;
2562     process_file($_);
2563 }
2564 if ($verbose && $errors) {
2565   print STDERR "$errors errors\n";
2566 }
2567 if ($verbose && $warnings) {
2568   print STDERR "$warnings warnings\n";
2569 }
2570
2571 exit($errors);