Re: File* argument order, argument types

On Sat, Feb 18, 2023 at 6:23 AM Andres Freund <andres(at)anarazel(dot)de> wrote:
>
> Hi,
>
> While trying to add additional File* functions (FileZero, FileFallocat) I went
> back and forth about the argument order between "amount" and "offset".
>
> We have:
>
> extern int FilePrefetch(File file, off_t offset, off_t amount, uint32 wait_event_info);
> extern int FileRead(File file, void *buffer, size_t amount, off_t offset, uint32 wait_event_info);
> extern int FileWrite(File file, const void *buffer, size_t amount, off_t offset, uint32 wait_event_info);
> extern int FileTruncate(File file, off_t offset, uint32 wait_event_info);
> extern void FileWriteback(File file, off_t offset, off_t nbytes, uint32 wait_event_info);
>
> and I want to add (for [1])
> extern int FileZero(File file, off_t amount, off_t offset, uint32 wait_event_info);
> extern int FileFallocate(File file, off_t amount, off_t offset, uint32 wait_event_info);
>
> The differences originate in trying to mirror the underlying function's
> signatures:
>
> int posix_fadvise(int fd, off_t offset, off_t len, int advice);
> ssize_t pread(int fd, void buf[.count], size_t count, off_t offset);
> ssize_t pwrite(int fd, const void buf[.count], size_t count, off_t offset);
> int ftruncate(int fd, off_t length);
> int posix_fallocate(int fd, off_t offset, off_t len);
> int sync_file_range(int fd, off64_t offset, off64_t nbytes, unsigned int flags);
>
>
> It seems quite confusing to be this inconsistent about argument order and
> argument types in the File* functions. For one, the relation to the underlying
> posix functions isn't always obvious. For another, we're not actually
> mirroring the signatures all that well, our argument and return types don't
> actually match.
>
>
> It'd be easy enough to decide on a set of types for the arguments, that'd be
> API (but not necessarily ABI compatible, but we don't care) compatible. But
> changing the argument order would commonly lead to silent breakage, which
> obviously would be bad. Or maybe it's unlikely enough that there are external
> callers?

I am sure there are extensions and forks which use these APIs and they
will be surprised to see this change OR will face silent breakage.
Do you consider those as external callers?

--
Best Wishes,
Ashutosh Bapat