Document foreign variadic functions in TRPL and the reference.

Fixes https://github.com/rust-lang/rust/issues/38485.

2 files changed, 34 insertions, 0 deletions

diff --git a/src/doc/book/ffi.md b/src/doc/book/ffi.md
index b53af694428..41457ee67a5 100644
--- a/src/doc/book/ffi.md
+++ b/src/doc/book/ffi.md
@@ -574,6 +574,31 @@ The [`libc` crate on crates.io][libc] includes type aliases and function
 definitions for the C standard library in the `libc` module, and Rust links
 against `libc` and `libm` by default.
 
+# Variadic functions
+
+In C, functions can be 'variadic', meaning they accept a variable number of arguments. This can
+be achieved in Rust by specifying `...` within the argument list of a foreign function declaration:
+
+```no_run
+extern {
+    fn foo(x: i32, ...);
+}
+
+fn main() {
+    unsafe {
+        foo(10, 20, 30, 40, 50);
+    }
+}
+```
+
+Normal Rust functions can *not* be variadic:
+
+```ignore
+// This will not compile
+
+fn foo(x: i32, ...) { }
+```
+
 # The "nullable pointer optimization"
 
 Certain Rust types are defined to never be `null`. This includes references (`&T`,
diff --git a/src/doc/reference.md b/src/doc/reference.md
index b5a91a170d8..9898c31282c 100644
--- a/src/doc/reference.md
+++ b/src/doc/reference.md
@@ -1657,6 +1657,15 @@ Functions within external blocks may be called by Rust code, just like
 functions defined in Rust. The Rust compiler automatically translates between
 the Rust ABI and the foreign ABI.
 
+Functions within external blocks may be variadic by specifying `...` after one
+or more named arguments in the argument list:
+
+```ignore
+extern {
+    fn foo(x: i32, ...);
+}
+```
+
 A number of [attributes](#ffi-attributes) control the behavior of external blocks.
 
 By default external blocks assume that the library they are calling uses the