src/doc/unstable-book/src/language-features/lang-items.md

   1 # `lang_items`
   2
   3 The tracking issue for this feature is: None.
   4
   5 ------------------------
   6
   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
  12 items'.
  13
  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`:
  17
  18 ```rust,ignore (libc-is-finicky)
  19 #![feature(lang_items, box_syntax, start, libc, core_intrinsics, rustc_private)]
  20 #![no_std]
  21 use core::intrinsics;
  22 use core::panic::PanicInfo;
  23
  24 extern crate libc;
  25
  26 struct Unique<T>(*mut T);
  27
  28 #[lang = "owned_box"]
  29 pub struct Box<T>(Unique<T>);
  30
  31 #[lang = "exchange_malloc"]
  32 unsafe fn allocate(size: usize, _align: usize) -> *mut u8 {
  33     let p = libc::malloc(size as libc::size_t) as *mut u8;
  34
  35     // Check if `malloc` failed:
  36     if p as usize == 0 {
  37         intrinsics::abort();
  38     }
  39
  40     p
  41 }
  42
  43 #[lang = "box_free"]
  44 unsafe fn box_free<T: ?Sized>(ptr: *mut T) {
  45     libc::free(ptr as *mut libc::c_void)
  46 }
  47
  48 #[start]
  49 fn main(_argc: isize, _argv: *const *const u8) -> isize {
  50     let _x = box 1;
  51
  52     0
  53 }
  54
  55 #[lang = "eh_personality"] extern fn rust_eh_personality() {}
  56 #[lang = "panic_impl"] extern fn rust_begin_panic(info: &PanicInfo) -> ! { unsafe { intrinsics::abort() } }
  57 #[no_mangle] pub extern fn rust_eh_register_frames () {}
  58 #[no_mangle] pub extern fn rust_eh_unregister_frames () {}
  59 ```
  60
  61 Note the use of `abort`: the `exchange_malloc` lang item is assumed to
  62 return a valid pointer, and so needs to do the check internally.
  63
  64 Other features provided by lang items include:
  65
  66 - overloadable operators via traits: the traits corresponding to the
  67   `==`, `<`, dereferencing (`*`) and `+` (etc.) operators are all
  68   marked with lang items; those specific four are `eq`, `ord`,
  69   `deref`, and `add` respectively.
  70 - stack unwinding and general failure; the `eh_personality`,
  71   `panic` and `panic_bounds_check` lang items.
  72 - the traits in `std::marker` used to indicate types of
  73   various kinds; lang items `send`, `sync` and `copy`.
  74 - the marker types and variance indicators found in
  75   `std::marker`; lang items `covariant_type`,
  76   `contravariant_lifetime`, etc.
  77
  78 Lang items are loaded lazily by the compiler; e.g. if one never uses
  79 `Box` then there is no need to define functions for `exchange_malloc`
  80 and `box_free`. `rustc` will emit an error when an item is needed
  81 but not found in the current crate or any that it depends on.
  82
  83 Most lang items are defined by `libcore`, but if you're trying to build
  84 an executable without the standard library, you'll run into the need
  85 for lang items. The rest of this page focuses on this use-case, even though
  86 lang items are a bit broader than that.
  87
  88 ### Using libc
  89
  90 In order to build a `#[no_std]` executable we will need libc as a dependency.
  91 We can specify this using our `Cargo.toml` file:
  92
  93 ```toml
  94 [dependencies]
  95 libc = { version = "0.2.14", default-features = false }
  96 ```
  97
  98 Note that the default features have been disabled. This is a critical step -
  99 **the default features of libc include the standard library and so must be
 100 disabled.**
 101
 102 ### Writing an executable without stdlib
 103
 104 Controlling the entry point is possible in two ways: the `#[start]` attribute,
 105 or overriding the default shim for the C `main` function with your own.
 106
 107 The function marked `#[start]` is passed the command line parameters
 108 in the same format as C:
 109
 110 ```rust,ignore (libc-is-finicky)
 111 #![feature(lang_items, core_intrinsics, rustc_private)]
 112 #![feature(start)]
 113 #![no_std]
 114 use core::intrinsics;
 115 use core::panic::PanicInfo;
 116
 117 // Pull in the system libc library for what crt0.o likely requires.
 118 extern crate libc;
 119
 120 // Entry point for this program.
 121 #[start]
 122 fn start(_argc: isize, _argv: *const *const u8) -> isize {
 123     0
 124 }
 125
 126 // These functions are used by the compiler, but not
 127 // for a bare-bones hello world. These are normally
 128 // provided by libstd.
 129 #[lang = "eh_personality"]
 130 #[no_mangle]
 131 pub extern fn rust_eh_personality() {
 132 }
 133
 134 #[lang = "panic_impl"]
 135 #[no_mangle]
 136 pub extern fn rust_begin_panic(info: &PanicInfo) -> ! {
 137     unsafe { intrinsics::abort() }
 138 }
 139 ```
 140
 141 To override the compiler-inserted `main` shim, one has to disable it
 142 with `#![no_main]` and then create the appropriate symbol with the
 143 correct ABI and the correct name, which requires overriding the
 144 compiler's name mangling too:
 145
 146 ```rust,ignore (libc-is-finicky)
 147 #![feature(lang_items, core_intrinsics, rustc_private)]
 148 #![feature(start)]
 149 #![no_std]
 150 #![no_main]
 151 use core::intrinsics;
 152 use core::panic::PanicInfo;
 153
 154 // Pull in the system libc library for what crt0.o likely requires.
 155 extern crate libc;
 156
 157 // Entry point for this program.
 158 #[no_mangle] // ensure that this symbol is called `main` in the output
 159 pub extern fn main(_argc: i32, _argv: *const *const u8) -> i32 {
 160     0
 161 }
 162
 163 // These functions are used by the compiler, but not
 164 // for a bare-bones hello world. These are normally
 165 // provided by libstd.
 166 #[lang = "eh_personality"]
 167 #[no_mangle]
 168 pub extern fn rust_eh_personality() {
 169 }
 170
 171 #[lang = "panic_impl"]
 172 #[no_mangle]
 173 pub extern fn rust_begin_panic(info: &PanicInfo) -> ! {
 174     unsafe { intrinsics::abort() }
 175 }
 176 ```
 177
 178 In many cases, you may need to manually link to the `compiler_builtins` crate
 179 when building a `no_std` binary. You may observe this via linker error messages
 180 such as "```undefined reference to `__rust_probestack'```".
 181
 182 ## More about the language items
 183
 184 The compiler currently makes a few assumptions about symbols which are
 185 available in the executable to call. Normally these functions are provided by
 186 the standard library, but without it you must define your own. These symbols
 187 are called "language items", and they each have an internal name, and then a
 188 signature that an implementation must conform to.
 189
 190 The first of these functions, `rust_eh_personality`, is used by the failure
 191 mechanisms of the compiler. This is often mapped to GCC's personality function
 192 (see the [libstd implementation][unwind] for more information), but crates
 193 which do not trigger a panic can be assured that this function is never
 194 called. The language item's name is `eh_personality`.
 195
 196 [unwind]: https://github.com/rust-lang/rust/blob/master/library/panic_unwind/src/gcc.rs
 197
 198 The second function, `rust_begin_panic`, is also used by the failure mechanisms of the
 199 compiler. When a panic happens, this controls the message that's displayed on
 200 the screen. While the language item's name is `panic_impl`, the symbol name is
 201 `rust_begin_panic`.
 202
 203 Finally, a `eh_catch_typeinfo` static is needed for certain targets which
 204 implement Rust panics on top of C++ exceptions.
 205
 206 ## List of all language items
 207
 208 This is a list of all language items in Rust along with where they are located in
 209 the source code.
 210
 211 - Primitives
 212   - `i8`: `libcore/num/mod.rs`
 213   - `i16`: `libcore/num/mod.rs`
 214   - `i32`: `libcore/num/mod.rs`
 215   - `i64`: `libcore/num/mod.rs`
 216   - `i128`: `libcore/num/mod.rs`
 217   - `isize`: `libcore/num/mod.rs`
 218   - `u8`: `libcore/num/mod.rs`
 219   - `u16`: `libcore/num/mod.rs`
 220   - `u32`: `libcore/num/mod.rs`
 221   - `u64`: `libcore/num/mod.rs`
 222   - `u128`: `libcore/num/mod.rs`
 223   - `usize`: `libcore/num/mod.rs`
 224   - `f32`: `libstd/f32.rs`
 225   - `f64`: `libstd/f64.rs`
 226   - `char`: `libcore/char.rs`
 227   - `slice`: `liballoc/slice.rs`
 228   - `str`: `liballoc/str.rs`
 229   - `const_ptr`: `libcore/ptr.rs`
 230   - `mut_ptr`: `libcore/ptr.rs`
 231   - `unsafe_cell`: `libcore/cell.rs`
 232 - Runtime
 233   - `start`: `libstd/rt.rs`
 234   - `eh_personality`: `libpanic_unwind/emcc.rs` (EMCC)
 235   - `eh_personality`: `libpanic_unwind/gcc.rs` (GNU)
 236   - `eh_personality`: `libpanic_unwind/seh.rs` (SEH)
 237   - `eh_catch_typeinfo`: `libpanic_unwind/emcc.rs` (EMCC)
 238   - `panic`: `libcore/panicking.rs`
 239   - `panic_bounds_check`: `libcore/panicking.rs`
 240   - `panic_impl`: `libcore/panicking.rs`
 241   - `panic_impl`: `libstd/panicking.rs`
 242 - Allocations
 243   - `owned_box`: `liballoc/boxed.rs`
 244   - `exchange_malloc`: `liballoc/heap.rs`
 245   - `box_free`: `liballoc/heap.rs`
 246 - Operands
 247   - `not`: `libcore/ops/bit.rs`
 248   - `bitand`: `libcore/ops/bit.rs`
 249   - `bitor`: `libcore/ops/bit.rs`
 250   - `bitxor`: `libcore/ops/bit.rs`
 251   - `shl`: `libcore/ops/bit.rs`
 252   - `shr`: `libcore/ops/bit.rs`
 253   - `bitand_assign`: `libcore/ops/bit.rs`
 254   - `bitor_assign`: `libcore/ops/bit.rs`
 255   - `bitxor_assign`: `libcore/ops/bit.rs`
 256   - `shl_assign`: `libcore/ops/bit.rs`
 257   - `shr_assign`: `libcore/ops/bit.rs`
 258   - `deref`: `libcore/ops/deref.rs`
 259   - `deref_mut`: `libcore/ops/deref.rs`
 260   - `index`: `libcore/ops/index.rs`
 261   - `index_mut`: `libcore/ops/index.rs`
 262   - `add`: `libcore/ops/arith.rs`
 263   - `sub`: `libcore/ops/arith.rs`
 264   - `mul`: `libcore/ops/arith.rs`
 265   - `div`: `libcore/ops/arith.rs`
 266   - `rem`: `libcore/ops/arith.rs`
 267   - `neg`: `libcore/ops/arith.rs`
 268   - `add_assign`: `libcore/ops/arith.rs`
 269   - `sub_assign`: `libcore/ops/arith.rs`
 270   - `mul_assign`: `libcore/ops/arith.rs`
 271   - `div_assign`: `libcore/ops/arith.rs`
 272   - `rem_assign`: `libcore/ops/arith.rs`
 273   - `eq`: `libcore/cmp.rs`
 274   - `ord`: `libcore/cmp.rs`
 275 - Functions
 276   - `fn`: `libcore/ops/function.rs`
 277   - `fn_mut`: `libcore/ops/function.rs`
 278   - `fn_once`: `libcore/ops/function.rs`
 279   - `generator_state`: `libcore/ops/generator.rs`
 280   - `generator`: `libcore/ops/generator.rs`
 281 - Other
 282   - `coerce_unsized`: `libcore/ops/unsize.rs`
 283   - `drop`: `libcore/ops/drop.rs`
 284   - `drop_in_place`: `libcore/ptr.rs`
 285   - `clone`: `libcore/clone.rs`
 286   - `copy`: `libcore/marker.rs`
 287   - `send`: `libcore/marker.rs`
 288   - `sized`: `libcore/marker.rs`
 289   - `unsize`: `libcore/marker.rs`
 290   - `sync`: `libcore/marker.rs`
 291   - `phantom_data`: `libcore/marker.rs`
 292   - `discriminant_kind`: `libcore/marker.rs`
 293   - `freeze`: `libcore/marker.rs`
 294   - `debug_trait`: `libcore/fmt/mod.rs`
 295   - `non_zero`: `libcore/nonzero.rs`
 296   - `arc`: `liballoc/sync.rs`
 297   - `rc`: `liballoc/rc.rs`