Auto merge of #44186 - alexcrichton:rollup, r=alexcrichton

Rollup of 8 pull requests

- Successful merges: #44044, #44089, #44116, #44125, #44154, #44157, #44160, #44172
- Failed merges: #44162

5 files changed, 130 insertions, 33 deletions

diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs
index c426bf8086e..0330ff5950b 100644
--- a/src/libstd/macros.rs
+++ b/src/libstd/macros.rs
@@ -26,13 +26,33 @@ macro_rules! __rust_unstable_column {
 
 /// The entry point for panic of Rust threads.
 ///
+/// This allows a program to to terminate immediately and provide feedback
+/// to the caller of the program. `panic!` should be used when a program reaches
+/// an unrecoverable problem.
+///
+/// This macro is the perfect way to assert conditions in example code and in
+/// tests.  `panic!` is closely tied with the `unwrap` method of both [`Option`]
+/// and [`Result`][runwrap] enums.  Both implementations call `panic!` when they are set
+/// to None or Err variants.
+///
 /// This macro is used to inject panic into a Rust thread, causing the thread to
 /// panic entirely. Each thread's panic can be reaped as the `Box<Any>` type,
 /// and the single-argument form of the `panic!` macro will be the value which
 /// is transmitted.
 ///
+/// [`Result`] enum is often a better solution for recovering from errors than
+/// using the `panic!` macro.  This macro should be used to avoid proceeding using
+/// incorrect values, such as from external sources.  Detailed information about
+/// error handling is found in the [book].
+///
 /// The multi-argument form of this macro panics with a string and has the
-/// `format!` syntax for building a string.
+/// [`format!`] syntax for building a string.
+///
+/// [runwrap]: ../std/result/enum.Result.html#method.unwrap
+/// [`Option`]: ../std/option/enum.Option.html#method.unwrap
+/// [`Result`]: ../std/result/enum.Result.html
+/// [`format!`]: ../std/macro.format.html
+/// [book]: ../book/second-edition/ch09-01-unrecoverable-errors-with-panic.html
 ///
 /// # Current implementation
 ///
@@ -78,15 +98,19 @@ macro_rules! panic {
 
 /// Macro for printing to the standard output.
 ///
-/// Equivalent to the `println!` macro except that a newline is not printed at
+/// Equivalent to the [`println!`] macro except that a newline is not printed at
 /// the end of the message.
 ///
 /// Note that stdout is frequently line-buffered by default so it may be
-/// necessary to use `io::stdout().flush()` to ensure the output is emitted
+/// necessary to use [`io::stdout().flush()`][flush] to ensure the output is emitted
 /// immediately.
 ///
 /// Use `print!` only for the primary output of your program.  Use
-/// `eprint!` instead to print error and progress messages.
+/// [`eprint!`] instead to print error and progress messages.
+///
+/// [`println!`]: ../std/macro.println.html
+/// [flush]: ../std/io/trait.Write.html#tymethod.flush
+/// [`eprint!`]: ../std/macro.eprint.html
 ///
 /// # Panics
 ///
@@ -118,16 +142,20 @@ macro_rules! print {
     ($($arg:tt)*) => ($crate::io::_print(format_args!($($arg)*)));
 }
 
-/// Macro for printing to the standard output, with a newline. On all
-/// platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone
+/// Macro for printing to the standard output, with a newline.
+///
+/// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone
 /// (no additional CARRIAGE RETURN (`\r`/`U+000D`).
 ///
-/// Use the `format!` syntax to write data to the standard output.
-/// See `std::fmt` for more information.
+/// Use the [`format!`] syntax to write data to the standard output.
+/// See [`std::fmt`] for more information.
 ///
 /// Use `println!` only for the primary output of your program.  Use
-/// `eprintln!` instead to print error and progress messages.
+/// [`eprintln!`] instead to print error and progress messages.
 ///
+/// [`format!`]: ../std/macro.format.html
+/// [`std::fmt`]: ../std/fmt/index.html
+/// [`eprintln!`]: ../std/macro.eprint.html
 /// # Panics
 ///
 /// Panics if writing to `io::stdout` fails.
@@ -149,16 +177,25 @@ macro_rules! println {
 
 /// Macro for printing to the standard error.
 ///
-/// Equivalent to the `print!` macro, except that output goes to
-/// `io::stderr` instead of `io::stdout`.  See `print!` for
+/// Equivalent to the [`print!`] macro, except that output goes to
+/// [`io::stderr`] instead of `io::stdout`.  See [`print!`] for
 /// example usage.
 ///
 /// Use `eprint!` only for error and progress messages.  Use `print!`
 /// instead for the primary output of your program.
 ///
+/// [`io::stderr`]: ../std/io/struct.Stderr.html
+/// [`print!`]: ../std/macro.print.html
+///
 /// # Panics
 ///
 /// Panics if writing to `io::stderr` fails.
+///
+/// # Examples
+///
+/// ```
+/// eprint!("Error: Could not complete task");
+/// ```
 #[macro_export]
 #[stable(feature = "eprint", since = "1.19.0")]
 #[allow_internal_unstable]
@@ -168,16 +205,25 @@ macro_rules! eprint {
 
 /// Macro for printing to the standard error, with a newline.
 ///
-/// Equivalent to the `println!` macro, except that output goes to
-/// `io::stderr` instead of `io::stdout`.  See `println!` for
+/// Equivalent to the [`println!`] macro, except that output goes to
+/// [`io::stderr`] instead of `io::stdout`.  See [`println!`] for
 /// example usage.
 ///
 /// Use `eprintln!` only for error and progress messages.  Use `println!`
 /// instead for the primary output of your program.
 ///
+/// [`io::stderr`]: ../std/io/struct.Stderr.html
+/// [`println!`]: ../std/macro.println.html
+///
 /// # Panics
 ///
 /// Panics if writing to `io::stderr` fails.
+///
+/// # Examples
+///
+/// ```
+/// eprintln!("Error: Could not complete task");
+/// ```
 #[macro_export]
 #[stable(feature = "eprint", since = "1.19.0")]
 macro_rules! eprintln {
@@ -267,13 +313,23 @@ pub mod builtin {
 
     /// The core macro for formatted string creation & output.
     ///
+    /// This macro functions by taking a formatting string literal containing
+    /// `{}` for each additional argument passed.  `format_args!` prepares the
+    /// additional parameters to ensure the output can be interpreted as a string
+    /// and canonicalizes the arguments into a single type.  Any value that implements
+    /// the [`Display`] trait can be passed to `format_args!`, as can any
+    /// [`Debug`] implementation be passed to a `{:?}` within the formatting string.
+    ///
     /// This macro produces a value of type [`fmt::Arguments`]. This value can be
-    /// passed to the functions in [`std::fmt`] for performing useful functions.
+    /// passed to the macros within [`std::fmt`] for performing useful redirection.
     /// All other formatting macros ([`format!`], [`write!`], [`println!`], etc) are
-    /// proxied through this one.
+    /// proxied through this one.  `format_args!`, unlike its derived macros, avoids
+    /// heap allocations.
     ///
     /// For more information, see the documentation in [`std::fmt`].
     ///
+    /// [`Display`]: ../std/fmt/trait.Display.html
+    /// [`Debug`]: ../std/fmt/trait.Debug.html
     /// [`fmt::Arguments`]: ../std/fmt/struct.Arguments.html
     /// [`std::fmt`]: ../std/fmt/index.html
     /// [`format!`]: ../std/macro.format.html
@@ -301,9 +357,11 @@ pub mod builtin {
     /// compile time, yielding an expression of type `&'static str`.
     ///
     /// If the environment variable is not defined, then a compilation error
-    /// will be emitted.  To not emit a compile error, use the `option_env!`
+    /// will be emitted.  To not emit a compile error, use the [`option_env!`]
     /// macro instead.
     ///
+    /// [`option_env!`]: ../std/macro.option_env.html
+    ///
     /// # Examples
     ///
     /// ```
@@ -319,11 +377,14 @@ pub mod builtin {
     /// If the named environment variable is present at compile time, this will
     /// expand into an expression of type `Option<&'static str>` whose value is
     /// `Some` of the value of the environment variable. If the environment
-    /// variable is not present, then this will expand to `None`.
+    /// variable is not present, then this will expand to `None`.  See
+    /// [`Option<T>`][option] for more information on this type.
     ///
     /// A compile time error is never emitted when using this macro regardless
     /// of whether the environment variable is present or not.
     ///
+    /// [option]: ../std/option/enum.Option.html
+    ///
     /// # Examples
     ///
     /// ```
@@ -385,10 +446,16 @@ pub mod builtin {
 
     /// A macro which expands to the line number on which it was invoked.
     ///
+    /// With [`column!`] and [`file!`], these macros provide debugging information for
+    /// developers about the location within the source.
+    ///
     /// The expanded expression has type `u32`, and the returned line is not
     /// the invocation of the `line!()` macro itself, but rather the first macro
     /// invocation leading up to the invocation of the `line!()` macro.
     ///
+    /// [`column!`]: macro.column.html
+    /// [`file!`]: macro.file.html
+    ///
     /// # Examples
     ///
     /// ```
@@ -401,9 +468,15 @@ pub mod builtin {
 
     /// A macro which expands to the column number on which it was invoked.
     ///
+    /// With [`line!`] and [`file!`], these macros provide debugging information for
+    /// developers about the location within the source.
+    ///
     /// The expanded expression has type `u32`, and the returned column is not
-    /// the invocation of the `column!()` macro itself, but rather the first macro
-    /// invocation leading up to the invocation of the `column!()` macro.
+    /// the invocation of the `column!` macro itself, but rather the first macro
+    /// invocation leading up to the invocation of the `column!` macro.
+    ///
+    /// [`line!`]: macro.line.html
+    /// [`file!`]: macro.file.html
     ///
     /// # Examples
     ///
@@ -417,11 +490,18 @@ pub mod builtin {
 
     /// A macro which expands to the file name from which it was invoked.
     ///
+    /// With [`line!`] and [`column!`], these macros provide debugging information for
+    /// developers about the location within the source.
+    ///
+    ///
     /// The expanded expression has type `&'static str`, and the returned file
-    /// is not the invocation of the `file!()` macro itself, but rather the
-    /// first macro invocation leading up to the invocation of the `file!()`
+    /// is not the invocation of the `file!` macro itself, but rather the
+    /// first macro invocation leading up to the invocation of the `file!`
     /// macro.
     ///
+    /// [`line!`]: macro.line.html
+    /// [`column!`]: macro.column.html
+    ///
     /// # Examples
     ///
     /// ```
diff --git a/src/libstd/os/raw.rs b/src/libstd/os/raw.rs
index c34491941d6..fe0427d4e5f 100644
--- a/src/libstd/os/raw.rs
+++ b/src/libstd/os/raw.rs
@@ -14,8 +14,7 @@
 
 use fmt;
 
-#[cfg(any(target_os = "emscripten",
-          all(target_os = "linux", any(target_arch = "aarch64",
+#[cfg(any(all(target_os = "linux", any(target_arch = "aarch64",
                                        target_arch = "arm",
                                        target_arch = "powerpc",
                                        target_arch = "powerpc64",
@@ -24,8 +23,7 @@ use fmt;
                                          target_arch = "arm")),
           all(target_os = "fuchsia", target_arch = "aarch64")))]
 #[stable(feature = "raw_os", since = "1.1.0")] pub type c_char = u8;
-#[cfg(not(any(target_os = "emscripten",
-              all(target_os = "linux", any(target_arch = "aarch64",
+#[cfg(not(any(all(target_os = "linux", any(target_arch = "aarch64",
                                            target_arch = "arm",
                                            target_arch = "powerpc",
                                            target_arch = "powerpc64",
diff --git a/src/libstd/sys/unix/fd.rs b/src/libstd/sys/unix/fd.rs
index 138087f1651..f50b093acc8 100644
--- a/src/libstd/sys/unix/fd.rs
+++ b/src/libstd/sys/unix/fd.rs
@@ -71,13 +71,21 @@ impl FileDesc {
         #[cfg(target_os = "android")]
         use super::android::cvt_pread64;
 
-        #[cfg(not(target_os = "android"))]
+        #[cfg(target_os = "emscripten")]
         unsafe fn cvt_pread64(fd: c_int, buf: *mut c_void, count: usize, offset: i64)
             -> io::Result<isize>
         {
-            #[cfg(any(target_os = "linux", target_os = "emscripten"))]
             use libc::pread64;
-            #[cfg(not(any(target_os = "linux", target_os = "emscripten")))]
+            cvt(pread64(fd, buf, count, offset as i32))
+        }
+
+        #[cfg(not(any(target_os = "android", target_os = "emscripten")))]
+        unsafe fn cvt_pread64(fd: c_int, buf: *mut c_void, count: usize, offset: i64)
+            -> io::Result<isize>
+        {
+            #[cfg(target_os = "linux")]
+            use libc::pread64;
+            #[cfg(not(target_os = "linux"))]
             use libc::pread as pread64;
             cvt(pread64(fd, buf, count, offset))
         }
@@ -104,13 +112,21 @@ impl FileDesc {
         #[cfg(target_os = "android")]
         use super::android::cvt_pwrite64;
 
-        #[cfg(not(target_os = "android"))]
+        #[cfg(target_os = "emscripten")]
+        unsafe fn cvt_pwrite64(fd: c_int, buf: *const c_void, count: usize, offset: i64)
+            -> io::Result<isize>
+        {
+            use libc::pwrite64;
+            cvt(pwrite64(fd, buf, count, offset as i32))
+        }
+
+        #[cfg(not(any(target_os = "android", target_os = "emscripten")))]
         unsafe fn cvt_pwrite64(fd: c_int, buf: *const c_void, count: usize, offset: i64)
             -> io::Result<isize>
         {
-            #[cfg(any(target_os = "linux", target_os = "emscripten"))]
+            #[cfg(target_os = "linux")]
             use libc::pwrite64;
-            #[cfg(not(any(target_os = "linux", target_os = "emscripten")))]
+            #[cfg(not(target_os = "linux"))]
             use libc::pwrite as pwrite64;
             cvt(pwrite64(fd, buf, count, offset))
         }
diff --git a/src/libstd/sys/unix/fs.rs b/src/libstd/sys/unix/fs.rs
index cb0f687e072..f94af491332 100644
--- a/src/libstd/sys/unix/fs.rs
+++ b/src/libstd/sys/unix/fs.rs
@@ -514,6 +514,8 @@ impl File {
             SeekFrom::End(off) => (libc::SEEK_END, off),
             SeekFrom::Current(off) => (libc::SEEK_CUR, off),
         };
+        #[cfg(target_os = "emscripten")]
+        let pos = pos as i32;
         let n = cvt(unsafe { lseek64(self.0.raw(), pos, whence) })?;
         Ok(n as u64)
     }
diff --git a/src/libstd/sys/unix/process/process_unix.rs b/src/libstd/sys/unix/process/process_unix.rs
index edd322ca6fa..ae24021fb6c 100644
--- a/src/libstd/sys/unix/process/process_unix.rs
+++ b/src/libstd/sys/unix/process/process_unix.rs
@@ -10,7 +10,6 @@
 
 use io::{self, Error, ErrorKind};
 use libc::{self, c_int, gid_t, pid_t, uid_t};
-use mem;
 use ptr;
 
 use sys::cvt;
@@ -184,7 +183,9 @@ impl Command {
         }
 
         // NaCl has no signal support.
-        if cfg!(not(any(target_os = "nacl", target_os = "emscripten"))) {
+        #[cfg(not(any(target_os = "nacl", target_os = "emscripten")))]
+        {
+            use mem;
             // Reset signal handling so the child process starts in a
             // standardized state. libstd ignores SIGPIPE, and signal-handling
             // libraries often set a mask. Child processes inherit ignored