diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index a8049e676b3bb..642fa8775a479 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -260,6 +260,7 @@ #![feature(core_intrinsics)] #![feature(dropck_eyepatch)] #![feature(exact_size_is_empty)] +#![feature(external_doc)] #![feature(fs_read_write)] #![feature(fixed_size_array)] #![feature(float_from_str_radix)] diff --git a/src/libstd/os/raw/char.md b/src/libstd/os/raw/char.md new file mode 100644 index 0000000000000..9a55767d965a6 --- /dev/null +++ b/src/libstd/os/raw/char.md @@ -0,0 +1,11 @@ +Equivalent to C's `char` type. + +[C's `char` type] is completely unlike [Rust's `char` type]; while Rust's type represents a unicode scalar value, C's `char` type is just an ordinary integer. This type will always be either [`i8`] or [`u8`], as the type is defined as being one byte long. + +C chars are most commonly used to make C strings. Unlike Rust, where the length of a string is included alongside the string, C strings mark the end of a string with the character `'\0'`. See [`CStr`] for more information. + +[C's `char` type]: https://en.wikipedia.org/wiki/C_data_types#Basic_types +[Rust's `char` type]: ../../primitive.char.html +[`CStr`]: ../../ffi/struct.CStr.html +[`i8`]: ../../primitive.i8.html +[`u8`]: ../../primitive.u8.html diff --git a/src/libstd/os/raw/double.md b/src/libstd/os/raw/double.md new file mode 100644 index 0000000000000..6818dada31793 --- /dev/null +++ b/src/libstd/os/raw/double.md @@ -0,0 +1,7 @@ +Equivalent to C's `double` type. + +This type will almost always be [`f64`], which is guaranteed to be an [IEEE-754 double-precision float] in Rust. That said, the standard technically only guarantees that it be a floating-point number with at least the precision of a [`float`], and it may be `f32` or something entirely different from the IEEE-754 standard. + +[IEEE-754 double-precision float]: https://en.wikipedia.org/wiki/IEEE_754 +[`float`]: type.c_float.html +[`f64`]: ../../primitive.f64.html diff --git a/src/libstd/os/raw/float.md b/src/libstd/os/raw/float.md new file mode 100644 index 0000000000000..57d1071d0da17 --- /dev/null +++ b/src/libstd/os/raw/float.md @@ -0,0 +1,6 @@ +Equivalent to C's `float` type. + +This type will almost always be [`f32`], which is guaranteed to be an [IEEE-754 single-precision float] in Rust. That said, the standard technically only guarantees that it be a floating-point number, and it may have less precision than `f32` or not follow the IEEE-754 standard at all. + +[IEEE-754 single-precision float]: https://en.wikipedia.org/wiki/IEEE_754 +[`f32`]: ../../primitive.f32.html diff --git a/src/libstd/os/raw/int.md b/src/libstd/os/raw/int.md new file mode 100644 index 0000000000000..a0d25fd21d89f --- /dev/null +++ b/src/libstd/os/raw/int.md @@ -0,0 +1,7 @@ +Equivalent to C's `signed int` (`int`) type. + +This type will almost always be [`i32`], but may differ on some esoteric systems. The C standard technically only requires that this type be a signed integer that is at least the size of a [`short`]; some systems define it as an [`i16`], for example. + +[`short`]: type.c_short.html +[`i32`]: ../../primitive.i32.html +[`i16`]: ../../primitive.i16.html diff --git a/src/libstd/os/raw/long.md b/src/libstd/os/raw/long.md new file mode 100644 index 0000000000000..c620b402819fd --- /dev/null +++ b/src/libstd/os/raw/long.md @@ -0,0 +1,7 @@ +Equivalent to C's `signed long` (`long`) type. + +This type will always be [`i32`] or [`i64`]. Most notably, many Linux-based systems assume an `i64`, but Windows assumes `i32`. The C standard technically only requires that this type be a signed integer that is at least 32 bits and at least the size of an [`int`], although in practice, no system would have a `long` that is neither an `i32` nor `i64`. + +[`int`]: type.c_int.html +[`i32`]: ../../primitive.i32.html +[`i64`]: ../../primitive.i64.html diff --git a/src/libstd/os/raw/longlong.md b/src/libstd/os/raw/longlong.md new file mode 100644 index 0000000000000..ab3d6436568df --- /dev/null +++ b/src/libstd/os/raw/longlong.md @@ -0,0 +1,7 @@ +Equivalent to C's `signed long long` (`long long`) type. + +This type will almost always be [`i64`], but may differ on some systems. The C standard technically only requires that this type be a signed integer that is at least 64 bits and at least the size of a [`long`], although in practice, no system would have a `long long` that is not an `i64`, as most systems do not have a standardised [`i128`] type. + +[`long`]: type.c_int.html +[`i64`]: ../../primitive.i64.html +[`i128`]: ../../primitive.i128.html diff --git a/src/libstd/os/raw.rs b/src/libstd/os/raw/mod.rs similarity index 76% rename from src/libstd/os/raw.rs rename to src/libstd/os/raw/mod.rs index 279caf8053a85..d5eeb5252f0f1 100644 --- a/src/libstd/os/raw.rs +++ b/src/libstd/os/raw/mod.rs @@ -8,12 +8,19 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Raw OS-specific types for the current platform/architecture +//! Platform-specific types, as defined by C. +//! +//! Code that interacts via FFI will almost certainly be using the +//! base types provided by C, which aren't nearly as nicely defined +//! as Rust's primitive types. This module provides types which will +//! match those defined by C, so that code that interacts with C will +//! refer to the correct types. #![stable(feature = "raw_os", since = "1.1.0")] use fmt; +#[doc(include = "os/raw/char.md")] #[cfg(any(all(target_os = "linux", any(target_arch = "aarch64", target_arch = "arm", target_arch = "powerpc", @@ -25,6 +32,7 @@ use fmt; all(target_os = "openbsd", target_arch = "aarch64"), all(target_os = "fuchsia", target_arch = "aarch64")))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_char = u8; +#[doc(include = "os/raw/char.md")] #[cfg(not(any(all(target_os = "linux", any(target_arch = "aarch64", target_arch = "arm", target_arch = "powerpc", @@ -36,30 +44,50 @@ use fmt; all(target_os = "openbsd", target_arch = "aarch64"), all(target_os = "fuchsia", target_arch = "aarch64"))))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_char = i8; +#[doc(include = "os/raw/schar.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_schar = i8; +#[doc(include = "os/raw/uchar.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_uchar = u8; +#[doc(include = "os/raw/short.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_short = i16; +#[doc(include = "os/raw/ushort.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_ushort = u16; +#[doc(include = "os/raw/int.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_int = i32; +#[doc(include = "os/raw/uint.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_uint = u32; +#[doc(include = "os/raw/long.md")] #[cfg(any(target_pointer_width = "32", windows))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_long = i32; +#[doc(include = "os/raw/ulong.md")] #[cfg(any(target_pointer_width = "32", windows))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulong = u32; +#[doc(include = "os/raw/long.md")] #[cfg(all(target_pointer_width = "64", not(windows)))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_long = i64; +#[doc(include = "os/raw/ulong.md")] #[cfg(all(target_pointer_width = "64", not(windows)))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulong = u64; +#[doc(include = "os/raw/longlong.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_longlong = i64; +#[doc(include = "os/raw/ulonglong.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulonglong = u64; +#[doc(include = "os/raw/float.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_float = f32; +#[doc(include = "os/raw/double.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_double = f64; -/// Type used to construct void pointers for use with C. +/// Equivalent to C's `void` type when used as a [pointer]. /// -/// This type is only useful as a pointer target. Do not use it as a -/// return type for FFI functions which have the `void` return type in -/// C. Use the unit type `()` or omit the return type instead. +/// In essence, `*const c_void` is equivalent to C's `const void*` +/// and `*mut c_void` is equivalent to C's `void*`. That said, this is +/// *not* the same as C's `void` return type, which is Rust's `()` type. +/// +/// Ideally, this type would be equivalent to [`!`], but currently it may +/// be more ideal to use `c_void` for FFI purposes. +/// +/// [`!`]: ../../primitive.never.html +/// [pointer]: ../../primitive.pointer.html // NB: For LLVM to recognize the void pointer type and by extension // functions like malloc(), we need to have it represented as i8* in // LLVM bitcode. The enum used here ensures this and prevents misuse diff --git a/src/libstd/os/raw/schar.md b/src/libstd/os/raw/schar.md new file mode 100644 index 0000000000000..6aa8b1211d808 --- /dev/null +++ b/src/libstd/os/raw/schar.md @@ -0,0 +1,6 @@ +Equivalent to C's `signed char` type. + +This type will always be [`i8`], but is included for completeness. It is defined as being a signed integer the same size as a C [`char`]. + +[`char`]: type.c_char.html +[`i8`]: ../../primitive.i8.html diff --git a/src/libstd/os/raw/short.md b/src/libstd/os/raw/short.md new file mode 100644 index 0000000000000..be92c6c106d59 --- /dev/null +++ b/src/libstd/os/raw/short.md @@ -0,0 +1,6 @@ +Equivalent to C's `signed short` (`short`) type. + +This type will almost always be [`i16`], but may differ on some esoteric systems. The C standard technically only requires that this type be a signed integer with at least 16 bits; some systems may define it as `i32`, for example. + +[`char`]: type.c_char.html +[`i16`]: ../../primitive.i16.html diff --git a/src/libstd/os/raw/uchar.md b/src/libstd/os/raw/uchar.md new file mode 100644 index 0000000000000..b6ca711f86934 --- /dev/null +++ b/src/libstd/os/raw/uchar.md @@ -0,0 +1,6 @@ +Equivalent to C's `unsigned char` type. + +This type will always be [`u8`], but is included for completeness. It is defined as being an unsigned integer the same size as a C [`char`]. + +[`char`]: type.c_char.html +[`u8`]: ../../primitive.u8.html diff --git a/src/libstd/os/raw/uint.md b/src/libstd/os/raw/uint.md new file mode 100644 index 0000000000000..6f7013a8ac18d --- /dev/null +++ b/src/libstd/os/raw/uint.md @@ -0,0 +1,7 @@ +Equivalent to C's `unsigned int` type. + +This type will almost always be [`u32`], but may differ on some esoteric systems. The C standard technically only requires that this type be an unsigned integer with the same size as an [`int`]; some systems define it as a [`u16`], for example. + +[`int`]: type.c_int.html +[`u32`]: ../../primitive.u32.html +[`u16`]: ../../primitive.u16.html diff --git a/src/libstd/os/raw/ulong.md b/src/libstd/os/raw/ulong.md new file mode 100644 index 0000000000000..c350395080e80 --- /dev/null +++ b/src/libstd/os/raw/ulong.md @@ -0,0 +1,7 @@ +Equivalent to C's `unsigned long` type. + +This type will always be [`u32`] or [`u64`]. Most notably, many Linux-based systems assume an `u64`, but Windows assumes `u32`. The C standard technically only requires that this type be an unsigned integer with the size of a [`long`], although in practice, no system would have a `ulong` that is neither a `u32` nor `u64`. + +[`long`]: type.c_long.html +[`u32`]: ../../primitive.u32.html +[`u64`]: ../../primitive.u64.html diff --git a/src/libstd/os/raw/ulonglong.md b/src/libstd/os/raw/ulonglong.md new file mode 100644 index 0000000000000..c41faf74c5c68 --- /dev/null +++ b/src/libstd/os/raw/ulonglong.md @@ -0,0 +1,7 @@ +Equivalent to C's `unsigned long long` type. + +This type will almost always be [`u64`], but may differ on some systems. The C standard technically only requires that this type be an unsigned integer with the size of a [`long long`], although in practice, no system would have a `long long` that is not a `u64`, as most systems do not have a standardised [`u128`] type. + +[`long long`]: type.c_longlong.html +[`u64`]: ../../primitive.u64.html +[`u128`]: ../../primitive.u128.html diff --git a/src/libstd/os/raw/ushort.md b/src/libstd/os/raw/ushort.md new file mode 100644 index 0000000000000..d364abb3c8e0c --- /dev/null +++ b/src/libstd/os/raw/ushort.md @@ -0,0 +1,6 @@ +Equivalent to C's `unsigned short` type. + +This type will almost always be [`u16`], but may differ on some esoteric systems. The C standard technically only requires that this type be an unsigned integer with the same size as a [`short`]. + +[`short`]: type.c_short.html +[`u16`]: ../../primitive.u16.html