sourcerer  -  generate  source code corresponding to input

       sourcerer [language] [options] executable_file
       sourcerer [A AL AP B C  C++  CO	F  I  L	M  P  PL  PR  S]
       [csoavOVT]   [I	file]	[L  file]  [P[sli]  prefix]  exe-

       sourcerer generates source code corresponding to the input
       executable  binary  file,  in  the chosen programming lan-
       guage.  The resulting source code is written  to	standard

       sourcerer  operates rapidly.  Due to the particular nature
       of the algorithms used, sourcerer will generate the source
       code  for  the  executable  file in a best case of no more
       than twice the time needed to execute file.

       Options allow the  user	to  generate  comments	with  the
       source	code,  and  to	provide	generalized  pseudo-code
       descriptions of any system calls made  in  the  executable
       file.  The pseudo-code description of system calls are, of
       course, in the proper syntax for the chosen language.

       Specifying valid command line options for  the  executable
       file will produce different source code file output.

       The available languages are:
		 Option Name		Language
		 A			Ada
		 AL			Algol68
		 AP			Apl
		 B			Basic
		 C			C
		 C++			C++
		 CO			Cobol
		 F			Fortran
		 I			Icon
		 L			Lisp
		 M			Modula2
		 P			Pascal
		 PE			Perl
		 PL			PL/I
		 PR			Prolog
		 S			Smalltalk
       Wherever	they  exist,  ANSI, POSIX,  or ISO standards for
       each language are used.	As is feasible, popular	variants
       in  each	language  are	offered	as  translation targets.
       These are specified with a series  of  lower-case  letters
       immediately  following  the  main  language argument.  For

		 Cw			Watcom C
		 Cm			Microsoft C
		 Cb			Borland C
		 Cg			Gnu C
		 Ckr			Kernigan and Ritchie ``classic'' C

       For some languages, sourcerer provides a choice in version
       level  in  translated  output.  See the -t option for more

       With version 2.0, sourcerer introduces a new feature.  The
       code  generation	and  pseudo-system calls can be tailored
       for a particular operating system.  The	currently  under-
       stood  operating	systems,  specified after the -O option,
       Operating System
		 BDS (Tahoe)
		 BSD (Mt. Xinu)
		 BSD on Intel (BSDI, FreeBSD)
		 Mac System 6.n
		 Mac System 7.n
		 Windows-NT (Alpha and PowerPC platforms only)

       Support for AT&T's Plan 9 is in beta-test now, with  final
       release	shipping  scheduled for 1Q 1996.  Support for the
       Intel COFF is anticipated for 3Q 1996.

       No support for MS-DOS  is  anticipated  due  to	intrinsic
       operating  system design deficiencies.  Due to those defi-
       ciencies, no translation to Windows95 or	other	Microsoft
       Windows	``operating  systems'' on the Intel platform with
       system calls is possible.

       The -V option displays the current version of sourcerer.

       The -T option displays a table of  all  operating  systems
       and   langauges	that  sourcerer	understands.	This  may
       include languages not  mentioned	in  this  documentation.

       When the -v (verbose) option is given, relevent version or
       standard numbers used for each operating	system	or  lan-
       guage description are shown.

       If a language is not specified, and the -a option is used,
       sourcerer scans the input executable file,  and	automati-
       cally  selects  the most efficient language to produce the
       source code and pseudo-code for system calls.  This option
       also implies the following options:

       -c	Generate  commented  source  code. These are not
		the comments from original source  code,  unless
		they  were included with the binary.  These com-
		ments map out sourcerer's choice of variable and
		function names, subroutine calls, etc.

       -s	Generate   pseudo-code	for  any  system  calls
		encountered in the executable file.   This  code
		is generated in-place in the resulting file. See
		the -P options.


       -L	These options allow the specification of include
		(header)  files  and compiled libraries, respec-
		tively.   Multiple  instances	of  each  may  be
		given.	Header files and libraries must be cho-
		sen so as not to conflict with the language  and
		operating  system  specifications.  They must be
		in a language and operating system recognized by
		sourcerer,  and  will	override  the  -a option.
		This code is generated in-place in the resulting
		file. See the -P options.

       The other option, -o, is incompatible with -a and -s.  The
       -o option specifies that only pseudo-code for  the  system
       calls  be  generated,  in  the  specified  language.  This
       option is most often used after sourcerer warns	that  the
       language chosen to generate the source code is inappropri-
       ate for generating the pseudo-code for system calls.

       The -P option optional and used only in	conjunction  with
       either the -s, -L or -I options.	This swith specifies the
       prefix for filenames created  additional	to  the  program
       source.	The -P options take a mandatory second letter to
       indicate the type of file:
		 Ps			system calls
		 Pi			include files
		 Pl			libraries
       The prefix following the -P option may  be  different  for
       each type of file.

       sourcerer -A -c new-executable > new-source.ADA

			      Local				3


		 Generate the Ada source code, commented, for the
		 program new-executable.
       sourcerer -a new-executable > new-source
		 Generate  commented   source	code   for   new-
		 executable, choosing the language for the source
		 code and  pseudo-coded	system	calls	automati-

       sourcerer  will	display	a warning indicating if the lan-
       guage chosen to produce the source code	is  inappropriate
       for the given executable.  Example:

       Warning: Ada is inefficient for translation of emacs.
       A  different warning is given if the language is appropri-
       ate for the executable, but not for producing the  pseudo-
       code  for  the system calls.  In this case, sourcerer will
       suggest an alternative language	to  produce  the  pseudo-
       coded system calls; in the form:
		 Warning:  language is inefficient for the system
		 calls, try language2.

       v2.3 Thu Sep 14 13:31:05 EDT 1995

       Mark Bergman (

       sourcerer has no understanding of GUI and may not be  able
       to  translate  graphics programs.  Future versions will be
       able to accept windowing	system	designations  much  like
       operating  system  specifications, and produce native code
       for the X Windows System, SunView, Phigs, and Geos.

       The translated code is  generally  a  single  source  code

       When   dealing	with  complex  binaries,  be  aware  that
       sourcerer cannot re-create the individual project files of
       the original source code; the resulting sourcerer file may
       be extremely large.  The file size depends upon the  suit-
       ability	of  the language chosen as well as the executable

       The -P option is new, and sometimes  sourcerer  gets  con-
       fused  about  what gets placed in a library, include file,
       or the main source file.	When in doubt, code is placed in
       the  main  source  file;	the resulting library or include
       files may be empty.  For the same reason, files containing
       system  calls  are  frequently  smaller	and contain fewer
       calls that the original language specified; the	remaining
       code is placed in the main source file.

       It  may	be  possible  to  generate  more complete header,
       included, and system call files by via  multiple	transla-
       tion  runs  with different options to the input executable
       file, and  considerable	cutting	and  pasting  among  the
       resulting output files.

       The -s or -a options may slow down the translation process
       considerably.   The  -a	option	in   particular   forces
       sourcerer  to scan the input executable multiple times and
       make take up to 2(n^2) to complete, where n  is	the  time
       needed to run the executable.

       Generating  library  or	included  files	via the -L or -I
       options can take processing time on the order of
                 _ /----------
		  V (2n)^2+t^2
       where n is the time needed to run the executable and t  is
       the  time needed to do a translation without the header or
       include files being generated separately.

       Generating pseudo-code corresponding to system  calls  can
       take  up	to  the product of the base translation time and
       the square of the time necessary to  execute  each  system
       call plus the time to run the executable.  Thus, combining
       the -s and -a options can take up to ( 2(n^2)+(t *(n+s)^2)
       )^2,  where  n is the time needed to run the executable, t
       is the base translation time, and s is the time needed  to
       execute the system calls.

       The  use of the -P options can have a severe impact on the
       translation time, as this  causes  sourcerer  to	generate
       both  the main source code and the chosen include, system,
       or header files	simultaneously.	Processing  time  (with
       appropriate  languages  chosen), with the options -s -I -L
       -Ps -Pl -Pi is roughly on the order of:
                 _ /--------------
	     2 *  V 2((2n)^2+t^2) *  (t*(n+s)^2)

       The -c option can also add considerable time  to	transla-

       sourcerer was written in a proprietary language, sourcerer
       cannot be applied recursively, as in:
		 sourcerer -C sourcerer > sourcerer.c
       Repeated invocations in this manner will permanently  dis-
       able the sourcer license.

       No  warranty  of use or fitness for any purpose is assumed
       or granted.   Use  at  your  own	risk.	The  authors  of
       sourcerer  respect  intellectual	property  and copyrights
       worldwide.  This product is only intented for educational,
       archival,  and data recovery purposes.  The authors assume
       no responsibility for unauthorized usage.


[an error occurred while processing this directive]