Document why there is no path_filestat_set_size

[marmistrz]

As suggested by @sunfishcode in bytecodealliance/wasmtime#273

[sbc100]

The fact that POSIX lacks a truncateat function seems like it was probably more of an oversight than a deliberate decision. Begin able to set a files size directly without opening seems useful to me.

Also, IIUC we are explicitly not following POSIX's design so the comment seems a little strange.

[sbc100]

I found this confusing to read because there clearly is a thing path_filestat_set_size called on the line below. I guess you are referring to the fact that there is no addition separate function with this name?

[marmistrz]

Yes, the intended meaning is that there is no function named __wasi_path_filestat_set_size.

[sunfishcode]

Could you change the text to add the word "function" here, so that it's clear you're talking about a function by that name (which indeed doesn't exist) rather than a right (which does)?

[marmistrz]

Done!

[marmistrz]

@sbc100
Lack of ftruncateat means that, as far as I know, there is no way to efficiently implement path_filestat_set_size on any major platform.

On Unix the only possible implementation seems to be path_open + fd_filestat_set_size corresponding to open + ftruncate.
On Windows there is SetEndOfFile which similarly expects a file handle, so again we end up doing path_open + fd_filestat_set_size.

Exposing path_filestat_set_size could give an illusion that this call is cheaper than path_open + fd_filestat_set_size.

[sbc100]

I see. This makes more sense to me now.

Perhaps you could rephrase. This comment makes it sound like we don't have this function because we are following POSIX, which is not that case. How about something like this:

Note: there is no function named `path_filestat_set_size` because on many existing
systems there is no way to efficiently implement this.  For example, POSIX has no
`ftruncateat` function.

[marmistrz]

Sorry for the delay. I rephrased it in a slightly different way, is it okay for you now?

[sunfishcode]

Would it be difficult to implement efficiently? It seems we could implement this by just opening the file and doing ftruncate, which would be reasonable. My understanding is that the main reason we don't have path_filestat_set_size is that we don't currently have any use cases for it, since no code written for POSIX systems would use it.

[marmistrz]

Here to implement efficiently is intended to mean to implement using one syscall only, as we consider the cost of other calls negligible.

How about

While such function would be desirable from the API design perspective, there are virtually no use cases for it since no code written for POSIX systems would use it. Moreover, implementing it would require multiple syscalls, leading to inferior performance.

[marmistrz]

@sunfishcode bump

[sunfishcode]

Thanks for the bump! That wording sounds good to me.

[marmistrz]

I pushed the new wording.

[sunfishcode]

Looks good!