New command `save'

[Jose E. Marchesi]

Hi people!

I just committed support for a new poke command, to make some company to
poor lonely `dump' :)

It is very useful to extract stuff from binary files.
See below an excerpt from the manual.

Now, what would be the right name for a command that does the reverse
than `save'?  i.e. a command that reads a region of data from a file and
fills it in the current IO space...  suggestions?  `restore' sounds
ugly, even if it is the opposite action of "saving"...

14 'save'
*********

Use the 'save' command in order to write a region from an IO space into
a file in your file system.

   This command has the following prototype:

     defun save = (int ios = get_ios,
                   string file = "",
                   off64 from = 0#B,
                   off64 size = 0#B,
                   int append = 0) void:

All arguments are optional.  When invoked with no arguments, 'save' does
nothing.

   The arguments 'from' and 'size' are used to determine the region of
the IO space to save.  This is how you would extract and save the
contents of an ELF section to a file 'out.text':

     (poke) defvar s = elf_section_by_name (Elf64_Ehdr @ 0#B, ".text")
     (poke) save :file "out.text" :from s.sh_offset :size s.sh_size

Both 'from' and 'size' are arbitrary offsets.  You should keep in mind
however that files are byte oriented.  Therefore saving, say, nine bits
to a file will actually write two bytes.

   By default 'save' will extract the data from the "current IO space".
However, it is possible to specify an alternative IOS by using the 'ios'
argument.

   By default 'save' will truncate the output file, if it exists, before
starting writing.  If the argument 'append' is set as true, however, it
will append to the existing contents of the file.  In this case, the
file should exist.