Skip to content
Tutorials Center
My learning

Topics

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.

Rust
use std::ffi::{CStr, CString};

let owned = CString::new("hello").unwrap();
let literal: &CStr = c"hello";

Try it

Rust CString, CStr and C string literals

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.

Rust Calling C and using OsString

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_ptr dangles if the CString is dropped. The famous bug is CString::new(s).unwrap().as_ptr(): the temporary dies at the end of the statement. Keep the CString in 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.
  • char is not c_char. Rust char is a 4-byte Unicode scalar; c_char is i8 or u8 depending 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_raw must be returned with from_raw, never freed by C's free; memory from malloc must be freed by free.
  • OsString is the right type for paths and arguments (env::args_os, Path::as_os_str). Converting with to_string_lossy replaces invalid sequences with U+FFFD.
  • std::os modules 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 plain rustc main.rs do not provide.