1.0.0[][src]Module std::ffi

Utilities related to FFI bindings.

This module provides utilities to handle data across non-Rust interfaces, like other programming languages and the underlying operating system. It is mainly of use for FFI (Foreign Function Interface) bindings and code that needs to exchange C-like strings with other languages.

Overview

Rust represents owned strings with the String type, and borrowed slices of strings with the str primitive. Both are always in UTF-8 encoding, and may contain nul bytes in the middle, i.e., if you look at the bytes that make up the string, there may be a \0 among them. Both String and str store their length explicitly; there are no nul terminators at the end of strings like in C.

C strings are different from Rust strings:

Representations of non-Rust strings

CString and CStr are useful when you need to transfer UTF-8 strings to and from languages with a C ABI, like Python.

OsString and OsStr are useful when you need to transfer strings to and from the operating system itself, or when capturing the output of external commands. Conversions between OsString, OsStr and Rust strings work similarly to those for CString and CStr.

Conversions

On Unix

On Unix, OsStr implements the std::os::unix::ffi::OsStrExt trait, which augments it with two methods, from_bytes and as_bytes. These do inexpensive conversions from and to UTF-8 byte slices.

Additionally, on Unix OsString implements the std::os::unix::ffi::OsStringExt trait, which provides from_vec and into_vec methods that consume their arguments, and take or produce vectors of u8.

On Windows

On Windows, OsStr implements the std::os::windows::ffi::OsStrExt trait, which provides an encode_wide method. This provides an iterator that can be collected into a vector of u16.

Additionally, on Windows OsString implements the std::os::windows:ffi::OsStringExt trait, which provides a from_wide method. The result of this method is an OsString which can be round-tripped to a Windows string losslessly.

Structs

CStr

Representation of a borrowed C string.

CString

A type representing an owned, C-compatible, nul-terminated string with no nul bytes in the middle.

FromBytesWithNulError

An error indicating that a nul byte was not in the expected position.

IntoStringError

An error indicating invalid UTF-8 when converting a CString into a String.

NulError

An error indicating that an interior nul byte was found.

OsStr

Borrowed reference to an OS string (see OsString).

OsString

A type that can represent owned, mutable platform-native strings, but is cheaply inter-convertible with Rust strings.

VaListExperimental

A wrapper for a va_list

VaListImplExperimental

Basic implementation of a va_list.

Enums

c_void

Equivalent to C's void type when used as a pointer.