src/libstd/ffi/mod.rs

   1 //! Utilities related to FFI bindings.
   2 //!
   3 //! This module provides utilities to handle data across non-Rust
   4 //! interfaces, like other programming languages and the underlying
   5 //! operating system. It is mainly of use for FFI (Foreign Function
   6 //! Interface) bindings and code that needs to exchange C-like strings
   7 //! with other languages.
   8 //!
   9 //! # Overview
  10 //!
  11 //! Rust represents owned strings with the [`String`] type, and
  12 //! borrowed slices of strings with the [`str`] primitive. Both are
  13 //! always in UTF-8 encoding, and may contain nul bytes in the middle,
  14 //! i.e., if you look at the bytes that make up the string, there may
  15 //! be a `\0` among them. Both `String` and `str` store their length
  16 //! explicitly; there are no nul terminators at the end of strings
  17 //! like in C.
  18 //!
  19 //! C strings are different from Rust strings:
  20 //!
  21 //! * **Encodings** - Rust strings are UTF-8, but C strings may use
  22 //! other encodings. If you are using a string from C, you should
  23 //! check its encoding explicitly, rather than just assuming that it
  24 //! is UTF-8 like you can do in Rust.
  25 //!
  26 //! * **Character size** - C strings may use `char` or `wchar_t`-sized
  27 //! characters; please **note** that C's `char` is different from Rust's.
  28 //! The C standard leaves the actual sizes of those types open to
  29 //! interpretation, but defines different APIs for strings made up of
  30 //! each character type. Rust strings are always UTF-8, so different
  31 //! Unicode characters will be encoded in a variable number of bytes
  32 //! each. The Rust type [`char`] represents a '[Unicode scalar
  33 //! value]', which is similar to, but not the same as, a '[Unicode
  34 //! code point]'.
  35 //!
  36 //! * **Nul terminators and implicit string lengths** - Often, C
  37 //! strings are nul-terminated, i.e., they have a `\0` character at the
  38 //! end. The length of a string buffer is not stored, but has to be
  39 //! calculated; to compute the length of a string, C code must
  40 //! manually call a function like `strlen()` for `char`-based strings,
  41 //! or `wcslen()` for `wchar_t`-based ones. Those functions return
  42 //! the number of characters in the string excluding the nul
  43 //! terminator, so the buffer length is really `len+1` characters.
  44 //! Rust strings don't have a nul terminator; their length is always
  45 //! stored and does not need to be calculated. While in Rust
  46 //! accessing a string's length is a O(1) operation (because the
  47 //! length is stored); in C it is an O(length) operation because the
  48 //! length needs to be computed by scanning the string for the nul
  49 //! terminator.
  50 //!
  51 //! * **Internal nul characters** - When C strings have a nul
  52 //! terminator character, this usually means that they cannot have nul
  53 //! characters in the middle — a nul character would essentially
  54 //! truncate the string. Rust strings *can* have nul characters in
  55 //! the middle, because nul does not have to mark the end of the
  56 //! string in Rust.
  57 //!
  58 //! # Representations of non-Rust strings
  59 //!
  60 //! [`CString`] and [`CStr`] are useful when you need to transfer
  61 //! UTF-8 strings to and from languages with a C ABI, like Python.
  62 //!
  63 //! * **From Rust to C:** [`CString`] represents an owned, C-friendly
  64 //! string: it is nul-terminated, and has no internal nul characters.
  65 //! Rust code can create a [`CString`] out of a normal string (provided
  66 //! that the string doesn't have nul characters in the middle), and
  67 //! then use a variety of methods to obtain a raw `*mut `[`u8`] that can
  68 //! then be passed as an argument to functions which use the C
  69 //! conventions for strings.
  70 //!
  71 //! * **From C to Rust:** [`CStr`] represents a borrowed C string; it
  72 //! is what you would use to wrap a raw `*const `[`u8`] that you got from
  73 //! a C function. A [`CStr`] is guaranteed to be a nul-terminated array
  74 //! of bytes. Once you have a [`CStr`], you can convert it to a Rust
  75 //! [`&str`][`str`] if it's valid UTF-8, or lossily convert it by adding
  76 //! replacement characters.
  77 //!
  78 //! [`OsString`] and [`OsStr`] are useful when you need to transfer
  79 //! strings to and from the operating system itself, or when capturing
  80 //! the output of external commands. Conversions between [`OsString`],
  81 //! [`OsStr`] and Rust strings work similarly to those for [`CString`]
  82 //! and [`CStr`].
  83 //!
  84 //! * [`OsString`] represents an owned string in whatever
  85 //! representation the operating system prefers. In the Rust standard
  86 //! library, various APIs that transfer strings to/from the operating
  87 //! system use [`OsString`] instead of plain strings. For example,
  88 //! [`env::var_os()`] is used to query environment variables; it
  89 //! returns an [`Option`]`<`[`OsString`]`>`. If the environment variable
  90 //! exists you will get a [`Some`]`(os_string)`, which you can *then* try to
  91 //! convert to a Rust string. This yields a [`Result<>`], so that
  92 //! your code can detect errors in case the environment variable did
  93 //! not in fact contain valid Unicode data.
  94 //!
  95 //! * [`OsStr`] represents a borrowed reference to a string in a
  96 //! format that can be passed to the operating system. It can be
  97 //! converted into an UTF-8 Rust string slice in a similar way to
  98 //! [`OsString`].
  99 //!
 100 //! # Conversions
 101 //!
 102 //! ## On Unix
 103 //!
 104 //! On Unix, [`OsStr`] implements the
 105 //! `std::os::unix::ffi::`[`OsStrExt`][unix.OsStrExt] trait, which
 106 //! augments it with two methods, [`from_bytes`] and [`as_bytes`].
 107 //! These do inexpensive conversions from and to UTF-8 byte slices.
 108 //!
 109 //! Additionally, on Unix [`OsString`] implements the
 110 //! `std::os::unix::ffi::`[`OsStringExt`][unix.OsStringExt] trait,
 111 //! which provides [`from_vec`] and [`into_vec`] methods that consume
 112 //! their arguments, and take or produce vectors of [`u8`].
 113 //!
 114 //! ## On Windows
 115 //!
 116 //! On Windows, [`OsStr`] implements the
 117 //! `std::os::windows::ffi::`[`OsStrExt`][windows.OsStrExt] trait,
 118 //! which provides an [`encode_wide`] method. This provides an
 119 //! iterator that can be [`collect`]ed into a vector of [`u16`].
 120 //!
 121 //! Additionally, on Windows [`OsString`] implements the
 122 //! `std::os::windows:ffi::`[`OsStringExt`][windows.OsStringExt]
 123 //! trait, which provides a [`from_wide`] method. The result of this
 124 //! method is an [`OsString`] which can be round-tripped to a Windows
 125 //! string losslessly.
 126 //!
 127 //! [`String`]: ../string/struct.String.html
 128 //! [`str`]: ../primitive.str.html
 129 //! [`char`]: ../primitive.char.html
 130 //! [`u8`]: ../primitive.u8.html
 131 //! [`u16`]: ../primitive.u16.html
 132 //! [Unicode scalar value]: http://www.unicode.org/glossary/#unicode_scalar_value
 133 //! [Unicode code point]: http://www.unicode.org/glossary/#code_point
 134 //! [`CString`]: struct.CString.html
 135 //! [`CStr`]: struct.CStr.html
 136 //! [`OsString`]: struct.OsString.html
 137 //! [`OsStr`]: struct.OsStr.html
 138 //! [`env::set_var()`]: ../env/fn.set_var.html
 139 //! [`env::var_os()`]: ../env/fn.var_os.html
 140 //! [`Result<>`]: ../result/enum.Result.html
 141 //! [unix.OsStringExt]: ../os/unix/ffi/trait.OsStringExt.html
 142 //! [`from_vec`]: ../os/unix/ffi/trait.OsStringExt.html#tymethod.from_vec
 143 //! [`into_vec`]: ../os/unix/ffi/trait.OsStringExt.html#tymethod.into_vec
 144 //! [unix.OsStrExt]: ../os/unix/ffi/trait.OsStrExt.html
 145 //! [`from_bytes`]: ../os/unix/ffi/trait.OsStrExt.html#tymethod.from_bytes
 146 //! [`as_bytes`]: ../os/unix/ffi/trait.OsStrExt.html#tymethod.as_bytes
 147 //! [`OsStrExt`]: ../os/unix/ffi/trait.OsStrExt.html
 148 //! [windows.OsStrExt]: ../os/windows/ffi/trait.OsStrExt.html
 149 //! [`encode_wide`]: ../os/windows/ffi/trait.OsStrExt.html#tymethod.encode_wide
 150 //! [`collect`]: ../iter/trait.Iterator.html#method.collect
 151 //! [windows.OsStringExt]: ../os/windows/ffi/trait.OsStringExt.html
 152 //! [`from_wide`]: ../os/windows/ffi/trait.OsStringExt.html#tymethod.from_wide
 153 //! [`Option`]: ../option/enum.Option.html
 154 //! [`Some`]: ../option/enum.Option.html#variant.Some
 155
 156 #![stable(feature = "rust1", since = "1.0.0")]
 157
 158 #[stable(feature = "cstr_from_bytes", since = "1.10.0")]
 159 pub use self::c_str::FromBytesWithNulError;
 160 #[stable(feature = "rust1", since = "1.0.0")]
 161 pub use self::c_str::{CStr, CString, IntoStringError, NulError};
 162
 163 #[stable(feature = "rust1", since = "1.0.0")]
 164 pub use self::os_str::{OsStr, OsString};
 165
 166 #[stable(feature = "core_c_void", since = "1.30.0")]
 167 pub use core::ffi::c_void;
 168
 169 #[unstable(
 170     feature = "c_variadic",
 171     reason = "the `c_variadic` feature has not been properly tested on \
 172               all supported platforms",
 173     issue = "44930"
 174 )]
 175 pub use core::ffi::{VaList, VaListImpl};
 176
 177 mod c_str;
 178 mod os_str;