Skip to content

Commit 8ce3484

Browse files
authored
Correct errors in the reference of extern functions definitions
1 parent 97f9691 commit 8ce3484

File tree

1 file changed

+50
-14
lines changed

1 file changed

+50
-14
lines changed

src/items/functions.md

Lines changed: 50 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -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")]
125147
extern "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 }
133162
let 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
138168
implemented 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

142178
Functions qualified with the `const` keyword are const functions. _Const

0 commit comments

Comments
 (0)