Re: [RFA, 3 of 3] save/restore process record, part 3 (save/restore)

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 16 Oct 2009 18:27:14 -0700
> From: Michael Snyder <msnyder@vmware.com>
> 
> If I need to resubmit the docs, I'll do that separately.

Yes, please.  It should document "record save" and "record restore".
An entry in NEWS is also in order.

What follows are mainly usability and UI related comments.

> +  if (record_debug)
> +    printf_filtered (_("Restoring recording from core file.\n"));

Debug messages are not supposed to be marked for translation.  (You
have several more of those in the patch.)

> +  printf_filtered ("Find precord section %s.\n",
> +		   osec ? "succeeded" : "failed");

Is this also a debug printout?  If so, why isn't it conditioned by
record_debug?  If it isn't, then why not marked for translation?  (I
think this kind of message should definitely be printed only under
record_debug.)

> +  bfdcore_read (core_bfd, osec, &magic, sizeof (magic), &bfd_offset);
> +  if (magic != RECORD_FILE_MAGIC)
> +    error (_("Version mis-match or file format error."));

It would be nice to say what file this refers to.

> +        default:
> +          error (_("Format of core file is not right."));

Suggest something like "Incorrect or unsupported format of core file."
"Not right" is too vague, IMO.

> +  printf_filtered ("Restored records from core file.\n");

This should be marked for translation.

> +  /* FIXME why doesn't this go in record_core_open?  */
> +  if (strcmp (current_target.to_shortname, "record_core") == 0)
> +    record_restore ();

Yes, why indeed?  Can this be resolved before the patch goes in?

> +     4 bytes: magic number htonl(0x20090829).
                              ^^^^^
Elsewhere in this documentation you use a more human-readable "network
byte order".

> +       NOTE: be sure to change whenever this file format changes!
> +
> +   Records:
> +     record_end:
> +       1 byte:  record type (record_end).
                                ^^^^^^^^^^
This probably has some integer value, right?  Or does this indicate
something other than an integer type?

> +     record_reg:
> +       1 byte:  record type (record_reg).
> +       4 bytes: register id (network byte order).
> +       n bytes: register value (n == register size).
                                        ^^^^^^^^^^^^^
How does one know what is the correct register size?

> +    error (_("Failed to write %d bytes to core file ('%s').\n"),
> +	   len, bfd_errmsg (bfd_get_error ()));

How about stating the name of the file?

> +  if (strcmp (current_target.to_shortname, "record") != 0)
> +    error (_("Process record is not started.\n"));

Suggest to add to the message text something that tells the user how
to remedy this situation.  E.g., "Invoke FOO command first."

> +      snprintf (recfilename_buffer, sizeof (recfilename_buffer),
> +                "gdb_record.%d", PIDGET (inferior_ptid));

What will this do in go32, where the "PID" is always 42?  Does a
target or an architecture have a way of overriding this default?

> +  if (record_debug)
> +    printf_filtered (_("Saving recording to file '%s'\n"),
> +		     recfilename);

Suggest to say "Saving execution log to core file '%s'\n".  I added
"core" because you use that freely elsewhere, and the user should
therefore know that the recorded data goes to a file formatted as a
core file.

> +  /* Need a cleanup that will close the file (FIXME: delete it?).  */

Can this be fixed before you commit?

> +  if (osec == NULL)
> +    error (_("Failed to create 'precord' section for corefile: %s"),
> +           bfd_errmsg (bfd_get_error ()));

Again, adding the name of the file will go a long way towards making
the intent clear to a user who has no clue in how precord works.

> +  printf_filtered (_("Saved recfile %s.\n"), recfilename);

"recfile"?  What's that? ;-)

> +Argument is filename.  File must be created with 'record dump'."),
                                                     ^^^^^^^^^^^
You mean, "record save", right?

Thanks.