IOS: modes for opening files

[Jose E. Marchesi]

Hi people!

In Poke we have the following definitions:

  var IOS_F_READ   = 1;
  var IOS_F_WRITE  = 2;
  var IOS_F_TRUNCATE = 8;
  var IOS_F_CREATE = 16;

  var IOS_M_RDONLY = IOS_F_READ;
  var IOS_M_WRONLY = IOS_F_WRITE;
  var IOS_M_RDWR = IOS_F_READ | IOS_F_WRITE;

The `open' function has the following prototype:

  fun open = (string handler, uint<64> flags = 0) int<32>

And the file IOD currently translates the Poke flags to mode strings for
fopen in the following way (in ios-dev-file.c:ios_dev_file_open):

  /* Decide what mode to use to open the file.  */
  if (flags_mode == IOS_F_READ)
    mode = "rb";
  else if (flags_mode == (IOS_F_WRITE | IOS_F_CREATE | IOS_F_TRUNCATE))
    mode = "wb";
  else if (flags_mode == (IOS_F_READ | IOS_F_WRITE))
    mode = "r+b";
  else if (flags_mode == (IOS_F_WRITE | IOS_F_CREATE | IOS_F_TRUNCATE))
    mode = "w+b";
  else
    {
      internal_error = IOD_EFLAGS;
      goto err;
    }

   f = fopen (handler, mode);

There is a clear bug in the code ("w+b" will never be used) and is
incomplete.

The `fopen' call supports three general modes for opening files: read,
write and append.  From fopen(3):

   r      Open text file for reading.  The stream  is  positioned  at  the
          beginning of the file.

   r+     Open  for  reading and writing.  The stream is positioned at the
          beginning of the file.

   w      Truncate file to zero length or create text  file  for  writing.
          The stream is positioned at the beginning of the file.

   w+     Open  for  reading  and writing.  The file is created if it does
          not exist, otherwise it is truncated.  The stream is  positioned
          at the beginning of the file.

   a      Open  for  appending (writing at end of file).  The file is cre‐
          ated if it does not exist.  The stream is positioned at the  end
          of the file.

   a+     Open  for  reading  and appending (writing at end of file).  The
          file is created if it does not exist.  The initial file position
          for  reading  is  at  the  beginning  of the file, but output is
          always appended to the end of the file.

We could follow the same model in the Poke `open', and provide:

  IOS_F_READ
  IOS_F_WRITE
  IOS_F_CREATE
  IOS_F_TRUNCATE
  IOS_F_APPEND  (implies IOS_F_CREATE)

Which would translate to fopen modes as (the list below uses ifelse
logic):

  IOS_F_READ | IOS_F_WRITE | IOS_F_CREATE                -> "w+"
  IOS_F_READ | IOS_F_WRITE | IOS_F_APPEND                -> "a+"
  IOS_F_READ | IOS_F_WRITE                               -> "r+"
  IOS_F_WRITE | IOS_F_APPEND                             -> "a"
  IOS_F_READ                                             -> "r"
  IOS_F_WRITE                                            -> "w"

and accompanying convenience mode values:

var IOS_M_RDONLY  = IOS_F_READ;
var IOS_M_WRONLY  = IOS_F_WRITE;
var IOS_M_WRONLYA = IOS_F_WRITE | IOS_F_APPEND;
var IOS_M_RDWR    = IOS_F_READ | IOS_F_WRITE;
var IOS_M_RDWRA   = IOS_F_READ | IOS_F_WRITE | IOS_F_APPEND;
var IOS_M_RDWRC   = IOS_F_READ | IOS_F_WRITE | IOS_F_CREATE;

Any other combination would raise a "bad flags" error.

You may be wondering, why don't we just support these six modes in the
argument to open?  The reason is that these six combinations make sense
for file IO devices, but for other kind of IO devices other combinations
of the flags may be useful, or not the six of them.

Opinions?