@@ -109,34 +109,70 @@ sufficient context to determine the type parameters. For example,
109109
110110## Extern functions
111111
112- Extern functions are part of Rust's foreign function interface, providing the
113- opposite functionality to [ external blocks] . Whereas external
114- blocks allow Rust code to call foreign code, extern functions with bodies
115- defined in Rust code _ can be called by foreign code_ . They are defined in the
116- same way as any other Rust function, except that they have the ` extern `
117- qualifier.
112+ Extern function _ definitions_ allow defining functions that can be called
113+ with a particular ABI:
114+
115+ ``` rust,norun
116+ extern "ABI" fn foo() { ... }
117+ ```
118+
119+ An extern function _ declaration_ via an [ external block] can be used to
120+ provide an item for these functions that can be called by Rust code without
121+ providing their definition.
122+
123+ The default ABI of Rust functions like ` fn foo() {} ` is ` "Rust" ` . While we
124+ abbreviate the type of Rust functions like ` foo ` as ` fn() ` , this is actually a
125+ synonym for ` extern "Rust" fn() ` . That is, this:
118126
119127``` rust
120- // Declares an extern fn, the ABI defaults to "C"
121- extern fn new_i32 () -> i32 { 0 }
128+ fn foo () {}
129+ ```
130+
131+ is identical to
132+
133+ ``` rust
134+ extern " Rust" fn foo () {}
135+ ```
122136
123- // Declares an extern fn with "stdcall" ABI
137+ Functions in Rust can be called by foreign code, and using an ABI that
138+ differs from Rust allows, for example, to provide functions that can be
139+ called from other programming languages like C:
140+
141+ ``` rust
142+ // Declares a function with the "C" ABI
143+ extern " C" fn new_i32 () -> i32 { 0 }
144+
145+ // Declares a function with the "stdcall" ABI
124146# #[cfg(target_arch = " x86_64" )]
125147extern " stdcall" fn new_i32_stdcall () -> i32 { 0 }
126148```
127149
128- Unlike normal functions, extern fns have type ` extern "ABI" fn() ` . This is the
129- same type as the functions declared in an extern block.
150+ Just as with [ external block] , when the ` extern ` keyword is used and the ` "ABI `
151+ is omitted, the ABI used defaults to ` "C" ` . That is, this
152+
153+ ``` rust
154+ extern fn new_i32 () -> i32 { 0 }
155+ let fptr : extern fn () -> i32 = new_i32 ;
156+ ```
157+
158+ is identical to
130159
131160``` rust
132- # extern fn new_i32 () -> i32 { 0 }
161+ extern " C " fn new_i32 () -> i32 { 0 }
133162let fptr : extern " C" fn () -> i32 = new_i32 ;
134163```
135164
136- As non-Rust calling conventions do not support unwinding, unwinding past the end
137- of an extern function will cause the process to abort. In LLVM, this is
165+ Since functions with an ABI that differs from ` "Rust" ` do not support
166+ unwinding in the exact same way that Rust does, unwinding past the end
167+ of functions with such ABIs causes the process to abort. In LLVM, this is
138168implemented by executing an illegal instruction.
139169
170+ Some ABIs that are identical to ` "Rust" ` are:
171+
172+ * ` "rust-call" `
173+ * ` "platform-intrinsic" `
174+ * ` "rust-intrinsic" `
175+
140176## Const functions
141177
142178Functions qualified with the ` const ` keyword are const functions. _ Const
0 commit comments