diff options
Diffstat (limited to 'src/doc/unstable-book')
11 files changed, 130 insertions, 95 deletions
diff --git a/src/doc/unstable-book/src/compiler-flags/check-cfg.md b/src/doc/unstable-book/src/compiler-flags/check-cfg.md index bfa92e7d3..321992f7b 100644 --- a/src/doc/unstable-book/src/compiler-flags/check-cfg.md +++ b/src/doc/unstable-book/src/compiler-flags/check-cfg.md @@ -143,7 +143,7 @@ fn do_features() {} #[cfg(has_feathers = "zapping")] // This is expected as "has_feathers" was provided in names() // and because no value checking was enable for "has_feathers" - // no warning is emited for the value "zapping" + // no warning is emitted for the value "zapping" fn do_zapping() {} #[cfg(has_mumble_frotz)] // This is UNEXPECTED because names checking is enable and diff --git a/src/doc/unstable-book/src/compiler-flags/dylib-lto.md b/src/doc/unstable-book/src/compiler-flags/dylib-lto.md new file mode 100644 index 000000000..f69ea334f --- /dev/null +++ b/src/doc/unstable-book/src/compiler-flags/dylib-lto.md @@ -0,0 +1,4 @@ +## `dylib-lto` + +This option enables using LTO for the `dylib` crate type. This is currently only used for compiling +`rustc` itself (more specifically, the `librustc_driver` dylib). diff --git a/src/doc/unstable-book/src/compiler-flags/remap-cwd-prefix.md b/src/doc/unstable-book/src/compiler-flags/remap-cwd-prefix.md index 977d25852..3890a12b7 100644 --- a/src/doc/unstable-book/src/compiler-flags/remap-cwd-prefix.md +++ b/src/doc/unstable-book/src/compiler-flags/remap-cwd-prefix.md @@ -8,7 +8,7 @@ This flag will rewrite absolute paths under the current working directory, replacing the current working directory prefix with a specified value. The given value may be absolute or relative, or empty. This switch takes -precidence over `--remap-path-prefix` in case they would both match a given +precedence over `--remap-path-prefix` in case they would both match a given path. This flag helps to produce deterministic output, by removing the current working diff --git a/src/doc/unstable-book/src/compiler-flags/sanitizer.md b/src/doc/unstable-book/src/compiler-flags/sanitizer.md index 7f7549aaf..b33405f18 100644 --- a/src/doc/unstable-book/src/compiler-flags/sanitizer.md +++ b/src/doc/unstable-book/src/compiler-flags/sanitizer.md @@ -9,17 +9,17 @@ The tracking issues for this feature are: This feature allows for use of one of following sanitizers: -* [AddressSanitizer][clang-asan] a fast memory error detector. -* [ControlFlowIntegrity][clang-cfi] LLVM Control Flow Integrity (CFI) provides +* [AddressSanitizer](#addresssanitizer) a fast memory error detector. +* [ControlFlowIntegrity](#controlflowintegrity) LLVM Control Flow Integrity (CFI) provides forward-edge control flow protection. -* [HWAddressSanitizer][clang-hwasan] a memory error detector similar to +* [HWAddressSanitizer](#hwaddresssanitizer) a memory error detector similar to AddressSanitizer, but based on partial hardware assistance. -* [LeakSanitizer][clang-lsan] a run-time memory leak detector. -* [MemorySanitizer][clang-msan] a detector of uninitialized reads. -* [MemTagSanitizer][clang-memtag] fast memory error detector based on +* [LeakSanitizer](#leaksanitizer) a run-time memory leak detector. +* [MemorySanitizer](#memorysanitizer) a detector of uninitialized reads. +* [MemTagSanitizer](#memtagsanitizer) fast memory error detector based on Armv8.5-A Memory Tagging Extension. -* [ShadowCallStack][clang-scs] provides backward-edge control flow protection. -* [ThreadSanitizer][clang-tsan] a fast data race detector. +* [ShadowCallStack](#shadowcallstack) provides backward-edge control flow protection. +* [ThreadSanitizer](#threadsanitizer) a fast data race detector. To enable a sanitizer compile with `-Zsanitizer=address`,`-Zsanitizer=cfi`, `-Zsanitizer=hwaddress`, `-Zsanitizer=leak`, `-Zsanitizer=memory`, @@ -58,6 +58,8 @@ AddressSanitizer works with non-instrumented code although it will impede its ability to detect some bugs. It is not expected to produce false positive reports. +See the [Clang AddressSanitizer documentation][clang-asan] for more details. + ## Examples Stack buffer overflow: @@ -204,6 +206,8 @@ tracking issue [#89653](https://github.com/rust-lang/rust/issues/89653)). LLVM CFI can be enabled with -Zsanitizer=cfi and requires LTO (i.e., -Clto). +See the [Clang ControlFlowIntegrity documentation][clang-cfi] for more details. + ## Example ```text @@ -430,6 +434,8 @@ HWAddressSanitizer requires `tagged-globals` target feature to instrument globals. To enable this target feature compile with `-C target-feature=+tagged-globals` +See the [Clang HWAddressSanitizer documentation][clang-hwasan] for more details. + ## Example Heap buffer overflow: @@ -507,6 +513,8 @@ LeakSanitizer is supported on the following targets: * `x86_64-apple-darwin` * `x86_64-unknown-linux-gnu` +See the [Clang LeakSanitizer documentation][clang-lsan] for more details. + # MemorySanitizer MemorySanitizer is detector of uninitialized reads. @@ -521,6 +529,8 @@ MemorySanitizer requires all program code to be instrumented. C/C++ dependencies need to be recompiled using Clang with `-fsanitize=memory` option. Failing to achieve that will result in false positive reports. +See the [Clang MemorySanitizer documentation][clang-msan] for more details. + ## Example Detecting the use of uninitialized memory. The `-Zbuild-std` flag rebuilds and @@ -569,7 +579,7 @@ MemTagSanitizer is supported on the following targets: MemTagSanitizer requires hardware support and the `mte` target feature. To enable this target feature compile with `-C target-feature="+mte"`. -More information can be found in the associated [LLVM documentation](https://llvm.org/docs/MemTagSanitizer.html). +See the [LLVM MemTagSanitizer documentation][llvm-memtag] for more details. # ShadowCallStack @@ -581,7 +591,9 @@ ShadowCallStack can be enabled with `-Zsanitizer=shadow-call-stack` option and i * `aarch64-linux-android` -A runtime must be provided by the application or operating system. See the [LLVM documentation][clang-scs] for further details. +A runtime must be provided by the application or operating system. + +See the [Clang ShadowCallStack documentation][clang-scs] for more details. # ThreadSanitizer @@ -604,6 +616,8 @@ can lead to false positive reports. ThreadSanitizer does not support atomic fences `std::sync::atomic::fence`, nor synchronization performed using inline assembly code. +See the [Clang ThreadSanitizer documentation][clang-tsan] for more details. + ## Example ```rust @@ -673,6 +687,7 @@ Sanitizers produce symbolized stacktraces when llvm-symbolizer binary is in `PAT * [HWAddressSanitizer in Clang][clang-hwasan] * [LeakSanitizer in Clang][clang-lsan] * [MemorySanitizer in Clang][clang-msan] +* [MemTagSanitizer in LLVM][llvm-memtag] * [ThreadSanitizer in Clang][clang-tsan] [clang-asan]: https://clang.llvm.org/docs/AddressSanitizer.html @@ -682,3 +697,4 @@ Sanitizers produce symbolized stacktraces when llvm-symbolizer binary is in `PAT [clang-msan]: https://clang.llvm.org/docs/MemorySanitizer.html [clang-scs]: https://clang.llvm.org/docs/ShadowCallStack.html [clang-tsan]: https://clang.llvm.org/docs/ThreadSanitizer.html +[llvm-memtag]: https://llvm.org/docs/MemTagSanitizer.html diff --git a/src/doc/unstable-book/src/compiler-flags/self-profile-events.md b/src/doc/unstable-book/src/compiler-flags/self-profile-events.md index 3ce18743b..3e644f786 100644 --- a/src/doc/unstable-book/src/compiler-flags/self-profile-events.md +++ b/src/doc/unstable-book/src/compiler-flags/self-profile-events.md @@ -41,7 +41,7 @@ $ rustc -Zself-profile -Zself-profile-events=default,args - `llvm` - Adds tracing information about LLVM passes and codegeneration. - - Disabled by default because this only works when `-Znew-llvm-pass-manager` is enabled. + - Disabled by default because this significantly increases the trace file size. ## Event synonyms diff --git a/src/doc/unstable-book/src/language-features/arbitrary-enum-discriminant.md b/src/doc/unstable-book/src/language-features/arbitrary-enum-discriminant.md deleted file mode 100644 index e0bb78227..000000000 --- a/src/doc/unstable-book/src/language-features/arbitrary-enum-discriminant.md +++ /dev/null @@ -1,37 +0,0 @@ -# `arbitrary_enum_discriminant` - -The tracking issue for this feature is: [#60553] - -[#60553]: https://github.com/rust-lang/rust/issues/60553 - ------------------------- - -The `arbitrary_enum_discriminant` feature permits tuple-like and -struct-like enum variants with `#[repr(<int-type>)]` to have explicit discriminants. - -## Examples - -```rust -#![feature(arbitrary_enum_discriminant)] - -#[allow(dead_code)] -#[repr(u8)] -enum Enum { - Unit = 3, - Tuple(u16) = 2, - Struct { - a: u8, - b: u16, - } = 1, -} - -impl Enum { - fn tag(&self) -> u8 { - unsafe { *(self as *const Self as *const u8) } - } -} - -assert_eq!(3, Enum::Unit.tag()); -assert_eq!(2, Enum::Tuple(5).tag()); -assert_eq!(1, Enum::Struct{a: 7, b: 11}.tag()); -``` diff --git a/src/doc/unstable-book/src/language-features/asm-sym.md b/src/doc/unstable-book/src/language-features/asm-sym.md deleted file mode 100644 index 103d91caf..000000000 --- a/src/doc/unstable-book/src/language-features/asm-sym.md +++ /dev/null @@ -1,13 +0,0 @@ -# `asm_sym` - -The tracking issue for this feature is: [#93333] - -[#93333]: https://github.com/rust-lang/rust/issues/93333 - ------------------------- - -This feature adds a `sym <path>` operand type to `asm!` and `global_asm!`. -- `<path>` must refer to a `fn` or `static`. -- A mangled symbol name referring to the item is substituted into the asm template string. -- The substituted string does not include any modifiers (e.g. GOT, PLT, relocations, etc). -- `<path>` is allowed to point to a `#[thread_local]` static, in which case the asm code can combine the symbol with relocations (e.g. `@plt`, `@TPOFF`) to read from thread-local data. diff --git a/src/doc/unstable-book/src/language-features/half-open-range-patterns-in-slices.md b/src/doc/unstable-book/src/language-features/half-open-range-patterns-in-slices.md new file mode 100644 index 000000000..56a1a97df --- /dev/null +++ b/src/doc/unstable-book/src/language-features/half-open-range-patterns-in-slices.md @@ -0,0 +1,30 @@ +# `half_open_range_patterns_in_slices` + +The tracking issue for this feature is: [#67264] +It is part of the `exclusive_range_pattern` feature, +tracked at [#37854]. + +[#67264]: https://github.com/rust-lang/rust/issues/67264 +[#37854]: https://github.com/rust-lang/rust/issues/37854 +----- + +This feature allow using top-level half-open range patterns in slices. + +```rust +#![feature(half_open_range_patterns_in_slices)] +#![feature(exclusive_range_pattern)] + +fn main() { + let xs = [13, 1, 5, 2, 3, 1, 21, 8]; + let [a @ 3.., b @ ..3, c @ 4..6, ..] = xs else { return; }; +} +``` + +Note that this feature is not required if the patterns are wrapped between parenthesis. + +```rust +fn main() { + let xs = [13, 1]; + let [(a @ 3..), c] = xs else { return; }; +} +``` diff --git a/src/doc/unstable-book/src/language-features/half-open-range-patterns.md b/src/doc/unstable-book/src/language-features/half-open-range-patterns.md deleted file mode 100644 index 3b16dd049..000000000 --- a/src/doc/unstable-book/src/language-features/half-open-range-patterns.md +++ /dev/null @@ -1,27 +0,0 @@ -# `half_open_range_patterns` - -The tracking issue for this feature is: [#67264] -It is part of the `#![exclusive_range_pattern]` feature, -tracked at [#37854]. - -[#67264]: https://github.com/rust-lang/rust/issues/67264 -[#37854]: https://github.com/rust-lang/rust/issues/37854 ------ - -The `half_open_range_patterns` feature allows RangeTo patterns -(`..10`) to be used in appropriate pattern matching contexts. -This requires also enabling the `exclusive_range_pattern` feature. - -It also enabled RangeFrom patterns but that has since been -stabilized. - -```rust -#![feature(half_open_range_patterns)] -#![feature(exclusive_range_pattern)] - let x = 5; - match x { - ..0 => println!("negative!"), // "RangeTo" pattern. Unstable. - 0 => println!("zero!"), - 1.. => println!("positive!"), // "RangeFrom" pattern. Stable. - } -``` diff --git a/src/doc/unstable-book/src/language-features/raw-dylib.md b/src/doc/unstable-book/src/language-features/raw-dylib.md index 23fc5b305..5fd208ae7 100644 --- a/src/doc/unstable-book/src/language-features/raw-dylib.md +++ b/src/doc/unstable-book/src/language-features/raw-dylib.md @@ -26,9 +26,9 @@ fn main() { ## Limitations -Currently, this feature is only supported on `-windows-msvc` targets. Non-Windows platforms don't have import -libraries, and an incompatibility between LLVM and the BFD linker means that it is not currently supported on -`-windows-gnu` targets. +This feature is unstable for the `x86` architecture, and stable for all other architectures. -On the `i686-pc-windows-msvc` target, this feature supports only the `cdecl`, `stdcall`, `system`, and `fastcall` -calling conventions. +This feature is only supported on Windows. + +On the `x86` architecture, this feature supports only the `cdecl`, `stdcall`, `system`, `fastcall`, and +`vectorcall` calling conventions. diff --git a/src/doc/unstable-book/src/language-features/unix-sigpipe.md b/src/doc/unstable-book/src/language-features/unix-sigpipe.md new file mode 100644 index 000000000..7ed6a7de8 --- /dev/null +++ b/src/doc/unstable-book/src/language-features/unix-sigpipe.md @@ -0,0 +1,62 @@ +# `unix_sigpipe` + +The tracking issue for this feature is: [#97889] + +[#97889]: https://github.com/rust-lang/rust/issues/97889 + +--- + +The `#[unix_sigpipe = "..."]` attribute on `fn main()` can be used to specify how libstd shall setup `SIGPIPE` on Unix platforms before invoking `fn main()`. This attribute is ignored on non-Unix targets. There are three variants: +* `#[unix_sigpipe = "inherit"]` +* `#[unix_sigpipe = "sig_dfl"]` +* `#[unix_sigpipe = "sig_ign"]` + +## `#[unix_sigpipe = "inherit"]` + +Leave `SIGPIPE` untouched before entering `fn main()`. Unless the parent process has changed the default `SIGPIPE` handler from `SIG_DFL` to something else, this will behave the same as `#[unix_sigpipe = "sig_dfl"]`. + +## `#[unix_sigpipe = "sig_dfl"]` + +Set the `SIGPIPE` handler to `SIG_DFL`. This will result in your program getting killed if it tries to write to a closed pipe. This is normally what you want if your program produces textual output. + +### Example + +```rust,no_run +#![feature(unix_sigpipe)] +#[unix_sigpipe = "sig_dfl"] +fn main() { loop { println!("hello world"); } } +``` + +```bash +% ./main | head -n 1 +hello world +``` + +## `#[unix_sigpipe = "sig_ign"]` + +Set the `SIGPIPE` handler to `SIG_IGN` before invoking `fn main()`. This will result in `ErrorKind::BrokenPipe` errors if you program tries to write to a closed pipe. This is normally what you want if you for example write socket servers, socket clients, or pipe peers. + +This is what libstd has done by default since 2014. (However, see the note on child processes below.) + +### Example + +```rust,no_run +#![feature(unix_sigpipe)] +#[unix_sigpipe = "sig_ign"] +fn main() { loop { println!("hello world"); } } +``` + +```bash +% ./main | head -n 1 +hello world +thread 'main' panicked at 'failed printing to stdout: Broken pipe (os error 32)', library/std/src/io/stdio.rs:1016:9 +note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace +``` + +### Note on child processes + +When spawning child processes, the legacy Rust behavior if `#[unix_sigpipe]` is not specified is to +reset `SIGPIPE` to `SIG_DFL`. + +If `#[unix_sigpipe = "..."]` is specified, no matter what its value is, the signal disposition of +`SIGPIPE` is no longer reset. This means that the child inherits the parent's `SIGPIPE` behavior. |