Text of rust.docs.kernel.org › core › primitive.fn.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

fn - Rust

Skip to main content fn Primitive Type fn 1.0.0 Expand description Function pointers, like fn(usize) -> bool . See also the traits Fn , FnMut , and FnOnce . Function pointers are pointers that point to code , not data. They can be called just like functions. Like references, function pointers are, among other things, assumed to not be null, so if you want to pass a function pointer over FFI and be able to accommodate null pointers, make your type Option<fn()> with your required signature.

Note that FFI requires additional care to ensure that the ABI for both sides of the call match. The exact requirements are not currently documented. § Safety Plain function pointers are obtained by casting either plain functions, or closures that don’t capture an environment: fn add_one(x: usize) -> usize { x + 1 } let ptr: fn (usize) -> usize = add_one; assert_eq! (ptr( 5 ), 6 ); let clos: fn (usize) -> usize = |x| x + 5 ; assert_eq! (clos( 5 ), 10 ); In addition to varying based on their signature, function pointers come in two flavors: safe and unsafe.

Plain fn() function pointers can only point to safe functions, while unsafe fn() function pointers can point to safe or unsafe functions. fn add_one(x: usize) -> usize { x + 1 } unsafe fn add_one_unsafely(x: usize) -> usize { x + 1 } let safe_ptr: fn (usize) -> usize = add_one; //ERROR: mismatched types: expected normal fn, found unsafe fn //let bad_ptr: fn(usize) -> usize = add_one_unsafely; let unsafe_ptr: unsafe fn (usize) -> usize = add_one_unsafely; let really_safe_ptr: unsafe fn (usize) -> usize = add_one; § ABI On top of that, function pointers can vary based on what ABI they use.

This is achieved by adding the extern keyword before the type, followed by the ABI in question. The default ABI is “Rust”, i.e., fn() is the exact same type as extern "Rust" fn() . A pointer to a function with C ABI would have type extern "C" fn() . extern "ABI" { ... } blocks declare functions with ABI “ABI”. The default here is “C”, i.e., functions declared in an extern {...} block have “C” ABI. For more information and a list of supported ABIs, see the nomicon’s section on foreign calling conventions . § Variadic functions Extern function declarations with the “C” or “cdecl” ABIs can also be variadic , allowing them to be called with a variable number of arguments.

Normal Rust functions, even those with an extern "ABI" , cannot be variadic. For more information, see the nomicon’s section on variadic functions . § Creating function pointers When bar is the name of a function, then the expression bar is not a function pointer. Rather, it denotes a value of an unnameable type that uniquely identifies the function bar . The value is zero-sized because the type already identifies the function.

This has the advantage that “calling” the value (it implements the Fn* traits) does not require dynamic dispatch. This zero-sized type coerces to a regular function pointer. For example: fn bar(x: i32) {} let not_bar_ptr = bar; // `not_bar_ptr` is zero-sized, uniquely identifying `bar` assert_eq! (size_of_val( & not_bar_ptr), 0 ); let bar_ptr: fn (i32) = not_bar_ptr; // force coercion to function pointer assert_eq! (size_of_val( & bar_ptr), size_of::<usize>()); let footgun = & bar; // this is a shared reference to the zero-sized type identifying `bar` The last line shows that &bar is not a function pointer either.

Rather, it is a reference to the function-specific ZST. &bar is basically never what you want when bar is a function. § Casting to and from integers You can cast function pointers directly to integers: let fnptr: fn (i32) -> i32 = |x| x+ 2 ; let fnptr_addr = fnptr as usize; However, a direct cast back is not possible. You need to use transmute : let fnptr = fnptr_addr as *const (); let fnptr: fn (i32) -> i32 = unsafe { std::mem::transmute(fnptr) }; assert_eq! (fnptr( 40 ), 42 ); Crucially, we as -cast to a raw pointer before transmute ing to a function pointer.

This avoids an integer-to-pointer transmute , which can be problematic. Transmuting between raw pointers and function pointers (i.e., two pointer types) is fine. Note that all of this is not portable to platforms where function pointers and data pointers have different sizes. § ABI compatibility Generally, when a function is declared with one signature and called via a function pointer with a different signature, the two signatures must be ABI-compatible or else calling the function via that function pointer is Undefined Behavior.

ABI compatibility is a lot stricter than merely having the same memory layout; for example, even if i32 and f32 have the same size and alignment, they might be passed in different registers and hence not be ABI-compatible. ABI compatibility as a concern only arises in code that alters the type of function pointers, and code that imports functions via extern blocks. Altering the type of function pointers is wildly unsafe (as in, a lot more unsafe than even transmute_copy ), and should only occur in the most exceptional circumstances.

Most Rust code just imports functions via use . So, most likely you do not have to worry about ABI compatibility. But assuming such circumstances, what are the rules? For this section, we are only considering the ABI of direct Rust-to-Rust calls (with both definition and callsite visible to the Rust compiler), not linking in general – once functions are imported via extern blocks, there are more things to consider that we do not go into here.

Note that this also applies to passing/calling functions across language boundaries via function pointers. Nothing in this section should be taken as a guarantee for non-Rust-to-Rust calls, even with types from core::ffi or libc . For two signatures to be considered ABI-compatible , they must use a compatible ABI string, must take the same number of arguments, and the individual argument types and the return types must be ABI-compatible.

The ABI string is declared via extern "ABI" fn(...) -> ... ; note that fn name(...) -> ... implicitly uses the "Rust" ABI string and extern fn name(...) -> ... implicitly uses the "C" ABI string. The ABI strings are guaranteed to be compatible if they are the same, or if the caller ABI string is $X-unwind and the callee ABI string is $X , where $X is one of the following: “C”, “aapcs”, “fastcall”, “stdcall”, “system”, “sysv64”, “thiscall”, “vectorcall”, “win64”.

The following types are guaranteed to be ABI-compatible: *const T , *mut T , &T , &mut T , Box<T> (specifically, only Box<T, Global> ), and NonNull<T> are all ABI-compatible with each other for all T . They are also ABI-compatible with each other for different T if they have the same metadata type ( <T as Pointee>::Metadata ). However, see the Control Flow Integrity docs for caveats. usize is ABI-compatible with the uN integer type of the same size, and likewise isize is ABI-compatible with the iN integer type of the same size. char is ABI-compatible with u32 .

Any two fn (function pointer) types are ABI-compatible with each other if they have the same ABI string or the ABI string only differs in a trailing -unwind , independent of the rest of their signature. (This means you can pass fn() to a function expecting fn(i32) , and the call will be valid ABI-wise. The callee receives the result of transmuting the function pointer from fn() to fn(i32) ; that transmutation is itself a well-defined operation, it’s just almost certainly UB to later call that function pointer.) Any two types with size 0 and alignment 1 are ABI-compatible.

A repr(transparent) type T is ABI-compatible with its unique non-trivial field, i.e., the unique field that doesn’t have size 0 and alignment 1 (if there is such a field). i32 is ABI-compatible with NonZero<i32> , and similar for all other integer types. If T is guaranteed to be subject to the null pointer optimization , and E is an enum satisfying the following requirements, then T and

The rest of this page is on the live site.