1. Symptoms
When the Rust compiler encounters error E0583, you will see a diagnostic message similar to the following in your build output:
error[E0583]: linkage name is not unique
--> src/main.rs:10:1
|
10 | extern "C" {
11 | #[link_name = "my_function"]
12 | fn my_function();
13 | #[link_name = "my_function"]
14 | fn my_function();
15 | }
|
= linkage name `my_function` used in multiple `extern` blocks for the same ABI
The compiler identifies that the same linkage name appears multiple times within an extern block, which violates the uniqueness requirement for foreign function symbols. The error points to the specific lines where the duplicate declarations occur and includes a note explaining that the linkage name must be unique for each ABI.
In more complex scenarios involving multiple source files, you may also see linker errors that manifest as multiple definition conflicts during the linking phase:
note: defined in `my_crate.a` was also defined in `other_crate.a`
error: linking with `cc` failed: exit code: 1
The Rust-specific error E0583 is caught at compile time before the linker runs, providing you with precise location information about the offending code.
2. Root Cause
Error E0583 stems from the Rust language’s requirement that each foreign function symbol must have a unique linkage name when using the foreign function interface (FFI). This uniqueness is mandated by the language specification to prevent ambiguity during the linking process and to maintain clear contract definitions between Rust code and external libraries.
The root cause typically involves one of three scenarios. First, you may have accidentally declared the same extern function twice with identical or conflicting linkage attributes. This commonly happens during refactoring when copy-pasting extern blocks or when merging code from multiple sources.
Second, the issue can arise from macro expansion that generates duplicate declarations. If your macros are not carefully designed to prevent re-expansion, they can produce multiple extern declarations with the same link name. This is particularly problematic when macros are applied across different modules or when conditional compilation is involved.
Third, conflicting declarations across different compilation units can trigger this error. If you have an extern function declared in multiple files without proper attribute isolation, the compiler detects the duplicate linkage names and halts compilation to prevent undefined behavior at link time.
The fundamental principle here is the One Definition Rule applied to FFI boundaries. Each symbol exposed through the FFI must have exactly one definition with a specific linkage name, and the Rust compiler enforces this constraint to ensure predictable behavior across all supported platforms.
3. Step-by-Step Fix
The solution to E0583 involves identifying and removing duplicate extern declarations while ensuring that each foreign function has exactly one unique linkage representation.
Before:
// lib.rs - Two conflicting extern declarations
extern "C" {
#[link_name = "process_data"]
fn process_data(input: *const u8, len: usize) -> i32;
}
mod processing {
use super::*;
extern "C" {
#[link_name = "process_data"]
fn process_data(input: *const u8, len: usize) -> i32;
}
pub fn wrapper(input: &[u8]) -> i32 {
// Re-declaring the same function creates the conflict
unsafe { process_data(input.as_ptr(), input.len()) }
}
}
After:
// lib.rs - Single, centralized extern block
extern "C" {
#[link_name = "process_data"]
fn process_data(input: *const u8, len: usize) -> i32;
}
// Re-export the function for use in other modules
pub use process_data;
// processing.rs - Clean module that uses the re-exported function
mod processing {
extern "C" {
// No duplicate declaration - use the re-export from parent scope
fn process_data(input: *const u8, len: usize) -> i32;
}
pub fn wrapper(input: &[u8]) -> i32 {
unsafe { process_data(input.as_ptr(), input.len()) }
}
}
When dealing with macros that generate duplicate declarations, you should add a guard to prevent multiple expansions:
Before:
macro_rules! declare_ffi {
($abi:expr) => {
extern $abi {
#[link_name = "initialize"]
fn initialize() -> i32;
}
};
}
// Multiple invocations cause the duplicate error
declare_ffi!("C");
declare_ffi!("C");
After:
// Use a static flag to prevent duplicate expansions
macro_rules! declare_ffi {
() => {
extern "C" {
#[link_name = "initialize"]
fn initialize() -> i32;
}
};
}
// Single invocation at module scope
declare_ffi!();
For complex projects with multiple crates providing overlapping FFI symbols, consolidate the extern declarations into a dedicated FFI wrapper crate:
Before:
// crate_a/src/lib.rs
extern "C" {
#[link_name = "shared_symbol"]
fn shared_symbol() -> i32;
}
// crate_b/src/lib.rs
extern "C" {
#[link_name = "shared_symbol"]
fn shared_symbol() -> i32;
}
After:
// crate_ffi/src/lib.rs - Dedicated FFI wrapper
extern "C" {
#[link_name = "shared_symbol"]
fn shared_symbol() -> i32;
}
pub use shared_symbol;
// crate_a/src/lib.rs
extern crate crate_ffi;
fn local_wrapper() -> i32 {
unsafe { crate_ffi::shared_symbol() }
}
4. Verification
After applying the fix, you should verify that the error has been resolved and that your FFI declarations maintain the correct behavior.
Run the Rust compiler to confirm E0583 no longer appears:
cargo build 2>&1 | grep -E "(error|E0583)"
A successful verification produces no output related to E0583 or other FFI linkage errors. The build should complete without warnings about duplicate linkage names.
Execute your test suite to ensure the FFI bindings function correctly:
cargo test
For projects with C or C++ dependencies, verify the symbol resolution by examining the compiled binary:
# On Linux/macOS
nm your_binary | grep process_data
# On Windows
dumpbin /SYMBOLS your_binary.exe | findstr process_data
The symbol should appear exactly once with the expected linkage name. You can also use the linker map file to confirm symbol uniqueness:
# Generate and inspect linker map on Linux
cargo build --release
cat target/release/*.map | grep -E "(process_data|FUNCTIONS)"
Run integration tests that exercise the FFI boundaries to catch any runtime issues that might stem from incorrect linkage. If your FFI functions interact with C libraries, ensure that all calling conventions and ABI specifications match between the Rust declarations and the native code implementations.
5. Common Pitfalls
Several frequent mistakes can lead to or fail to fully resolve E0583. Understanding these pitfalls helps you avoid introducing the error during development.
The most common mistake is using #[link_name] alongside #[no_mangle] without understanding their interaction. The #[no_mangle] attribute exposes a Rust function with its original name, while #[link_name] specifies how native code should reference an extern function. Using both on the same declaration creates confusion about which name takes precedence and can lead to subtle linking errors.
Another pitfall involves assuming that function overloading in C libraries can be replicated in Rust extern declarations. Rust does not support function overloading, so if a C library exports functions with the same name but different signatures, you must use distinct Rust function names with appropriate #[link_name] attributes pointing to the correct C symbols.
Copy-pasting extern blocks from documentation or other projects often introduces duplicate declarations when those blocks are merged into the same crate. Always audit your FFI code when combining sources and consolidate duplicate declarations into a single, well-organized extern block.
When using conditional compilation with #[cfg()], ensure that mutually exclusive configurations still produce unique linkage names. If two cfg-gated declarations resolve to the same link name depending on compile flags, you will encounter E0583 when both paths are active simultaneously.
Finally, be cautious with procedural macros that generate extern declarations. These macros should track which symbols have already been declared to prevent duplicate output. Testing macro-generated code with multiple inclusion scenarios catches such issues early in development.
6. Related Errors
Two related Rust compiler errors often appear alongside or instead of E0583 when working with FFI code.
E0560: Closure is provided inline occurs when you attempt to define a closure body within an extern block. This error signals a fundamental misunderstanding of FFI boundaries since extern blocks may only contain declarations, not implementations. The fix requires moving the function implementation to the native library and keeping only the declaration in the extern block.
E0261: Argument requires a size that is not known at compile time frequently accompanies FFI errors when passing slices or unsized types across the boundary. This error indicates that your type signatures do not account for the ABI requirements of foreign functions. You must either provide the size explicitly, use raw pointer types, or redesign the interface to use sized types that the compiler can reason about.
E0088: Invalid export attribute appears when #[link_name] is applied to a non-extern function or used incorrectly. The attribute is only valid for declarations within extern blocks, and the specified name must be a valid identifier in the target language’s calling convention. Understanding the valid contexts for each FFI attribute prevents this error and clarifies the distinction between Rust’s own symbol visibility and foreign symbol linkage.