Incorrect documentation of Root::create_file

[Riatre]

Documentation says:

    /// # Errors
    ///
    /// Identical to [`create`].

libpathrs/src/root.rs

Line 394 in 80ca8d3

/// Identical to [`create`].

And then create:

    /// # Errors
    ///
    /// If the path already exists (regardless of the type of the existing
    /// inode), an error is returned.

However create_file does not return error, unless the caller explicitly add O_EXCL to the flags.

[cyphar]

Well, there are other errors you can get from create and create_file that are broadly shared (mostly related to lookup failures) but you're right that it's not strictly "identical".

Is there any particular wording you'd suggest? Or would you prefer that I mention the other kinds of errors you can get (it felt a little gratuitous to list all the kinds of VFS errors you could theoretically get so I only listed the notable ones)?

[Riatre]

I would say that saying something along the line of "it's identical to create except that if the path already exists and is a regular file we open the file instead of error out", is fine.

For context, I was trying to implement something that creates OR truncates a file and return whether it was newly created. I read the doc and decided to use a loop of create_file and open_subpath. To my surprise create_file always succeed.

[cyphar]

Sure, I'll write something up.

For context, I was trying to implement something that creates OR truncates a file and return whether it was newly created. I read the doc and decided to use a loop of create_file and open_subpath. To my surprise create_file always succeed.

Indeed, you just need to pass O_TRUNC to Root::create_file, as openat(O_CREAT|O_TRUNC) has the behaviour you want.

[cyphar]

D'oh, I meant to include this in 0.2.3. Let me add it to a milestone so I don't forget...