Imported Upstream version 1.2.1
[packages/binwalk.git] / docs / API
index 870d96c..abeffec 100644 (file)
--- a/docs/API
+++ b/docs/API
@@ -10,27 +10,29 @@ DESCRIPTION
 
 BASIC SCAN
 
-       This is the simplest scan, and is equivalent to running binwalk on the command line with no additional arguments.
-       Note the use of the cleanup() method, which will ensure all temporary files generated by binwalk are cleaned up:
+       The following is an example of the simplest scan, and is equivalent to running binwalk on the command line 
+       with no additional arguments:
 
+               import pprint
                from binwalk import Binwalk
 
-               binwalk = Binwalk()
-               results = binwalk.scan('firmware.bin')
-               binwalk.cleanup()
+               with Binwalk() as bw:
+                       pprint.PrettyPrinter().pprint(bw.scan('firmware.bin'))
 
-       The scan() method will return a list of tuples, one tuple for each offset in the target file where a matching
-       signature was found. The first element of each tuple is the offset into the file at which the match was found. 
-       The second tuple is a list of dictionaries (depending on the binwalk options, there may be more than one match 
-       for a given offset); each dictionary describes a matching signature:
+       The scan() method will return a dictionary of results, and may also be passed a list of files:
+
+               from binwalk import Binwalk
 
-               results = [
-                               (0, [{description : "LZMA compressed data..."}]),
-                               (112, [{description : "gzip compressed data..."}]),
-               ]
+               with Binwalk() as bw:
+                       for (filename, file_results) in bw.scan(['firmware1.bin', 'firmware2.bin']).iteritems():
+                       print "Results for %s:" % filename
+                       for (offset, results) in file_results:
+                               for result in results:
+                                       print offset, result['description']
 
-       A callback function may also be specified. The callback function is called as soon as a match is identified. It
-       is passed two arguments: the offset at which the match was found, and a list of dictionaries as described above:
+       Alternatively, a callback function may be specified. The callback function is called as soon as a match is found. 
+       It is passed two arguments: the offset at which the match was found, and a list of results dictionaries (one dictionary 
+       per result found at that offset):
 
                from binwalk import Binwalk
 
@@ -39,35 +41,33 @@ BASIC SCAN
                        for result in results:
                                print " %s" % result['description']
 
-               binwalk = Binwalk(callback=my_callback)
-               binwalk.scan('firmware.bin')
-               binwalk.cleanup()
+               with Binwalk() as bw:
+                       bw.scan('firmware.bin', callback=my_callback)
 
 
 ADDING FILTERS
 
-       Include and exclude filters may be specified which operate identically to the --include, --exclude and --search
-       binwalk command line options:
+       Include and exclude filters may be specified which operate identically to the --include, and --exclude binwalk
+       command line options:
 
                from binwalk import Binwalk
                
                binwalk = Binwalk()
                
-               # Adds a normally excluded signature to the existing list of signatures (same as --include)
-               binwalk.filter.include('minix', exclusive=False)
-
-               # Exclusively filters out all signatures except those containing the string 'filesystem' (same as --search)
+               # Exclusively filters out all signatures except those containing the string 'filesystem' (same as --include)
                binwalk.filter.include('filesystem')
 
                # Excludes all results that contain the string 'jffs2' (same as --exclude)
                binwalk.filter.exclude('jffs2')
 
                binwalk.scan('firmware')
+               binwalk.cleanup()
 
 
 EXTRACTING FILES
 
        Extract rules may be specified which operate identically to the --dd and --extract binwalk command line options.
+       Extraction is automatically enabled when one or more extraction rules are specified.
        
        To add a custom extract rule, or a list of extract rules (such as with the --dd option):
 
@@ -82,6 +82,7 @@ EXTRACTING FILES
                binwalk.extractor.add_rule(['gzip:gz', 'filesystem:fs'])
 
                binwalk.scan('firmware')
+               binwalk.cleanup()
 
        To load the default extraction rules from the extract.conf file (such as with the --extract option):
        
@@ -89,8 +90,8 @@ EXTRACTING FILES
                
                binwalk = Binwalk()
                binwalk.extractor.load_defaults()
-               binwalk.Scan('firmware.bin')
-
+               binwalk.scan('firmware.bin')
+               binwalk.cleanup()
 
        To enabled delayed file extraction (such as with the --delay option):
 
@@ -98,7 +99,8 @@ EXTRACTING FILES
                
                binwalk = Binwalk()
                binwalk.extractor.enable_delayed_extract(True)
-               binwalk.Scan('firmware.bin')
+               binwalk.scan('firmware.bin')
+               binwalk.cleanup()
 
        To enable file cleanup after extraction (such as with the --rm option):
 
@@ -106,5 +108,6 @@ EXTRACTING FILES
                
                binwalk = Binwalk()
                binwalk.extractor.cleanup_extracted_files(True)
-               binwalk.Scan('firmware.bin')
+               binwalk.scan('firmware.bin')
+               binwalk.cleanup()