3 The tracking issue for this feature is: None.
5 ------------------------
7 The `rustc` compiler has certain pluggable operations, that is,
8 functionality that isn't hard-coded into the language, but is
9 implemented in libraries, with a special marker to tell the compiler
10 it exists. The marker is the attribute `#[lang = "..."]` and there are
11 various different values of `...`, i.e. various different 'lang
14 For example, `Box` pointers require two lang items, one for allocation
15 and one for deallocation. A freestanding program that uses the `Box`
16 sugar for dynamic allocations via `malloc` and `free`:
19 #![feature(lang_items, box_syntax, start, libc, core_intrinsics)]
26 pub struct Box<T>(*mut T);
28 #[lang = "exchange_malloc"]
29 unsafe fn allocate(size: usize, _align: usize) -> *mut u8 {
30 let p = libc::malloc(size as libc::size_t) as *mut u8;
32 // Check if `malloc` failed:
41 unsafe fn box_free<T: ?Sized>(ptr: *mut T) {
42 libc::free(ptr as *mut libc::c_void)
46 fn main(_argc: isize, _argv: *const *const u8) -> isize {
52 #[lang = "eh_personality"] extern fn rust_eh_personality() {}
53 #[lang = "panic_fmt"] extern fn rust_begin_panic() -> ! { unsafe { intrinsics::abort() } }
54 #[lang = "eh_unwind_resume"] extern fn rust_eh_unwind_resume() {}
55 #[no_mangle] pub extern fn rust_eh_register_frames () {}
56 #[no_mangle] pub extern fn rust_eh_unregister_frames () {}
59 Note the use of `abort`: the `exchange_malloc` lang item is assumed to
60 return a valid pointer, and so needs to do the check internally.
62 Other features provided by lang items include:
64 - overloadable operators via traits: the traits corresponding to the
65 `==`, `<`, dereferencing (`*`) and `+` (etc.) operators are all
66 marked with lang items; those specific four are `eq`, `ord`,
67 `deref`, and `add` respectively.
68 - stack unwinding and general failure; the `eh_personality`,
69 `eh_unwind_resume`, `fail` and `fail_bounds_checks` lang items.
70 - the traits in `std::marker` used to indicate types of
71 various kinds; lang items `send`, `sync` and `copy`.
72 - the marker types and variance indicators found in
73 `std::marker`; lang items `covariant_type`,
74 `contravariant_lifetime`, etc.
76 Lang items are loaded lazily by the compiler; e.g. if one never uses
77 `Box` then there is no need to define functions for `exchange_malloc`
78 and `box_free`. `rustc` will emit an error when an item is needed
79 but not found in the current crate or any that it depends on.
81 Most lang items are defined by `libcore`, but if you're trying to build
82 an executable without the standard library, you'll run into the need
83 for lang items. The rest of this page focuses on this use-case, even though
84 lang items are a bit broader than that.
88 In order to build a `#[no_std]` executable we will need libc as a dependency.
89 We can specify this using our `Cargo.toml` file:
93 libc = { version = "0.2.14", default-features = false }
96 Note that the default features have been disabled. This is a critical step -
97 **the default features of libc include the standard library and so must be
100 ### Writing an executable without stdlib
102 Controlling the entry point is possible in two ways: the `#[start]` attribute,
103 or overriding the default shim for the C `main` function with your own.
105 The function marked `#[start]` is passed the command line parameters
106 in the same format as C:
109 #![feature(lang_items, core_intrinsics)]
112 use core::intrinsics;
114 // Pull in the system libc library for what crt0.o likely requires.
117 // Entry point for this program.
119 fn start(_argc: isize, _argv: *const *const u8) -> isize {
123 // These functions are used by the compiler, but not
124 // for a bare-bones hello world. These are normally
125 // provided by libstd.
126 #[lang = "eh_personality"]
128 pub extern fn rust_eh_personality() {
131 // This function may be needed based on the compilation target.
132 #[lang = "eh_unwind_resume"]
134 pub extern fn rust_eh_unwind_resume() {
137 #[lang = "panic_fmt"]
139 pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
143 unsafe { intrinsics::abort() }
147 To override the compiler-inserted `main` shim, one has to disable it
148 with `#![no_main]` and then create the appropriate symbol with the
149 correct ABI and the correct name, which requires overriding the
150 compiler's name mangling too:
153 #![feature(lang_items, core_intrinsics)]
157 use core::intrinsics;
159 // Pull in the system libc library for what crt0.o likely requires.
162 // Entry point for this program.
163 #[no_mangle] // ensure that this symbol is called `main` in the output
164 pub extern fn main(_argc: i32, _argv: *const *const u8) -> i32 {
168 // These functions are used by the compiler, but not
169 // for a bare-bones hello world. These are normally
170 // provided by libstd.
171 #[lang = "eh_personality"]
173 pub extern fn rust_eh_personality() {
176 // This function may be needed based on the compilation target.
177 #[lang = "eh_unwind_resume"]
179 pub extern fn rust_eh_unwind_resume() {
182 #[lang = "panic_fmt"]
184 pub extern fn rust_begin_panic(_msg: core::fmt::Arguments,
188 unsafe { intrinsics::abort() }
192 In many cases, you may need to manually link to the `compiler_builtins` crate
193 when building a `no_std` binary. You may observe this via linker error messages
194 such as "```undefined reference to `__rust_probestack'```". Using this crate
195 also requires enabling the library feature `compiler_builtins_lib`. You can read
196 more about this [here][compiler-builtins-lib].
198 [compiler-builtins-lib]: library-features/compiler-builtins-lib.html
200 ## More about the language items
202 The compiler currently makes a few assumptions about symbols which are
203 available in the executable to call. Normally these functions are provided by
204 the standard library, but without it you must define your own. These symbols
205 are called "language items", and they each have an internal name, and then a
206 signature that an implementation must conform to.
208 The first of these functions, `rust_eh_personality`, is used by the failure
209 mechanisms of the compiler. This is often mapped to GCC's personality function
210 (see the [libstd implementation][unwind] for more information), but crates
211 which do not trigger a panic can be assured that this function is never
212 called. The language item's name is `eh_personality`.
214 [unwind]: https://github.com/rust-lang/rust/blob/master/src/libpanic_unwind/gcc.rs
216 The second function, `rust_begin_panic`, is also used by the failure mechanisms of the
217 compiler. When a panic happens, this controls the message that's displayed on
218 the screen. While the language item's name is `panic_fmt`, the symbol name is
221 A third function, `rust_eh_unwind_resume`, is also needed if the `custom_unwind_resume`
222 flag is set in the options of the compilation target. It allows customizing the
223 process of resuming unwind at the end of the landing pads. The language item's name
224 is `eh_unwind_resume`.
226 ## List of all language items
228 This is a list of all language items in Rust along with where they are located in
232 - `i8`: `libcore/num/mod.rs`
233 - `i16`: `libcore/num/mod.rs`
234 - `i32`: `libcore/num/mod.rs`
235 - `i64`: `libcore/num/mod.rs`
236 - `i128`: `libcore/num/mod.rs`
237 - `isize`: `libcore/num/mod.rs`
238 - `u8`: `libcore/num/mod.rs`
239 - `u16`: `libcore/num/mod.rs`
240 - `u32`: `libcore/num/mod.rs`
241 - `u64`: `libcore/num/mod.rs`
242 - `u128`: `libcore/num/mod.rs`
243 - `usize`: `libcore/num/mod.rs`
244 - `f32`: `libstd/f32.rs`
245 - `f64`: `libstd/f64.rs`
246 - `char`: `libcore/char.rs`
247 - `slice`: `liballoc/slice.rs`
248 - `str`: `liballoc/str.rs`
249 - `const_ptr`: `libcore/ptr.rs`
250 - `mut_ptr`: `libcore/ptr.rs`
251 - `unsafe_cell`: `libcore/cell.rs`
253 - `start`: `libstd/rt.rs`
254 - `eh_personality`: `libpanic_unwind/emcc.rs` (EMCC)
255 - `eh_personality`: `libpanic_unwind/seh64_gnu.rs` (SEH64 GNU)
256 - `eh_personality`: `libpanic_unwind/seh.rs` (SEH)
257 - `eh_unwind_resume`: `libpanic_unwind/seh64_gnu.rs` (SEH64 GNU)
258 - `eh_unwind_resume`: `libpanic_unwind/gcc.rs` (GCC)
259 - `msvc_try_filter`: `libpanic_unwind/seh.rs` (SEH)
260 - `panic`: `libcore/panicking.rs`
261 - `panic_bounds_check`: `libcore/panicking.rs`
262 - `panic_fmt`: `libcore/panicking.rs`
263 - `panic_fmt`: `libstd/panicking.rs`
265 - `owned_box`: `liballoc/boxed.rs`
266 - `exchange_malloc`: `liballoc/heap.rs`
267 - `box_free`: `liballoc/heap.rs`
269 - `not`: `libcore/ops/bit.rs`
270 - `bitand`: `libcore/ops/bit.rs`
271 - `bitor`: `libcore/ops/bit.rs`
272 - `bitxor`: `libcore/ops/bit.rs`
273 - `shl`: `libcore/ops/bit.rs`
274 - `shr`: `libcore/ops/bit.rs`
275 - `bitand_assign`: `libcore/ops/bit.rs`
276 - `bitor_assign`: `libcore/ops/bit.rs`
277 - `bitxor_assign`: `libcore/ops/bit.rs`
278 - `shl_assign`: `libcore/ops/bit.rs`
279 - `shr_assign`: `libcore/ops/bit.rs`
280 - `deref`: `libcore/ops/deref.rs`
281 - `deref_mut`: `libcore/ops/deref.rs`
282 - `index`: `libcore/ops/index.rs`
283 - `index_mut`: `libcore/ops/index.rs`
284 - `add`: `libcore/ops/arith.rs`
285 - `sub`: `libcore/ops/arith.rs`
286 - `mul`: `libcore/ops/arith.rs`
287 - `div`: `libcore/ops/arith.rs`
288 - `rem`: `libcore/ops/arith.rs`
289 - `neg`: `libcore/ops/arith.rs`
290 - `add_assign`: `libcore/ops/arith.rs`
291 - `sub_assign`: `libcore/ops/arith.rs`
292 - `mul_assign`: `libcore/ops/arith.rs`
293 - `div_assign`: `libcore/ops/arith.rs`
294 - `rem_assign`: `libcore/ops/arith.rs`
295 - `eq`: `libcore/cmp.rs`
296 - `ord`: `libcore/cmp.rs`
298 - `fn`: `libcore/ops/function.rs`
299 - `fn_mut`: `libcore/ops/function.rs`
300 - `fn_once`: `libcore/ops/function.rs`
301 - `generator_state`: `libcore/ops/generator.rs`
302 - `generator`: `libcore/ops/generator.rs`
304 - `coerce_unsized`: `libcore/ops/unsize.rs`
305 - `drop`: `libcore/ops/drop.rs`
306 - `drop_in_place`: `libcore/ptr.rs`
307 - `clone`: `libcore/clone.rs`
308 - `copy`: `libcore/marker.rs`
309 - `send`: `libcore/marker.rs`
310 - `sized`: `libcore/marker.rs`
311 - `unsize`: `libcore/marker.rs`
312 - `sync`: `libcore/marker.rs`
313 - `phantom_data`: `libcore/marker.rs`
314 - `freeze`: `libcore/marker.rs`
315 - `debug_trait`: `libcore/fmt/mod.rs`
316 - `non_zero`: `libcore/nonzero.rs`