2 releases

0.1.1 Nov 26, 2020
0.1.0 Nov 26, 2020

#453 in Embedded development

Download history 194/week @ 2024-06-19 217/week @ 2024-06-26 266/week @ 2024-07-03 331/week @ 2024-07-10 395/week @ 2024-07-17 378/week @ 2024-07-24 365/week @ 2024-07-31 387/week @ 2024-08-07 341/week @ 2024-08-14 448/week @ 2024-08-21 314/week @ 2024-08-28 413/week @ 2024-09-04 516/week @ 2024-09-11 648/week @ 2024-09-18 514/week @ 2024-09-25 590/week @ 2024-10-02

2,379 downloads per month
Used in 12 crates (5 directly)

MIT/Apache

53KB
982 lines

printf-compat

Crates.io Docs.rs

printf reimplemented in Rust

This is a complete reimplementation of printf in Rust, using the unstable (i.e. requires a Nightly compiler) c_variadic feature.

  • Many C libraries provide a way to provide a custom log callback. With this crate, you can provide a pure Rust option, and do whatever you want with it. Log it to the console, store it in a string, or do anything else.
  • If you're writing a Rust-first program for a microcontroller and need to interface with a C library, you might not have a libc and have to reimplement it yourself. If it uses printf, use this crate to easily add your own output. core::fmt too big? No problem! Write your own formatting code, or use a minimal formatting library like ufmt or defmt. Don't need every single option given by printf format strings? No problem! Just don't implement it.
  • Likewise, if you're using wasm32-unknown-unknown instead of emscripten (as wasm-bindgen is only compatible with the former), you have no libc. If you want to interface with a C library, you'll have to do it all yourself. With this crate, that turns into 5 lines instead of hundreds for printf.

Benefits

⚒ Modular

printf-compat lets you pick how you want to output a message. Use pre-written adapters for fmt::Write (like a String) or io::Write (like io::stdout()), or implement your own.

🔬 Small

This crate is no_std compatible (printf-compat = { version = "0.1", default-features = false } in your Cargo.toml). The main machinery doesn't require the use of core::fmt, and it can't panic.

🔒 Safe (as can be)

Of course, printf is completely unsafe, as it requires the use of va_list. However, outside of that, all of the actual string parsing is written in completely safe Rust. No buffer overflow attacks!

The n format specifier, which writes to a user-provided pointer, is considered a serious security vulnerability if a user-provided string is ever passed to printf. It is supported by this crate; however, it doesn't do anything by default, and you'll have to explicitly do the writing yourself.

🧹 Tested

A wide test suite is used to ensure that many different possibilities are identical to glibc's printf. Differences are documented.

Getting Started

Start by adding the unstable feature:

#![feature(c_variadic)]

Now, add your function signature:

use cty::{c_char, c_int};

#[no_mangle]
unsafe extern "C" fn c_library_print(str: *const c_char, mut args: ...) -> c_int {
    todo!()
}

If you have access to std, i.e. not an embedded platform, you can use std::os::raw instead of cty. Also, think about what you're doing:

  • If you're implenting printf because you don't have one, you'll want to call it printf and add #[no_mangle].
  • Likewise, if you're creating a custom log function for a C library and it expects to call a globally-defined function, keep #[no_mangle] and rename the function to what it expects.
  • On the other hand, if your C library expects you to call a function to register a callback (example 1, example 2), remove #[no_mangle].

Now, add your logic:

use printf_compat::{format, output};
let mut s = String::new();
let bytes_written = format(str, args.as_va_list(), output::fmt_write(&mut s));
println!("{}", s);
bytes_written

Of course, replace output::fmt_write with whatever you like—some are provided for you in output. If you'd like to write your own, follow their function signature: you need to provide a function to format() that takes an Argument and returns the number of bytes written (although you don't need to if your C library doesn't use it) or -1 if there was an error.

License: MIT OR Apache-2.0

Dependencies

~1MB
~16K SLoC