Rust Reference ยท Standard Library Modules
The std::ffi and std::os modules
Reference for Rust std::ffi and std::os: CString, CStr, OsString, OsStr, c_int and friends, C string literals, and calling C functions through extern blocks.
std::ffi holds the types Rust needs to talk to C code and to the operating system's own idea of text. There are two families. CString and CStr are nul-terminated byte strings for C APIs; OsString and OsStr represent names the OS gives you (file names, environment variables, arguments), which may not be valid UTF-8. The module also re-exports the C type aliases c_int, c_char, c_long, c_void and the rest, which match the platform's C ABI.
std::os is the home of platform-specific extensions: std::os::unix, std::os::windows, std::os::linux, std::os::fd and so on. They add extra methods through extension traits, for example OsStrExt::as_bytes on Unix. The old std::os::raw module is the same set of C aliases as std::ffi.
use std::ffi::{CStr, CString}; let owned = CString::new("hello").unwrap(); let literal: &CStr = c"hello";
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
| Item | Description |
|---|---|
CString |
Owned, nul-terminated, no interior nuls. new, as_ptr, into_raw, from_raw, as_bytes. |
CStr |
Borrowed counterpart. from_ptr (unsafe), from_bytes_with_nul, from_bytes_until_nul, to_str, to_string_lossy. |
c"text" |
C string literal of type &'static CStr. Stable since 1.77. |
OsString, OsStr |
Platform-native strings; convert with to_str or to_string_lossy. |
c_char, c_int, c_uint, c_long, c_double, c_void, ... |
C type aliases from std::ffi (stable at this path since 1.64). |
unsafe extern "C" { ... } |
Declares foreign functions. safe fn / unsafe fn mark each item (edition 2024, stable since 1.82). |
std::os::unix::ffi::{OsStrExt, OsStringExt} |
Unix: raw bytes of an OsStr. |
std::os::windows::ffi::{OsStrExt, OsStringExt} |
Windows: UTF-16 units (encode_wide). |
std::os::fd |
AsFd, OwnedFd, BorrowedFd, RawFd on Unix-like systems. |
Usage notes
CString::as_ptrdangles if theCStringis dropped. The famous bug isCString::new(s).unwrap().as_ptr(): the temporary dies at the end of the statement. Keep theCStringin a variable for as long as C uses the pointer.- Rust strings are not nul-terminated, and C strings may contain bytes that are not UTF-8. Always convert deliberately.
charis notc_char. Rustcharis a 4-byte Unicode scalar;c_charisi8oru8depending on the platform.- Foreign calls are unsafe unless declared
safe, because the compiler cannot check C's contracts: pointer validity, lifetimes, thread safety. - Ownership across the boundary: memory allocated by
into_rawmust be returned withfrom_raw, never freed by C'sfree; memory frommallocmust be freed byfree. OsStringis the right type for paths and arguments (env::args_os,Path::as_os_str). Converting withto_string_lossyreplaces invalid sequences with U+FFFD.std::osmodules compile only on their platform; wrap code in#[cfg(unix)]or#[cfg(windows)].- Struct layout: pass structs to C with
#[repr(C)]; Rust's default layout is unspecified. - Linking to a C library other than the system C runtime needs a
#[link]attribute and build configuration, which this runner and a plainrustc main.rsdo not provide.
Related
unsafe,extern, Raw pointers,std::env,std::path- Lessons: FFI, Unsafe Rust, Strings