unixstring

UnixString is an FFI-friendly null-terminated byte string that may be constructed from a String, a CString, a PathBuf, an OsString or a collection of bytes.

An UnixString can then be converted into a slice of CStr, Path or OsStr in infallible and zero-cost operations.

Why?

UnixString aims to be useful in any scenario where you'd like to use FFI (specially with C) on Unix systems. If you have a PathBuf, for example, you can send that data to a libc function, such as stat, but you'd have to first allocate a CString (or something analogous) to do so.

The same is true with OsString and String because these three types are allowed to have internal zero bytes and are not null-terminated.

A UnixString is very close to what a CString is but with increased flexibility and usability. A CString cannot be changed or increased after instantited, while UnixString is growable through its push and push_bytes methods, somewhat similar to OsString.

A CString also does not have direct reference conversions to anything but &[u8] or &CStr, while UnixString has those and more (described below).

Obtaining references from an UnixString

Into	Function	Notes
`&CStr`	`UnixString::as_c_str`	Available through `AsRef` as well
`&Path`	`UnixString::as_path`	Available through `AsRef` as well
`&str`	`UnixString::as_str`	Fails if the bytes of the `UnixString` aren't valid UTF-8
`&[u8]`	`UnixString::as_bytes`	Returns the bytes of the `UnixString` without the null terminator
`&[u8]`	`UnixString::as_bytes_with_nul`	Returns the bytes of the `UnixString` with the null terminator
`&OsStr`	`UnixString::as_os_str`	Available through `AsRef` as well
`* const c_char`	`UnixString::as_ptr`

Creating an UnixString

From	Potential failure	Trait impl	Function
`CString`	Infallible	From	`UnixString::from_cstring`
`PathBuf`	Fails if contains an interior zero byte	TryFrom	`UnixString::from_pathbuf`
`String`	Fails if contains an interior zero byte	TryFrom	`UnixString::from_string`
`Vec`	Fails if contains an interior zero byte	TryFrom	`UnixString::from_bytes`
`OsString`	Fails if contains an interior zero byte	TryFrom	`UnixString::from_os_string`
`* const c_char`	Unsafe, see the docs for more info	None	`UnixString::from_ptr`

Converting from an UnixString

Into	Function	Notes
`CString`	`UnixString::into_cstring`
`PathBuf`	`UnixString::into_pathbuf`
`OsString`	`UnixString::into_os_string`
`String`	`UnixString::into_string`	Fails if the `UnixString`'s bytes are not valid UTF-8
`String`	`UnixString::into_string_lossy`
`String`	`UnixString::to_string_lossy`	Non-moving version of `UnixString::into_string_lossy`
`String`	`UnixString::into_string_unchecked`	Unsafe: creates a String without checking if the bytes are valid UTF-8
`Vec`	`UnixString::into_bytes`	Returns the bytes of the `UnixString` without the null terminator
`Vec`	`UnixString::into_bytes_with_nul`	Returns the bytes of the `UnixString` with the null terminator

All of the above are also available through .into().

Examples

Creating an UnixString with bytes received through FFI

use libc::{c_char, getcwd};
use unixstring::UnixString;

fn main() {
    const PATH_SIZ: usize = 1024;
    let mut buf: [c_char; 1024] = [0; 1024];

    let ptr = &mut buf as *mut c_char;

    unsafe { getcwd(ptr, PATH_SIZ) };

    if ptr.is_null() {
        panic!("getcwd failed");
    }

    let unix_string = unsafe { UnixString::from_ptr(ptr as *const c_char) };

    assert_eq!(unix_string.as_path(), std::env::current_dir().unwrap())
}

Using an UnixString to send bytes through FFI

use std::{convert::TryFrom, env};

use unixstring::UnixString;

fn stat(path: &UnixString) -> std::io::Result
    {
    
   // Safety: The all-zero byte-pattern is a valid `struct stat`
    
   let 
   mut stat_buf 
   = 
   unsafe { std
   ::mem
   ::
   zeroed() };

    
   if 
   -
   1 
   == 
   unsafe { libc
   ::
   lstat(path.
   as_ptr(), 
   &
   mut stat_buf) } {
        
   let io_err 
   = std
   ::io
   ::Error
   ::
   last_os_error();
        
   Err(io_err)
    } 
   else {
        
   Ok(stat_buf)
    }
}



   fn 
   main() -> std::io::
   Result<()>{
    
   for arg 
   in env
   ::
   args_os().
   map(UnixString
   ::try_from).
   flatten() {
        
   let stat 
   = 
   stat(
   &arg)?;
        
        
   let size 
   = stat.st_size;

        
   println!(
   "{} occupies {} bytes.", arg.
   as_path().
   display(), size);
    }

    
   Ok(())
}

You might also like...

fd is a program to find entries in your filesystem. It is a simple, fast and user-friendly alternative to find

fd is a program to find entries in your filesystem. It is a simple, fast and user-friendly alternative to find. While it does not aim to support all of find's powerful functionality, it provides sensible (opinionated) defaults for a majority of use cases.

25.9k Jan 9, 2023

Comments

Create std::fs::File from UnixString without allocating

When opening a std::fs::File in Rust on Linux right now, you give it an AsRef<Path>, which is turned into a CString, reallocating the string in the process (rust/library/std/src/sys/unix/fs.rs, function cstr()). There is no way to use safe rust and just the standard library to open a File without allocating a String on the heap. Even using this library to convert a UnixString into a Path to open a File, the standard library has no knowledge that the UnixString was nul terminated, so must reallocate.

It would be nice if this library (or one based on it) gave that capability. A File::open<P:AsRef<UnixStr>> that is guaranteed to not allocate in the success case; the error case might allocate an String to describe the error.

Also you may have noticed I included a signature with UnixStr. I think it makes sense to have separate UnixString and UnixStr (owned vs borrowed) just like the standard library has for String vs str, CString vs CStr, OsString vs OsStr, etc.

opened by maxbla 0