packages icon






























































                                    - 1 -         Formatted:  March 29, 2024






 PROTOIZE(1)                                                     PROTOIZE(1)
                               21 January 1990



 NAME
      protoize - convert K&R C source code to ANSI C prototype format




 SYNOPSIS
      protoize [.B -VqfnkNlgC ] [ -B <dir>






      ] [ -c <cc opts> ] [ file... ]

 DESCRIPTION
      Protoize aids in the conversion of

      K&R C source code files to ANSI C  source  code  files  with  function
      prototypes.   This  conversion  is  useful for eliciting more complete
      interface checking from ANSI C compilers, or as a preliminary step  in
      the conversion of C programs to C++.







      Protoize is designed  to  be  used  in  conjunction  with  the  GNU  C
      compiler.   The  GNU C compiler does preliminary information gathering
      about functions by analyzing the files to be  converted.   The  GNU  C
      compiler  may be invoked automatically as a result of running protoize
      so it is important to have it properly installed before attempting  to
      convert source files via protoize.


      Protoize actually has  two  primary  functions.   First,  It  converts
      existing  function  declarations  and  definitions  to prototype form.
      Second, for cases in which functions are called before they have  been
      declared (i.e. points of implicit function declarations), protoize can
      be instructed to insert new prototype style function declarations into
      the  source  code.   For  implicit function declarations, protoize can
      either insert the new (explicit)  function  declaration  at  the  very
      beginning of the block which contains the implicit declaration, or (at
      the user's option) these explicit declarations can  be  inserted  near
      the tops of the source files where the implicit declarations occurred.
      The insertion  of  these  new  (explicit)  function  declarations  (by
      protoize) assures that all function calls in your source files will be
      checked  for  the  correct  number  and  types  of  parameters  during



                                    - 1 -         Formatted:  March 29, 2024






 PROTOIZE(1)                                                     PROTOIZE(1)
                               21 January 1990



      subsequent compilations.


      Protoize supports the conversion of both large and small systems of  C
      source code to prototype form.

      Protoize can perform the  conversion  of  an  entire  program  in  one
      (batch) step.


      Protoize is able to convert entire systems of C source code because it
      knows  how  to  use  information  (gleaned by the C compiler) from one
      source file to convert function definitions and declarations  in  that
      same source file or in other source files (as required).


      Each conversion of a  system  of  source  code  to  prototyped  format
      consists of two major steps.  First, there is an information gathering
      step.  In this step, all of the source files  that  make  up  a  given
      executable  program  are recompiled using the GNU C compiler and using
      the -fgen-aux-info option.  These  recompilations  will  be  performed
      automatically by protoize on an as needed basis.

      As individual compilation steps are performed, you may notice  that  a
      side-effect  of these compilations is to create files with a .X suffix
      in the same directory  with  the  original  base  source  files  being
      compiled.  During compilation with -fgen-aux-info, one such .X file is
      created for each base  source  file  compiled.   These  files  contain
      information about function definitions and declarations and additional
      coded information which can be used by protoize to convert your source
      code automatically to prototyped format.


      After a full set of .X files corresponding to  all  of  the  .c  (i.e.
      base  source)  files  for  an  individual  program  have been created,
      protoize performs the actual conversion step.

      Execution of the protoize program causes your original source files to
      be  converted  such  that  both  their function declarations and their
      function definitions are in prototyped format.  After  the  conversion
      of your system, you will be left with a set of similar (but converted)
      source files with the same names as your original files.

      Before it writes each converted file back to disk,  protoize  attempts
      to  rename  the  original  file,  giving  it  a .save suffix.  It then
      creates a new output file with the same name that  the  original  file
      had.   This  ensures that if there were any hard links to the original
      input files, these will not be altered by the conversion process.

      WARNING!  If for any given original file, a save file already  exists,
      protoize  will assume that the existing save file contains a backup of



                                    - 2 -         Formatted:  March 29, 2024






 PROTOIZE(1)                                                     PROTOIZE(1)
                               21 January 1990



      the original file as it existed before any conversions  were  applied.
      Thus,  if  there is an existing save file, protoize will not overwrite
      this existing save file, and no new backup of that particular original
      file will be made during that run of protoize.

      An important safety feature of protoize is that it normally only tries
      to  convert  files for which you have both read and write permissions.
      Also, protoize will normally only convert files located in directories
      that you have both search and write permissions for.

      Another safety feature is that  protoize  will  not  normally  convert
      files  which  are  located  in  system  include directories.  A system
      include directory is defined by protoize as  either  /usr/include  (or
      any of its subdirectories) or a directory whose full absolute pathname
      includes either gcc-include or g++-include.

      Most of the above safety features can be overridden by  using  the  -f
      (force) option (see below), but even when -f is used, you cannot force
      the conversion of files for which  you  do  not  at  least  have  read
      permission,  or  files  in  directories  that you do not at least have
      write permission for.

      Note that protoize will make no  attempt  to  convert  definitions  or
      declarations  of functions which accept a variable number of arguments
      and which  are  written  using  the  varargs  conventions.   All  such
      function  definitions  and  declarations must be converted manually to
      the stdarg conventions.  Warnings are automatically issued for varargs
      function  definitions  and  declarations which are left unconverted by
      protoize.

 OPTIONS
      Protoize recognizes the following options:

      -V   Version number.  Causes the current version number to be  printed
           on stderr.

      -q   Quiet mode.  Normally, protoize may issue many  verbose  warnings
           concerning  noteworthy  conditions.   These warnings can often be
           helpful to the overall conversion effort.  Users who  prefer  not
           to  see such messages can use the -q option which suppresses most
           such warnings.

      -f   Force mode.  Use of  this  option  overrides  the  normal  safety
           features  of  protoize.  It allows for attempts to convert system
           include files, and files not writable by you.  These  conversions
           are  still subject to all normal file protections provided by the
           operating system.  This option should be used only  with  extreme
           caution.   It can be especially dangerous to use this option when
           logged on as root. Note that when this option is  used,  you  are
           allowed  to  convert even files that you do not have write access
           to.   So  long  as  you  have  write  access  to  the  containing



                                    - 3 -         Formatted:  March 29, 2024






 PROTOIZE(1)                                                     PROTOIZE(1)
                               21 January 1990



           directory, conversion may occur.

      -n   No convert mode.  Do not actually perform any conversions on base
           source  files  or  on include files.  Rather, simply do all steps
           leading up to conversion and then print a list (to stdout) of the
           names  of  all  files  which  would  actually  be modified if the
           conversions were actually performed.  This option may  be  useful
           to  you  if  you are converting a system of source files that you
           are unfamiliar with.  In such cases, you may need to verify ahead
           of  time  that  include  files which belong to other people or to
           other projects will not be modified by running protoize.  Use  of
           this option also implicitly enables keep mode. (See the -k option
           below.)

      -k   Keep mode.  Normally, protoize reads the information  in  the  .X
           files created by the GNU C compiler, and then immediately deletes
           these files (since they will no longer be valid or  useful  after
           conversion).   When  the  -k option is used however, the .X files
           are not deleted during conversion.

      -N   No save mode.  When this option is used, no attempt  is  made  to
           make  backups  of original files (by renaming them such that they
           have an added  .save  suffix).   Use  this  option  with  extreme
           caution,  and  only when you have previously backed up all of the
           files that might be converted by running protoize.  (See  the  -n
           option above.)

      -c <cc opts>
           Specify compile options.  The -c option can be used as a means of
           passing  on  important compilation options to the C compiler.  It
           may often be necessary to use this option to  pass  command  line
           preprocessor  definitions  on to the compilation step.  Note that
           The compile options  must  be  given  as  a  single  argument  to
           protoize.  If you have more than one compilation option, you will
           have to quote the entire set of compilation options in  order  to
           keep  the  shell  from  treating  them  as  separate arguments to
           protoize.  Note  also  that  certain  options  are  automatically
           suppressed  by  protoize  and cannot be passed on to the compiler
           (i.e.  -g, -O, -c, -S, and -o are suppressed).


      -C   C++ conversion mode.  Normally, protoize writes  its  (converted)
           output  files  back  to  files  of the same names as the original
           (unconverted) input files.  In C++ conversion  mode,  after  each
           output  file  is  written,  a  check  is made to see if the given
           output file has a .c suffix.  If it does, then the given file  is
           renamed,  and  its suffix is changed to .C. This makes the output
           file acceptable as a C++  input  file  for  either  the  GNU  C++
           compiler or for the Cfront translator.





                                    - 4 -         Formatted:  March 29, 2024






 PROTOIZE(1)                                                     PROTOIZE(1)
                               21 January 1990



      -l   Add explicit local declarations.  This option causes protoize  to
           insert   explicit  declarations  for  functions  that  were  only
           implicitly declared in the original source  code.   When  the  -l
           option  is  used,  lists  of  additional  new  explicit  function
           declarations  are  inserted  near  the  starts  of  blocks  where
           explicit  function  declarations  took  place.   (See also the -g
           option below.)

      -g   Add explicit global declarations.  This option causes protoize to
           insert   explicit  declarations  for  functions  that  were  only
           implicitly declared in your original source code.   When  the  -g
           option  is  used,  a  list  of  additional  new explicit function
           declarations  is  inserted  just  before   the   first   function
           definition   in  each  individual  source  file  that  previously
           contained implicit declarations.  (See also the -l option above.)

      -B <dir>
           Alternate library directory option.  Use this option  to  specify
           that protoize should attempt to find the file SYSCALLS.c.X in the
           alternate directory indicated in the option.


 EXAMPLES
      Assume that you have a directory with all of the files for your system
      in  it.   Also  assume  that  your  system  consists of two executable
      programs, one built from the files s1.c, s2.c, and s3.c, and the other
      built  from the files s4.c and s5.c. Finally, assume that these source
      files share some common include files.

      In order to properly convert such a system of programs, you would need
      to perform the steps shown below.

           protoize s1.c s2.c s3.c
           protoize s4.c s5.c


      In the example above, the first invocation of protoize causes three .X
      files  (called s1.c.X, s2.c.X, and s3.c.X) to be created.  These files
      are generated automatically by  protoize  (which  invokes  the  GNU  C
      compiler  to  create  them).   These  files  contain information about
      function definitions and declarations both for their corresponding  .c
      files and for any files which are included by these base .c files.

      After protoize has invoked the compiler for each of  the  files  which
      make  up  prog1, it performs the actual conversion of these base files
      (and may perform some conversion of their include files depending upon
      the information available in the .X files).  Finally, after performing
      all necessary conversions, protoize automatically  deletes  the  files
      s1.c.X, s2.c.X, and s3.c.X.





                                    - 5 -         Formatted:  March 29, 2024






 PROTOIZE(1)                                                     PROTOIZE(1)
                               21 January 1990



      After performing the conversion for prog1, (as illustrated above)  you
      would  then request protoize to convert all of the files which make up
      prog2 in a similar fashion.  This step would create two more .X  files
      (called  s4.c.X and s5.c.X). As with the conversion of prog1, protoize
      will automatically generate any needed .X files (by invoking the GNU C
      compiler), will perform the conversion of all of the given base source
      files (and possibly do some conversion on  include  files),  and  will
      finish  up  by automatically deleting the .X files that were generated
      during this run.

      You may occasionally find  that  you  need  to  convert  a  particular
      program  which  consists  of  several base source files, some of which
      must be compiled with unusual options.  In such cases, you  can  still
      convert  the  program  via  a special mechanism.  For each base source
      file which requires special compilation  options,  you  can  create  a
      corresponding  .X  file  for the base file (before invoking protoize).
      You would do this by invoking the GNU C  compiler  directly  with  the
      required   special   options,  and  with  the  -fgen-aux-info  option.
      Protoize is smart enough to use  existing  .X  files  (when  they  are
      available  and when they are up to date) so creating .X files ahead of
      time with the GNU C compiler is an easy  way  to  accommodate  unusual
      compilation options for individual base files.

      Note that protoize checks each preexisting .X file before it tries  to
      use it in order to insure that it is up-to-date with respect to all of
      the source files that it contains information about.   If  this  check
      fails,  protoize  will  automatically  invoke the GNU C compiler (with
      default options) to recreate the needed .X file.

 CAVEATS
      The protoize program doesn't just get information  from  your  own  .X
      files.    Every   time   protoize  executes,  it  also  reads  a  file
      SYSCALLS.c.X from some standard installation directory (if it  exists)
      to  obtain  a  pre-written  set  of  function  prototypes  for various
      standard system-supplied functions.  These prototypes are  effectively
      added  to  the  set  of  prototypes  which protoize can use to perform
      prototype substitutions on your source files.  If the source code  for
      any  individual  programs  that  you  are  converting contains its own
      definitions for functions with the  same  names  as  standard  system-
      supplied  functions,  protoize  is  intelligent  enough  to  allow the
      parameter typing from your own function definitions to take precedence
      over the information contained in the SYSCALLS.c.X file.

      Protoize changes (and possibly adds to) your original source  code  in
      ways  which  may require you to rearrange the placement of other items
      in your code.  Specifically, it is often necessary to move around type
      definitions or declarations for enum, struct, and union types.


      Usage of protoize may cause  source  lines  to  grow  quite  long  and
      thereby  become  difficult to read and to edit.  Fortunately, protoize



                                    - 6 -         Formatted:  March 29, 2024






 PROTOIZE(1)                                                     PROTOIZE(1)
                               21 January 1990



      is intelligent enough  to  automatically  break  up  very  long  lines
      containing  newly  inserted function prototypes whenever the length of
      any given output line would otherwise  exceed  79  columns  (including
      tabs to standard UNIX tab stops).

      Note that in traditional (K&R) C,  it  was  not  possible  to  declare
      parameter  types  for function pointer parameters and variables.  Such
      function pointer variables could only be declared with empty parameter
      lists  in  traditional  C.   Unfortunately,  this  means that protoize
      typically  has  no  adequate  source  of  information  from  which  to
      manufacture  appropriate  (prototyped)  formal argument lists for such
      function pointer variables.  Thus, declarations  of  function  pointer
      variables  and  parameters will not be properly converted by protoize.
      In  the  case  of  function  pointer  variables,  protoize   currently
      performs  no  conversion  whatsoever.  In the case of function pointer
      parameters  however,  protoize  will  attempt   to   do   half-hearted
      conversions   by   manufacturing   formal  parameter  lists  for  such
      parameters.  These manufactured formal parameter lists will look  like
      `...'.


      It is naive to assume that the conversions performed by  protoize  are
      sufficient  to make your source code completely compatible with ANSI C
      or C++. The automatic conversion of your source files via protoize  is
      only  one  step  (albeit  a  big one) towards full conversion.  A full
      conversion may also require lots of editing "by hand".

      Protoize only converts  function  declarations  and  definitions.   No
      conversion  of  types  (such as function types and pointer-to-function
      types) contained in typedef statements is attempted.   These  must  be
      converted manually.


      When converting to full prototype format, it may  often  be  the  case
      that  complete  information regarding the types of function parameters
      is not actually available in  the  original  (K&R)  code.   This  will
      almost  always  be the case for parameters whose types are pointer-to-
      function types.  For pointer-to-function parameters, it  it  customary
      (in  K&R  C)  to  omit the types of the arguments which the pointed-to
      function expects to receive.  In cases where the  argument  types  for
      function  pointer  parameters  are  not present in the original source
      code, protoize notes this lack of complete  information  in  a  useful
      (but  harmless)  way.   After  conversion,  the (prototyped) parameter
      lists  for  pointer-to-function  parameters  are  represented  in  the
      converted  files  as comments which contain the string "???".  You can
      easily locate all such strings after conversion (using  your  favorite
      editor)  and replace them with more complete information regarding the
      true parameter profile of the pointed-to functions.






                                    - 7 -         Formatted:  March 29, 2024






 PROTOIZE(1)                                                     PROTOIZE(1)
                               21 January 1990



 WARNINGS
      There are numerous possible warning and error messages which  protoize
      may  issue  for strange circumstances (e.g. missing input files, etc.)
      or for noteworthy conditions  in  the  source  code  being  converted.
      These  should  all  be  self-explanatory.  If any message is not self-
      explanatory, it's a bug.  Please report it.

 FILES
      /usr/local/bin/gcc            GNU C compiler
      /usr/local/bin/protoize       the protoize program

      /usr/local/lib/SYSCALLS.c.X   aux info file for system functions


 SEE ALSO
      gcc(1), g++(1), unprotoize(1)

 BUGS
      Protoize can easily be confused by source code which has  macro  calls
      in  the  vicinity  of something which it has to convert.  Fortunately,
      such cases seem to be rare in practice.  This is an  inherent  problem
      with  the  compiler  based  approach to information gathering and will
      likely never be fixed.  When it does become  confused,  protoize  will
      still  proceed  to  convert  the  file  it  is  working  on as much as
      possible.  Only the particularly confusing  function  definitions  and
      declarations  will  fail  to  be converted.  These can subsequently be
      converted manually.

      Due to the method currently used to gather information, protoize  will
      fail  to  convert  function  declarations  and  definitions  which are
      located in conditional compilation sections  which  were  preprocessed
      out  during the creation of the .X files used for conversion.  You can
      generally work around this problem by doing repeated conversion  steps
      using  protoize,  each  with  a  different  set of compilation options
      (i.e. preprocessor   symbol   definitions)   but   assuring   complete
      conversion   can   currently   only  be  done  by  visual  inspection.
      Currently, protoize attempts to find function definitions  which  were
      preprocessed  out  and  to  issues  warnings  for such cases.  A later
      revision of protoize may also be able to detect cases  where  function
      declarations  have  been  preprocessed  out  and  to issue appropriate
      warnings for those cases also.






      Currently, protoize  makes  no  attempt  to  convert  declarations  of
      pointer to function types, variables, or fields.





                                    - 8 -         Formatted:  March 29, 2024






 PROTOIZE(1)                                                     PROTOIZE(1)
                               21 January 1990



      Currently, varargs functions  definitions  and  declarations  must  be
      converted by hand to use the stdarg convention.  It is possible that a
      subsequent version of protoize will make  some  attempt  to  do  these
      conversions automatically.

      Protoize may get confused if  it  finds  that  it  has  to  convert  a
      function  declaration  or  definition in a region of source code where
      there is more than one formal parameter list present.  Thus,  attempts
      to  convert code containing multiple (conditionally compiled) versions
      of a single function header (in the same vicinity) may not produce the
      desired (or expected) results.  If you plan on converting source files
      which contain such code, it is recommended that you  first  make  sure
      that  each conditionally compiled region of source code which contains
      an alternative function header also contains at least  one  additional
      follower  token  (past  the  final  right  parenthesis of the function
      header).  This should circumvent the problem.


      Bugs (and requests for reasonable enhancements) should be reported  to
      bug-gcc@prep.ai.mit.edu.   Bugs  may  actually be fixed if they can be
      easily reproduced, so it is in your interest to report them in such  a
      way that reproduction is easy.

 COPYING
      Copyright (c) 1989, 1990 Free Software Foundation, Inc.

      Permission is granted to make and distribute verbatim copies  of  this
      manual  provided  the  copyright notice and this permission notice are
      preserved on all copies.

      Permission is granted to copy and distribute modified versions of this
      manual  under  the  conditions for verbatim copying, provided that the
      entire resulting derived work is distributed  under  the  terms  of  a
      permission notice identical to this one.

      Permission is granted to copy  and  distribute  translations  of  this
      manual  into another language, under the above conditions for modified
      versions, except that  this  permission  notice  may  be  included  in
      translations  approved  by  the Free Software Foundation instead of in
      the original English.

 AUTHORS
      Written by Ronald F. Guilmette at the  Microelectronics  and  Computer
      Technology  Corporation  (MCC).  Generously donated by MCC to the Free
      Software Foundation.

      See the GNU C Compiler Manual for a list of contributors to GNU C.







                                    - 9 -         Formatted:  March 29, 2024