![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to proto-man CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to proto-man CVS log | Up to [GCC 2.x] / gcc |
1.1 ! root 1: #ifndef UNPRO ! 2: #define THISPROG PROTOIZE ! 3: #define thisprog protoize ! 4: #define Thisprog Protoize ! 5: #define otherprog unprotoize ! 6: #define from_convention varargs ! 7: #define to_convention stdarg ! 8: #else ! 9: #define THISPROG UNPROTOIZE ! 10: #define thisprog unprotoize ! 11: #define Thisprog Unprotoize ! 12: #define otherprog protoize ! 13: #define from_convention stdarg ! 14: #define to_convention varargs ! 15: #endif ! 16: .\" Man page file for the thisprog program. ! 17: .\" This is badly out of date, especially concerning ! 18: .\" the way of deciding which files to convert. ! 19: .\" Really all this information should be updated and put in gcc.texinfo. ! 20: .\" ! 21: .\" Written by Ron Guilmette ([email protected]). ! 22: .\" ! 23: .\" Copyright (C) 1989, 1990 Free Software Foundation, Inc. ! 24: .\" ! 25: .\" This file is part of GNU CC. ! 26: .\" ! 27: .\" GNU CC is free software; you can redistribute it and/or modify ! 28: .\" it under the terms of the GNU General Public License as published by ! 29: .\" the Free Software Foundation; either version 1, or (at your option) ! 30: .\" any later version. ! 31: .\" ! 32: .\" GNU CC is distributed in the hope that it will be useful, ! 33: .\" but WITHOUT ANY WARRANTY; without even the implied warranty of ! 34: .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ! 35: .\" GNU General Public License for more details. ! 36: .\" ! 37: .\" You should have received a copy of the GNU General Public License ! 38: .\" along with GNU CC; see the file COPYING. If not, write to ! 39: .\" the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. ! 40: .\" ! 41: .TH THISPROG 1 "21 January 1990" "" ! 42: .SH NAME ! 43: #ifndef UNPRO ! 44: thisprog \- convert K&R C source code to ANSI C prototype format ! 45: #else ! 46: thisprog \- convert ANSI C source code to K&R C (unprototyped) format ! 47: #endif ! 48: .SH SYNOPSIS ! 49: .B thisprog ! 50: [ ! 51: #ifndef UNPRO ! 52: .B -VqfnkNlgC ! 53: ] [ ! 54: .B -B ! 55: .I <dir> ! 56: #else ! 57: .B -VqfnkN ! 58: ] [ ! 59: .B -i ! 60: .I <str> ! 61: #endif ! 62: ] [ ! 63: .B -c ! 64: .I <cc opts> ! 65: ] [ ! 66: .I file\c ! 67: \&... ] ! 68: .SH DESCRIPTION ! 69: .fi ! 70: .ad b ! 71: .I Thisprog ! 72: aids in the conversion of ! 73: #ifndef UNPRO ! 74: K&R C source code files to ANSI C source code files with function prototypes. ! 75: This conversion is useful for eliciting more complete ! 76: interface checking from ANSI C compilers, or as ! 77: a preliminary step in the conversion of C programs to C++. ! 78: #else ! 79: ANSI C source code files to K&R C source code files without function prototypes ! 80: . ! 81: This conversion is useful for porting ANSI C programs to ! 82: machines for which no ANSI C compiler is available. ! 83: #endif ! 84: .PP ! 85: .I Thisprog ! 86: is designed to be used in conjunction ! 87: with the GNU C compiler. The GNU C compiler does preliminary ! 88: .I "information gathering" ! 89: about functions by analyzing the files to be converted. ! 90: The GNU C compiler may be invoked automatically as a result of ! 91: running ! 92: .I thisprog ! 93: so it is important to have it properly installed before attempting ! 94: to convert source files via ! 95: .I thisprog. ! 96: #ifndef UNPRO ! 97: .PP ! 98: .I Thisprog ! 99: actually has two primary functions. First, It converts ! 100: existing function declarations and definitions ! 101: to prototype form. ! 102: Second, for cases in which functions ! 103: are called before they have been declared ! 104: (i.e. points of ! 105: .I implicit ! 106: function declarations), ! 107: .I thisprog ! 108: can be instructed to ! 109: insert new prototype style function declarations ! 110: into the source code. ! 111: For implicit function declarations, ! 112: .I thisprog ! 113: can either ! 114: insert the new (explicit) function declaration ! 115: at the very beginning of the block which contains ! 116: the implicit declaration, or (at the user\'s option) ! 117: these explicit declarations can be inserted near the tops of the ! 118: source files where the implicit declarations occurred. ! 119: The insertion of these new (explicit) function ! 120: declarations (by thisprog) assures that ! 121: .B all ! 122: function calls in your source files will be ! 123: checked for the correct ! 124: number and types of parameters ! 125: during subsequent compilations. ! 126: #endif ! 127: .PP ! 128: .I Thisprog ! 129: supports the conversion of both large and small systems of C source ! 130: code to ! 131: #ifndef UNPRO ! 132: prototype ! 133: #else ! 134: unprototyped ! 135: #endif ! 136: form. ! 137: .I Thisprog ! 138: can perform the conversion of an ! 139: entire program in one (batch) step. ! 140: #ifndef UNPRO ! 141: .PP ! 142: .I Thisprog ! 143: is able to convert entire systems of C source code because ! 144: it knows how to use information (gleaned by the C compiler) from one ! 145: source file to convert ! 146: function definitions and declarations in that same source file or in ! 147: other source files (as required). ! 148: #endif ! 149: .PP ! 150: Each conversion of a system of source code to ! 151: #ifndef UNPRO ! 152: prototyped ! 153: #else ! 154: unprototyped ! 155: #endif ! 156: format consists of two major steps. First, there is an ! 157: .I "information gathering" ! 158: step. In this step, ! 159: all of the source files that make up a given ! 160: executable program are recompiled using the GNU C compiler and using the ! 161: .B -fgen-aux-info ! 162: option. ! 163: These recompilations will be performed automatically by ! 164: .I thisprog ! 165: on an ! 166: .I as needed ! 167: basis. ! 168: .PP ! 169: As individual compilation steps are performed, you may notice ! 170: that a side-effect of these compilations is to create files with a ! 171: .B .X ! 172: suffix in the same directory with the original ! 173: .I base ! 174: source files being compiled. ! 175: During compilation with ! 176: .B -fgen-aux-info, ! 177: one such ! 178: .B .X ! 179: file is created for ! 180: each ! 181: .I base ! 182: source file compiled. These files contain ! 183: information above function definitions and declarations and ! 184: additional coded information which can be used by ! 185: .I thisprog ! 186: to convert your source code ! 187: automatically to ! 188: #ifndef UNPRO ! 189: prototyped ! 190: #else ! 191: unprototyped ! 192: #endif ! 193: format. ! 194: .PP ! 195: After a full set of ! 196: .B .X ! 197: files corresponding to all of the ! 198: .B .c ! 199: (i.e. ! 200: .I base ! 201: source) files for an individual ! 202: program ! 203: have been created, ! 204: .I thisprog ! 205: performs the actual conversion step. ! 206: .PP ! 207: Execution of the ! 208: .I thisprog ! 209: program causes your original source files to be converted such that both ! 210: their function declarations and their function definitions are in ! 211: #ifndef UNPRO ! 212: prototyped ! 213: #else ! 214: unprototyped ! 215: #endif ! 216: format. ! 217: After the conversion of your system, you will be ! 218: left with a set of similar (but converted) source files ! 219: with the same names as your original files. ! 220: .PP ! 221: Before it writes each converted file back to disk, ! 222: .I thisprog ! 223: attempts to rename the original file, giving it a ! 224: .B .save ! 225: suffix. ! 226: It then creates a new output file ! 227: with the same name that the original file had. ! 228: This ensures that if there were any hard links to the original ! 229: input files, these will not be altered by the conversion process. ! 230: .PP ! 231: WARNING! If for any given original file, a save file already exists, ! 232: .I thisprog ! 233: will assume that the existing save file contains a backup of the ! 234: original file as it existed before any conversions were applied. ! 235: Thus, if there is an existing save file, ! 236: .I thisprog ! 237: will not overwrite this existing save file, and no new backup of ! 238: that particular original file will be made during that run of ! 239: .I thisprog. ! 240: .PP ! 241: An important safety feature of ! 242: .I thisprog ! 243: is that it normally only tries to convert files for which you have both ! 244: read and write permissions. Also, ! 245: .I thisprog ! 246: will normally only convert files located in directories that you ! 247: have both search and write permissions for. ! 248: .PP ! 249: Another safety feature is that ! 250: .I thisprog ! 251: will not normally convert files which ! 252: are located in ! 253: .I system ! 254: include directories. ! 255: A ! 256: .I system ! 257: include directory is defined by ! 258: .I thisprog ! 259: as either ! 260: .B /usr/include ! 261: (or any of its subdirectories) ! 262: or a directory whose full absolute pathname includes ! 263: either ! 264: .B gcc-include ! 265: or ! 266: .B g++-include. ! 267: .PP ! 268: Most of the above safety features can be overridden by using the ! 269: .B \-f ! 270: (force) option (see below), ! 271: but even when ! 272: .B \-f ! 273: is used, you cannot force the conversion of files for which you ! 274: do not at least have read permission, or files in directories that you do not ! 275: at least have write permission for. ! 276: .PP ! 277: Note that ! 278: .I thisprog ! 279: will make no attempt to convert definitions ! 280: #ifndef UNPRO ! 281: or declarations ! 282: #endif ! 283: of functions which accept a variable number of arguments ! 284: and which are written using the ! 285: .I from_convention ! 286: conventions. ! 287: All such function definitions ! 288: #ifndef UNPRO ! 289: and declarations ! 290: #endif ! 291: must be converted manually to the ! 292: .I to_convention ! 293: conventions. ! 294: Warnings are automatically issued for ! 295: .I from_convention ! 296: function definitions ! 297: #ifndef UNPRO ! 298: and declarations ! 299: #endif ! 300: which are left unconverted by ! 301: .I thisprog. ! 302: .SH OPTIONS ! 303: .I Thisprog ! 304: recognizes the following options: ! 305: .TP ! 306: .B \-V ! 307: Version number. Causes the current version number to be ! 308: printed on stderr. ! 309: .TP ! 310: .B \-q ! 311: Quiet mode. ! 312: Normally, ! 313: .I thisprog ! 314: may issue many verbose warnings concerning noteworthy conditions. ! 315: These warnings can often be helpful to the overall conversion effort. ! 316: Users who prefer not to see such messages can use the ! 317: .B \-q ! 318: option which suppresses most such warnings. ! 319: .TP ! 320: .B \-f ! 321: Force mode. ! 322: Use of this option overrides the normal safety ! 323: features of ! 324: .I thisprog. ! 325: It allows for attempts to convert system include files, ! 326: and files not writable by you. ! 327: These conversions are still subject to all normal ! 328: file protections provided by the operating system. ! 329: This option should be used only with extreme caution. ! 330: It can be especially dangerous to use this option when logged on as ! 331: .I root. ! 332: Note that when this option is used, you are allowed to convert even files ! 333: that you do not have write access to. So long as you have write access ! 334: to the containing directory, conversion may occur. ! 335: .TP ! 336: .B \-n ! 337: No convert mode. Do not actually perform any conversions on base source files ! 338: or on include files. Rather, simply do all steps leading up to conversion ! 339: and then print a list (to stdout) of the names of all files which would ! 340: actually be modified if the conversions were actually performed. This option ! 341: may be useful to you if you are converting a system of source files ! 342: that you are unfamiliar with. In such cases, you may need to verify ! 343: ahead of time that include files which belong to other people or to ! 344: other projects will not be modified by running ! 345: .I thisprog. ! 346: Use of this option also implicitly enables ! 347: .I keep mode. ! 348: (See the ! 349: .B \-k ! 350: option below.) ! 351: .TP ! 352: .B \-k ! 353: Keep mode. Normally, ! 354: .I thisprog ! 355: reads the information in the ! 356: .B .X ! 357: files created by the GNU C compiler, and then ! 358: immediately deletes these files (since they will no longer be ! 359: valid or useful after conversion). When the ! 360: .B \-k ! 361: option is used however, the ! 362: .B .X ! 363: files are not deleted during conversion. ! 364: .TP ! 365: .B -N ! 366: No save mode. When this option is used, no attempt is made to ! 367: make backups of original files (by renaming them such that they have ! 368: an added ! 369: .B .save ! 370: suffix). ! 371: Use this option with extreme caution, and ! 372: only when you have previously backed up ! 373: all of the files that might be converted ! 374: by running ! 375: .I thisprog. ! 376: (See the ! 377: .B -n ! 378: option above.) ! 379: .TP ! 380: .B \-c <cc opts> ! 381: Specify compile options. The ! 382: .B \-c ! 383: option can be used as a means of passing on important compilation ! 384: options to the C compiler. It may often be necessary to use this option ! 385: to pass command line preprocessor definitions on to the compilation step. ! 386: Note that The compile options must be given as a single argument to ! 387: .I thisprog. ! 388: If you have more than one ! 389: compilation option, you will have to quote the entire set of ! 390: compilation options in order to keep the shell from treating ! 391: them as separate arguments to ! 392: .I thisprog. ! 393: Note also that certain options are automatically suppressed by ! 394: .I thisprog ! 395: and cannot be passed on to the compiler (i.e. ! 396: .B "-g, -O, -c, -S," ! 397: and ! 398: .B "-o" ! 399: are suppressed). ! 400: #ifndef UNPRO ! 401: .TP ! 402: .B \-C ! 403: C++ conversion mode. ! 404: Normally, ! 405: .I thisprog ! 406: writes its (converted) output files back to files of the same names ! 407: as the original (unconverted) input files. ! 408: In C++ conversion mode, ! 409: after each output file is written, ! 410: a check is made to see if the given output file has a ! 411: .B .c ! 412: suffix. If it does, then the given file is renamed, and its suffix ! 413: is changed to ! 414: .B .C. ! 415: This makes the output file ! 416: acceptable as a C++ input file for either the GNU C++ compiler or ! 417: for the Cfront translator. ! 418: .TP ! 419: .B \-l ! 420: Add explicit local declarations. This option causes ! 421: .I thisprog ! 422: to insert ! 423: explicit declarations for functions that were only implicitly declared ! 424: in the original source code. When the ! 425: .B \-l ! 426: option is used, lists of additional new ! 427: explicit function declarations are inserted near the ! 428: starts of blocks where explicit function declarations took place. ! 429: (See also the ! 430: .B \-g ! 431: option below.) ! 432: .TP ! 433: .B \-g ! 434: Add explicit global declarations. This option causes ! 435: .I thisprog ! 436: to insert ! 437: explicit declarations for functions that were only implicitly declared ! 438: in your original source code. When the ! 439: .B \-g ! 440: option is used, a list of additional new ! 441: explicit function declarations is inserted just before the ! 442: first function definition in each individual source file that previously ! 443: contained implicit declarations. ! 444: (See also the ! 445: .B \-l ! 446: option above.) ! 447: .TP ! 448: .B \-B <dir> ! 449: Alternate library directory option. Use this option to specify that ! 450: .I thisprog ! 451: should attempt to find the file ! 452: .B SYSCALLS.c.X ! 453: in the alternate directory indicated in the option. ! 454: #else ! 455: .TP ! 456: .B \-i <str> ! 457: Indent string option. ! 458: This option can be used to specify a string to use when indenting ! 459: lines containing declarations for formal parameter variables. ! 460: The default indentation string for such lines is a sequence of five spaces ! 461: (i.e.\ GNU style indentation) but you may use this option to specify ! 462: any other string that you like (e.g.\ a tab character). ! 463: Note that ! 464: the shell has its own interpretations for blanks and tabs, so you ! 465: will generally have to quotes the argument given in the ! 466: .B -i ! 467: option. ! 468: #endif ! 469: .SH EXAMPLES ! 470: Assume that you have ! 471: a directory with ! 472: all of the files for your system in it. Also ! 473: assume that your system consists of two ! 474: executable programs, one built from the files ! 475: .B s1.c, s2.c, ! 476: and ! 477: .B s3.c, ! 478: and the other built from the files ! 479: .B s4.c ! 480: and ! 481: .B s5.c. ! 482: Finally, assume that these source files share some common include files. ! 483: .PP ! 484: In order to properly convert such a system of programs, you ! 485: would need to perform the steps shown below. ! 486: .sp 1 ! 487: .in +0.5i ! 488: .ft B ! 489: thisprog s1.c s2.c s3.c ! 490: .br ! 491: thisprog s4.c s5.c ! 492: .sp 1 ! 493: .ft R ! 494: .in -0.5i ! 495: .PP ! 496: In the example above, the first invocation of ! 497: .I thisprog ! 498: causes three ! 499: .B .X ! 500: files (called ! 501: .B s1.c.X, s2.c.X, ! 502: and ! 503: .B s3.c.X) ! 504: to be created. ! 505: These files are generated automatically by ! 506: .I thisprog ! 507: (which invokes the GNU C compiler to create them). ! 508: These files contain information about function definitions and declarations ! 509: .I both ! 510: for their corresponding ! 511: .B .c ! 512: files and for any files ! 513: which are included by these ! 514: .I base ! 515: .B .c ! 516: files. ! 517: .PP ! 518: After ! 519: .I thisprog ! 520: has invoked the compiler for each of the files which make up ! 521: .I prog1, ! 522: it performs the actual conversion of these base files (and ! 523: may perform some conversion of their include files ! 524: depending upon the information available in the ! 525: .B .X ! 526: files). ! 527: Finally, after performing all necessary conversions, ! 528: .I thisprog ! 529: automatically deletes the files ! 530: .B s1.c.X, s2.c.X, ! 531: and ! 532: .B s3.c.X. ! 533: .PP ! 534: After performing the conversion for ! 535: .I prog1, ! 536: (as illustrated above) ! 537: you would then ! 538: request ! 539: .I thisprog ! 540: to convert all of the files which make up ! 541: .I prog2 ! 542: in a similar fashion. ! 543: This step would create two more ! 544: .B .X ! 545: files (called ! 546: .B s4.c.X ! 547: and ! 548: .B s5.c.X). ! 549: As with the conversion of ! 550: .I prog1, ! 551: .I thisprog ! 552: will automatically generate any needed ! 553: .B .X ! 554: files (by invoking the GNU C compiler), ! 555: will perform the conversion of all of the given ! 556: .I base ! 557: source files (and possibly do some conversion on include files), ! 558: and will finish up by ! 559: automatically deleting the ! 560: .B .X ! 561: files that were generated during this run. ! 562: .PP ! 563: You may occasionally find that you need to convert a ! 564: particular program which ! 565: consists of several ! 566: .I base ! 567: source files, some of which must be compiled ! 568: with unusual options. ! 569: In such cases, you can still convert the program via ! 570: a special mechanism. ! 571: For each ! 572: .I base ! 573: source file which requires special compilation options, ! 574: you can create a corresponding ! 575: .B .X ! 576: file for the ! 577: .I base ! 578: file ! 579: .I (before ! 580: invoking ! 581: .I thisprog). ! 582: You would do this by invoking the GNU C compiler directly ! 583: with the required special options, and with the ! 584: .B -fgen-aux-info ! 585: option. ! 586: .I Thisprog ! 587: is smart enough to use existing ! 588: .B .X ! 589: files (when they are available and when they are up to date) so creating ! 590: .B .X ! 591: files ahead of time with the GNU C compiler ! 592: is an easy way to accommodate unusual compilation options for individual ! 593: .I base ! 594: files. ! 595: .PP ! 596: Note that ! 597: .I thisprog ! 598: checks each preexisting ! 599: .B .X ! 600: file before it tries to use it in order ! 601: to insure that it is up-to-date ! 602: with respect to all of the source files ! 603: that it contains information about. ! 604: If this check fails, ! 605: .I thisprog ! 606: will automatically ! 607: invoke the GNU C compiler (with default options) to recreate the needed ! 608: .B .X file. ! 609: .SH CAVEATS ! 610: #ifndef UNPRO ! 611: The ! 612: .I thisprog ! 613: program doesn\'t just get information from your own ! 614: .B .X ! 615: files. Every time ! 616: .I thisprog ! 617: executes, it also reads a file ! 618: .B SYSCALLS.c.X ! 619: from some standard installation directory ! 620: (if it exists) to obtain a pre-written set of function prototypes for ! 621: various standard system-supplied functions. These prototypes are effectively ! 622: added to the set of prototypes which ! 623: .I thisprog ! 624: can use to perform prototype substitutions on your source files. ! 625: If the source code for any individual programs that you are converting ! 626: contains its own definitions ! 627: for functions with the same names as standard system-supplied functions, ! 628: .I thisprog ! 629: is intelligent enough to allow the parameter typing from your own ! 630: function definitions to take precedence over the information ! 631: contained in the ! 632: .B SYSCALLS.c.X ! 633: file. ! 634: .PP ! 635: .I Thisprog ! 636: changes ! 637: #ifndef UNPRO ! 638: (and possibly adds to) ! 639: #endif ! 640: your original source code ! 641: in ways which may require you to rearrange the placement of other ! 642: items in your code. Specifically, it is often necessary to move ! 643: around type definitions or declarations for ! 644: .B "enum, struct," ! 645: and ! 646: .B union ! 647: types. ! 648: #ifndef UNPRO ! 649: .PP ! 650: Usage of ! 651: .I thisprog ! 652: may cause source lines to grow quite long and thereby become difficult ! 653: to read and to edit. Fortunately, ! 654: .I thisprog ! 655: is intelligent enough to automatically break up very long lines containing ! 656: newly inserted function prototypes whenever the length of ! 657: any given output line would otherwise exceed 79 columns (including tabs ! 658: to standard UNIX tab stops). ! 659: .PP ! 660: Note that in traditional (K&R) C, it was not possible to declare ! 661: parameter types for ! 662: .B "function pointer" ! 663: parameters and variables. ! 664: Such function pointer variables could only be ! 665: declared with empty parameter lists in traditional C. Unfortunately, ! 666: this means that ! 667: .I thisprog ! 668: typically ! 669: has no adequate source of information from which to manufacture ! 670: appropriate (prototyped) formal argument lists for such function pointer ! 671: variables. Thus, declarations of function pointer variables and ! 672: parameters will not be properly converted by ! 673: .I thisprog. ! 674: In the case of function pointer variables, ! 675: .I thisprog ! 676: currently performs no conversion whatsoever. ! 677: In the case of function pointer parameters however, ! 678: .I thisprog ! 679: will attempt to do half-hearted conversions by ! 680: manufacturing formal parameter lists for such parameters. ! 681: These manufactured formal parameter lists will look ! 682: like \`\.\.\.\'. ! 683: #endif ! 684: .PP ! 685: #endif ! 686: It is naive to assume that the conversions performed by ! 687: .I thisprog ! 688: are sufficient to make your source code completely compatible with ! 689: #ifndef UNPRO ! 690: ANSI C or C++. ! 691: #else ! 692: K&R C. ! 693: #endif ! 694: The automatic conversion of your source files via ! 695: .I thisprog ! 696: is only one step (albeit a big one) towards ! 697: full conversion. A full conversion may also require ! 698: lots of editing "by hand". ! 699: .PP ! 700: .I Thisprog ! 701: only converts function declarations and definitions. No conversion of ! 702: .I types ! 703: (such as function types and pointer-to-function types) ! 704: contained in ! 705: .B typedef ! 706: statements is attempted. These must be converted manually. ! 707: #ifdef UNPRO ! 708: .PP ! 709: Naive conversion of source code via ! 710: .I thisprog ! 711: may introduce bugs into the resulting (converted) code unless you are very ! 712: careful. The reason for this is rather subtle. ! 713: Basically, when a call is made to a prototyped function, the types of ! 714: some of the parameter values in the call may be implicitly converted ! 715: to the types of the corresponding formal parameters (as declared in the ! 716: function prototype). These implicit conversions can (occasionally) involve ! 717: changes of representation for the passed values (for instance from int ! 718: to float). Unfortunately, once your code has been converted via ! 719: .I thisprog, ! 720: these implicit conversions will no longer take place within the function ! 721: calls which require them. ! 722: .PP ! 723: The only remedy for this problem (currently) is for users of ! 724: .I thisprog ! 725: to make sure that explicit casts are inserted into calls which will force ! 726: these type conversions to occur even in the absence of function ! 727: prototypes. Users can determine the exact set of places where such explicit ! 728: casts may be required by compiling all code to be converted using the ! 729: .B -Wconversion ! 730: option to GCC prior to conversion. The warnings produced by ! 731: .B -Wconversion ! 732: will indicate those places in the original source code where explicit ! 733: casts must be inserted. Once these explicit casts have been manually ! 734: inserted (and the warnings from ! 735: .B -Wconversion ! 736: eliminated), conversion may be performed without any possibility of ! 737: generating code which is incorrect due to missed type conversions. ! 738: #else ! 739: .PP ! 740: When converting to full prototype format, it may often be the case that ! 741: complete information regarding the types of function parameters is not ! 742: actually avaiable in the original (K&R) code. ! 743: This will almost always be the case for parameters whose types are ! 744: pointer-to-function types. ! 745: For pointer-to-function parameters, it it customary (in K&R C) to ! 746: omit the types of the arguments which the pointed-to function expects ! 747: to receive. ! 748: In cases where the argument types for function pointer parameters are ! 749: not present in the original source code, ! 750: .I thisprog ! 751: notes this lack of complete information in a useful (but harmless) ! 752: way. After conversion, the (prototyped) parameter lists for ! 753: pointer-to-function parameters are represented in the converted ! 754: files as comments which contain the string "???". You can easily ! 755: locate all such strings after conversion (using your favorite editor) ! 756: and replace them with more complete information regarding the ! 757: true parameter profile of the pointed-to functions. ! 758: #endif ! 759: .SH WARNINGS ! 760: There are numerous possible warning and error messages which ! 761: .I thisprog ! 762: may issue for strange circumstances (e.g.\ missing input ! 763: files, etc.) or for noteworthy conditions in the source code being converted. ! 764: These should all be self-explanatory. ! 765: If any message is not self-explanatory, it\'s a bug. Please report it. ! 766: .SH FILES ! 767: .ta 3.0i ! 768: /usr/local/bin/gcc GNU C compiler ! 769: .br ! 770: /usr/local/bin/thisprog the thisprog program ! 771: #ifndef UNPRO ! 772: .br ! 773: /usr/local/lib/SYSCALLS.c.X aux info file for system functions ! 774: #endif ! 775: .SH "SEE ALSO" ! 776: gcc(1), g++(1), otherprog(1) ! 777: .SH BUGS ! 778: .I Thisprog ! 779: can easily be confused by ! 780: source code which has ! 781: macro calls in the ! 782: vicinity of something which it has to convert. ! 783: Fortunately, such cases seem to be rare in practice. ! 784: This is an inherent problem with the compiler ! 785: based approach to information gathering and will likely never be fixed. ! 786: When it does become confused, ! 787: .I thisprog ! 788: will still proceed to convert the file it is working on as much as ! 789: possible. Only the particularly confusing function definitions and ! 790: declarations will fail to be converted. These can subsequently be converted ! 791: manually. ! 792: .PP ! 793: Due to the method currently used to gather information, ! 794: .I thisprog ! 795: will fail to convert function declarations and definitions which ! 796: are located in conditional compilation sections which were ! 797: .I "preprocessed out" ! 798: during the creation of the ! 799: .B .X ! 800: files used for conversion. ! 801: You can generally work around this problem by doing ! 802: repeated conversion steps using ! 803: .I thisprog, ! 804: each with a different set of compilation options (i.e.\ preprocessor ! 805: symbol definitions) but assuring complete conversion can ! 806: currently only be done by visual inspection. ! 807: Currently, ! 808: .I thisprog ! 809: attempts to find function definitions which were ! 810: .I "preprocessed out" ! 811: and to issues warnings for such cases. ! 812: A later revision of ! 813: .I thisprog ! 814: #ifndef UNPRO ! 815: may also be able to detect cases where function declarations ! 816: have been ! 817: .I "preprocessed out" ! 818: and to issue appropriate warnings for those cases also. ! 819: #else ! 820: may be able to convert both function declarations and function ! 821: definitions which have been ! 822: .I "preprocessed out." ! 823: #endif ! 824: .PP ! 825: Currently, ! 826: .I thisprog ! 827: makes no attempt to convert declarations of ! 828: .I "pointer to function" ! 829: types, variables, or fields. ! 830: #ifdef UNPRO ! 831: A later version of ! 832: .I thisprog ! 833: may attempt to perform conversions of these ! 834: declarative items also. ! 835: #endif ! 836: .PP ! 837: Currently, ! 838: .I from_convention ! 839: functions definitions ! 840: #ifndef UNPRO ! 841: and declarations ! 842: #endif ! 843: must be converted by hand to use the ! 844: .I to_convention ! 845: convention. ! 846: It is possible that a subsequent version of ! 847: .I thisprog ! 848: will make some attempt to do these conversions automatically. ! 849: .PP ! 850: .I Thisprog ! 851: may get confused if it finds that it has to convert a function ! 852: declaration or definition in a region of source code where ! 853: there is more than one formal parameter list present. ! 854: Thus, attempts to convert code containing ! 855: multiple (conditionally compiled) versions of a single ! 856: function header (in the same vicinity) may not produce ! 857: the desired (or expected) results. ! 858: If you plan on converting source files which contain ! 859: such code, it is recommended that you first make sure ! 860: that each conditionally compiled region of source ! 861: code which contains an alternative function header ! 862: also contains at least one additional follower token ! 863: (past the final right parenthesis of the function header). ! 864: This should circumvent the problem. ! 865: #ifdef UNPRO ! 866: .PP ! 867: .I Thisprog ! 868: can become confused when trying to convert a function ! 869: definition or declaration ! 870: which contains a declaration for a ! 871: .I pointer-to-function ! 872: formal argument ! 873: which has the same name as the function being defined or ! 874: declared. ! 875: Such unfortunate choices of formal parameter names are discouraged. ! 876: #endif ! 877: .PP ! 878: Bugs (and requests for reasonable enhancements) should be reported to ! 879: [email protected]. Bugs may actually be fixed if they can be easily ! 880: reproduced, so it is in your interest to report them ! 881: in such a way that reproduction is easy. ! 882: .SH COPYING ! 883: Copyright (c) 1989, 1990 Free Software Foundation, Inc. ! 884: .sp 1 ! 885: Permission is granted to make and distribute verbatim copies of ! 886: this manual provided the copyright notice and this permission notice ! 887: are preserved on all copies. ! 888: .sp 1 ! 889: Permission is granted to copy and distribute modified versions of this ! 890: manual under the conditions for verbatim copying, provided that the ! 891: entire resulting derived work is distributed under the terms of a ! 892: permission notice identical to this one. ! 893: .sp 1 ! 894: Permission is granted to copy and distribute translations of this ! 895: manual into another language, under the above conditions for modified ! 896: versions, except that this permission notice may be included in ! 897: translations approved by the Free Software Foundation instead of in ! 898: the original English. ! 899: .SH AUTHORS ! 900: Written by Ronald F.\ Guilmette at the Microelectronics and Computer Technology ! 901: Corporation (MCC). Generously donated by MCC to the Free Software ! 902: Foundation. ! 903: .sp 1 ! 904: See the GNU C Compiler Manual for a list of contributors to GNU C.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.