Add File already exists error doc to hard_link function

[Harshit933]

Description

If the link path already exists, the error AlreadyExists is returned. This commit adds this error to the docs.

I tested it with the current rust master version, this error was returned when there is already a link for the file is present.
This was the error returned:

[harshit:../Desktop/rust_compiler_testing/hard_link (master|…5)] cargo +stage1 run
   Compiling hard_link v0.1.0 (/home/harshit/Desktop/rust_compiler_testing/hard_link)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.12s
     Running `target/debug/hard_link`
Err(Os { code: 17, kind: AlreadyExists, message: "File exists" })

This is my first PR on rust, any suggestions on which issue I can take next are most welcome 😄

Fixes #130117

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @ChrisDenton (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[ChrisDenton]

I do agree with this PR because I think this is always the intended behaviour and not documenting it was just an oversight. However, I would caution about documenting based on testing alone as that can miss edge cases or other platforms. cc @the8472 in case I'm missing something.

I think this would need a sign-off by someone on libs-api as it's technically a new API guarantee. But I think this should be an easy decision. cc @rust-lang/libs-api

[the8472]

Yeah posix requires that it fails if the destination exists. So that only leaves WASI, which to my understanding does try to match what's portable and secure so it probably should have this property too but I couldn't find documentation on that. CC @sunfishcode

[Harshit933]

However, I would caution about documenting based on testing alone as that can miss edge cases or other platforms

Hello ,I agree that behavior can vary across platforms and may sometimes differ from what is expected. Out of curiosity is there any way to know (other than testing on different OS) the anomaly of this function. I looked up the code it internally calls the system functions namely link and linkat based on the OS.

[ChrisDenton]

The documentation for hard_link says which functions it currently uses on each platform. You can look up each platform documentation for the corresponding function.

The reason I pinged our libs-api team is because documenting a guarantee is a bit of a stronger decision than just "this is what happens now". It's a guarantee that this is the behaviour we expect from all platforms, now and in the future. I personally think this is a good guarantee to have but it'll need libs-api to agree.

[Harshit933]

Got it. Thank you so much for the explanation.

[Amanieu]

@rfcbot merge

[rfcbot]

Team member @Amanieu has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[tbu-]

Has anyone tested this on Windows? I can't find anything concerning the second path already existing in the docs of CreateHardLinkW.

[sunfishcode]

Yeah posix requires that it fails if the destination exists. So that only leaves WASI, which to my understanding does try to match what's portable and secure so it probably should have this property too but I couldn't find documentation on that. CC @sunfishcode

Indeed, I've now opened WebAssembly/wasi-filesystem#165 to add documentation for that.

[ChrisDenton]

Has anyone tested this on Windows?

Yes. It'll return ERROR_ALREADY_EXISTS if the file already exists. Internally it uses NtSetInformationFile with FILE_LINK_INFORMATION and sets ReplaceIfExists to false.

I can't find anything concerning the second path already existing in the docs of CreateHardLinkW.

I mean, it's not as explicit as I'd like but it is meant to be implied by calling it a "new file" and not mentioning replacing the old file.

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[ChrisDenton]

Thanks!

@bors r+

[bors]

📌 Commit ab27463 has been approved by ChrisDenton

It is now in the queue for this repository.