[Libguestfs] Proposed new file apis

[Richard W.M. Jones]

On Mon, Aug 23, 2010 at 04:58:38PM +0100, Matthew Booth wrote:
> On 23/08/10 16:23, Richard W.M. Jones wrote:
> >BTW you need two spaces after full stops.
> 
> Out of curiosity is that a technical or a stylistic requirement?
> Stylistically, double spaces after a full stop have always seemed
> anachronistic to me.

It's a stylistic one.

> >>>  +hpread returns a NULL C<content>  on error.");
> >>>  +
> >>>  +  ("hwrite", (RErr, [Int "handle"; BufferIn "content"]), 273,
> >>>  +   [ProtocolLimitWarning], [],
> >>>  +   "write data to an open handle",
> >>>  +   "\
> >>>  +This command writes all the data in C<content>  to C<handle>. It
> >>>  +returns an error if this fails.");
> >So we're definitely disallowing partial writes, even though in some
> >future version we might allow writes to non-file handles?  This API
> >won't allow partial writes.
> 
> Yes. I think reads and writes are quite different in this respect.
> You always know exactly what you want to write, but you may not know
> what can be read. If this assumption is wrong, now's the time to
> disagree.

I think we should change pwrite in that case.  pwrite only works on
files, and AFAICT there is never a situation where a partial write is
possible for a file, so we should turn pwrite into a full write and
change the documentation accordingly.

> >>>  +  ("hpwrite", (RErr, [Int "handle"; BufferIn "content"]), 274,
> >>>  +   [ProtocolLimitWarning], [],
> >>>  +   "write data to an open handle at a specific offset",
> >>>  +   "\
> >>>  +This command writes all the data in C<content>  to C<handle>,
> >>>  +starting at C<offset>  bytes from the beginning of the file. It
> >>>  +returns an error if this fails.");
> >The offset is missing from the API.
> 
> Oops :)
> 
> >>>  +  ("hseek", (RInt64 "newoffset", [Int "handle"; Int64 "offset";
> >>>  +                                  Int "whence"]), 275, [],
> >>>  +   [],
> >>>  +   "seek on an open handle",
> >>>  +   "\
> >>>  +This command updates the 'current position' in C<handle>. This
> >"current position" doesn't need those extra quotes.
> >
> >>>  +affects the hread and hwrite calls. See L<lseek(3p)>  for details
> >If you're referring to another call, write:
> >
> >... C<guestfs_hread>  and C<guestfs_hwrite>  ...
> >
> >The generator will rewrite this correctly.
> >
> >>>  +of C<offset>  and C<whence>.
> >C<whence>  is presumably 0/1/2?  You should document this, or use a
> >String if you want an enumerated type.
> 
> Are you saying that a String can be magically turned into an
> enumerated type somehow? I was trying to work out how to use an
> enumerated type.

Sadly not.  However we have a long history of using strings instead of
enumerated types throughout the API.  In any case, either 0/1/2 needs
to be documented, or this should be a string.  It should not be an
undocumented int.

> >>>  +On success, hseek returns the new offset from the beginning of
> >>>  +the file. It returns an offset of -1 on failure.");
> >>>  +
> >>>  +  ("htruncate", (RErr, [Int "handle"; Int64 "size"]), 276, [],
> >>>  +   [],
> >>>  +   "truncate a file",
> >>>  +   "\
> >>>  +This command sets the size of the file referred to by C<handle>
> >>>  +to C<size>. If the file was previously larger than C<size>, the
> >>>  +extra data will be lost. If the file was previously smaller than
> >>>  +C<size>, the file will be zero-filled. The latter case will
> >>>  +typically create a sparse file.");
> >Since we already have truncate and allocate calls, I wonder what the
> >benefit is of having handle versions.  I mean, these are extremely
> >infrequent operations compared to hread/hwrite, so I doubt there's any
> >optimization benefit in adding these, and if we add these, why not
> >other very infrequent ops.
> 
> htruncate is required when streaming a file with sparse sections. i.e.
> 
> h = hopen_file("/foo");
> hwrite(h, "foo");
> htruncate(h, hseek(h, 1024, CUR));
> 
> Technically you only need this for a sparse section at the end of a
> file. You could do it by mixing paths and file handles, but that
> would be a bit jarring.

I don't think I understand this.  If you're writing to a file, you can
truncate it once (before any writing) to set its size:

  truncate-size "/output" 100M;
  hopen-file "/output";
  hwrite ...;
  hwrite ...;
  hwrite ...;
  hclose fd;

Why is htruncate needed during writes?

> hallocate is similarly there to avoid a jarring mix of paths and
> file handles when operating on a single file.  I could also add
> fchmod and fchown, I guess. Any more?

My point was we don't need to duplicate all of these.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
libguestfs lets you edit virtual machines.  Supports shell scripting,
bindings from many languages.  http://et.redhat.com/~rjones/libguestfs/
See what it can do: http://et.redhat.com/~rjones/libguestfs/recipes.html