Update canonicalize docs
I was recently working with file-paths in Rust, and I felt let down by the `std::fs::canonicalize` docs, so I figured I should submit a PR with some suggestions.
I was looking for a method to turn a relative path into an absolute path. The `canonicalize` docs didn't mention the words "relative" or "absolute", but they did mention resolving symlinks (which is a kind of canonicalisation and does not imply converting to absolute), so I assumed that's all it did. To remedy this, I've added the word "absolute" to the description of both `std::fs::canonicalize` and `std::path::Path::canonicalize`.
After calling `canonicalize` on Windows, I ran into a bunch of other problems I would not have expected from the function's behaviour on Linux. Specifically, if you call `canonicalize` on a path:
- it's allowed to be much longer than it otherwise would
- `.join("a/slash/delimited/path")` gives you a broken path that Windows can't use, where the same operation would have worked perfectly without `canonicalize` (if the path were short enough)
- the resulting path may confuse other Windows programs if you pass it to them on the command-line, or write it to a config file that they read, etc.
...so I tried to summarize those behaviours too.
If I understand correctly, those behaviours are a side-effect of calling `GetFinalPathNameByHandle`, and the documentation says `canonicalize` might not call that function in future, so maybe those side-effects shouldn't be part of the function's documentation. However, I bet there's a lot of applications deliberately calling `canonicalize` just for the path-length-extension alone, so that particular side-effect is de-facto part of the `canonicalize` interface.
Rollup of 18 pull requests
Successful merges:
- #49423 (Extend tests for RFC1598 (GAT))
- #50010 (Give SliceIndex impls a test suite of girth befitting the implementation (and fix a UTF8 boundary check))
- #50447 (Fix update-references for tests within subdirectories.)
- #50514 (Pull in a wasm fix from LLVM upstream)
- #50524 (Make DepGraph::previous_work_products immutable)
- #50532 (Don't use Lock for heavily accessed CrateMetadata::cnum_map.)
- #50538 ( Make CrateNum allocation more thread-safe. )
- #50564 (Inline `Span` methods.)
- #50565 (Use SmallVec for DepNodeIndex within dep_graph.)
- #50569 (Allow for specifying a linker plugin for cross-language LTO)
- #50572 (Clarify in the docs that `mul_add` is not always faster.)
- #50574 (add fn `into_inner(self) -> (Idx, Idx)` to RangeInclusive (#49022))
- #50575 (std: Avoid `ptr::copy` if unnecessary in `vec::Drain`)
- #50588 (Move "See also" disambiguation links for primitive types to top)
- #50590 (Fix tuple struct field spans)
- #50591 (Restore RawVec::reserve* documentation)
- #50598 (Remove unnecessary mutable borrow and resizing in DepGraph::serialize)
- #50606 (Retry when downloading the Docker cache.)
Failed merges:
- #50161 (added missing implementation hint)
- #50558 (Remove all reference to DepGraph::work_products)
Map the stack guard page with max protection on NetBSD
On NetBSD the initial mmap() protection of a mapping can not be made
less restrictive with mprotect().
So when mapping a stack guard page, use the maximum protection
we ever want to use, then mprotect() it to the permission we
want it to have initially.
Fixes#50313
Add some explanations for #[must_use]
`#[must_use]` can be given a string argument which is shown whilst warning for things.
We should add a string argument to most of the user-exposed ones.
I added these for everything but the operators, mostly because I'm not sure what to write there or if we need anything there.
These are unstable, and were deprecated by #47510, since Rust 1.25. The
internal `sys` implementations are still kept to support the call in the
common `resolve_socket_addr`.
Forbid constructing empty identifiers from concat_idents
The empty identifier is a [reserved identifier](8a37c75a3a/src/libsyntax_pos/symbol.rs (L300-L305)) in rust, apparently used for black magicks like representing the crate root or somesuch... and therefore, being able to construct it is Ungood. Presumably.
...even if the macro that lets you construct it is so useless that you can't actually do any damage with it. (and believe me, I tried)
Fixes#50403.
**Note:** I noticed that when you try to do something similar with `proc_macro::Term`, the compiler actually catches it and flags the identifier as reserved. Perhaps a better solution would be to somehow have that same check applied here.
While currently only NetBSD seems to be affected, all systems
implementing PAX MPROTECT in strict mode need this treatment,
and it does not hurt others.
Rollup of 7 pull requests
Successful merges:
- #50233 (Make `Vec::new` a `const fn`)
- #50312 (Add more links in panic docs)
- #50316 (Fix some broken links in docs.)
- #50325 (Add a few more tests for proc macro feature gating)
- #50327 (Display correct unused field suggestion for nested struct patterns)
- #50330 (check that #[used] is used only on statics)
- #50344 (Update Cargo to 2018-04-28 122fd5be5201913d42e219e132d6569493583bca)
Failed merges:
Add more links in panic docs
Fixes#48695 by adding a link to `AssertUnwindSafe`. Also added some other links in the module's docs to make things clearer.
Bury Error::description()
Second attempt of #49536https://github.com/rust-lang/rfcs/pull/2230
The exact wording of the default implementation is still up in the air, but I think it's a detail that can be amended later.
On NetBSD the initial mmap() protection of a mapping can not be made
less restrictive with mprotect().
So when mapping a stack guard page, use the maximum protection
we ever want to use, then mprotect() it to the permission we
want it to have initially.
… rather than the module’s.
Remove code definition of the Error trait from its doc-comment
It was out of date, and rustdoc already shows the same information.
Add a default impl for Error::description and document it as deprecated.
It is redundant with Display while being much less flexible for implementors.
This is only a "soft" deprecation: it is not worth the hassle of a warning to existing users.
Tweak Error trait docs to reflect actual requirements
Android abstract unix domain sockets AddressKind correction
The prior check causes abstract unix domain sockets to return AddressKind::Unnamed instead of AddressKind::Abstract on Android.
Other than the immediately proceeding comment "macOS seems to return a len of 16 and a zeroed sun_path for unnamed addresses" the check as-implemented does not seem to have alternative explanation. I couldn't find an alternative explanation while stepping though git blame. I suspect the AddressKind::Unnamed nonzero check should instead be if macos, length 16, and zeroed array. @sfackler could you comment on this, the code as-is is the same from your initial addition of abstract uds support.
Add doc links to `std::os` extension traits
Addresses a small subset of #29367.
This adds documentation links to the original type for various OS-specific extension traits, and uses a common sentence for introducing such traits (which now consistently ends in a period).
std: Child::kill() returns error if process has already exited
This patch makes it clear in std::process::Child::kill()'s API
documentation that an error is returned if the child process has
already cleanly exited. This is implied by the example, but not
called out explicitly.
Make signature of Path::strip_prefix accept non-references
I did this a while back but didn't submit a PR. Might as well see what happens.
Fixes#48390.
**Note: This has the potential to cause regressions in type inference.** However, in order for code to break, it would need to be relying on the signature to determine that a type is `&_`, while still being able to figure out what the `_` is. I'm having a hard time imagining such a scenario in real code.
