[Libguestfs] Proposed new file apis

Matthew Booth mbooth at redhat.com
Mon Aug 23 15:58:38 UTC 2010


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.

>> >  +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.

>> >  +  ("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.

>> >  +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.

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?

>
>> >  +  ("hallocate", (RErr, [Int "handle"; Int64 "offset"; Int64 "length"]), 277, [],
>> >  +   [],
>> >  +   "reserve space for a file",
>> >  +   "\
>> >  +This command ensures that C<length>  bytes of disk space have been
>> >  +allocated, starting at an offset of C<offset>  bytes from the
>> >  +beginning of the file, for the file referred to by C<handle>.
>> >  +This will increase the size of the file if necessary. Any newly
>> >  +allocated space will be zero-filled.");
>> >  +
>> >    ]
>> >
>> >    let all_functions = non_daemon_functions @ daemon_functions

Thanks,

Matt
-- 
Matthew Booth, RHCA, RHCSS
Red Hat Engineering, Virtualisation Team

GPG ID:  D33C3490
GPG FPR: 3733 612D 2D05 5458 8A8A 1600 3441 EA19 D33C 3490




More information about the Libguestfs mailing list