SOURCERER(1) SOURCERER(1)
NAME
sourcerer - generate source code corresponding to input
executable.
SYNOPSIS
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-
cutable_file
DESCRIPTION
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
output.
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
example:
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
details.
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,
include:
Operating System
AIX
AUX
BDS (Tahoe)
BSD (Mt. Xinu)
BSD on Intel (BSDI, FreeBSD)
CP/M
Linux-Elf
Linux-a.out
Mac System 6.n
Mac System 7.n
Minix
Multics
OS/2
OS9
OSF/1
SYSV3
SYSV4
TOPS20
Ultrix
VMS
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.
OPTIONS
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.
-I
-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.
EXAMPLES
sourcerer -A -c new-executable > new-source.ADA
Local 3
SOURCERER(1) SOURCERER(1)
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-
cally.
DIAGNOSTICS
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.
VERSION
v2.3 Thu Sep 14 13:31:05 EDT 1995
AUTHOR
Mark Bergman (bergman@panix.com)
BUGS
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
file.
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
itself.
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.
EFFICIENCY CONSIDERATIONS
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-
tion.
WARNINGS
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.
SOURCERER(1) SOURCERER(1)
[an error occurred while processing this directive]