Skip to content

Commit 0a3e07d

Browse files
kennytmkennytm
authored
Rollup merge of rust-lang#46962 - clarcharr:os_raw_docs, r=QuietMisdreavus
Document std::os::raw. This adds a brief explanation to each type and its definition according to C. This also helps clarify that the definitions of the types, as described by rustdoc, are not necessarily the same from platform to platform.
2 parents ca7d839 + fefd5e9 commit 0a3e07d

15 files changed

+124
-5
lines changed

‎src/libstd/lib.rs

+1
Original file line numberDiff line numberDiff line change
@@ -260,6 +260,7 @@
260260
#![feature(core_intrinsics)]
261261
#![feature(dropck_eyepatch)]
262262
#![feature(exact_size_is_empty)]
263+
#![feature(external_doc)]
263264
#![feature(fs_read_write)]
264265
#![feature(fixed_size_array)]
265266
#![feature(float_from_str_radix)]

‎src/libstd/os/raw/char.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Equivalent to C's `char` type.
2+
3+
[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.
4+
5+
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.
6+
7+
[C's `char` type]: https://en.wikipedia.org/wiki/C_data_types#Basic_types
8+
[Rust's `char` type]: ../../primitive.char.html
9+
[`CStr`]: ../../ffi/struct.CStr.html
10+
[`i8`]: ../../primitive.i8.html
11+
[`u8`]: ../../primitive.u8.html

‎src/libstd/os/raw/double.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Equivalent to C's `double` type.
2+
3+
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.
4+
5+
[IEEE-754 double-precision float]: https://en.wikipedia.org/wiki/IEEE_754
6+
[`float`]: type.c_float.html
7+
[`f64`]: ../../primitive.f64.html

‎src/libstd/os/raw/float.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Equivalent to C's `float` type.
2+
3+
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.
4+
5+
[IEEE-754 single-precision float]: https://en.wikipedia.org/wiki/IEEE_754
6+
[`f32`]: ../../primitive.f32.html

‎src/libstd/os/raw/int.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Equivalent to C's `signed int` (`int`) type.
2+
3+
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.
4+
5+
[`short`]: type.c_short.html
6+
[`i32`]: ../../primitive.i32.html
7+
[`i16`]: ../../primitive.i16.html

‎src/libstd/os/raw/long.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Equivalent to C's `signed long` (`long`) type.
2+
3+
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`.
4+
5+
[`int`]: type.c_int.html
6+
[`i32`]: ../../primitive.i32.html
7+
[`i64`]: ../../primitive.i64.html

‎src/libstd/os/raw/longlong.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Equivalent to C's `signed long long` (`long long`) type.
2+
3+
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.
4+
5+
[`long`]: type.c_int.html
6+
[`i64`]: ../../primitive.i64.html
7+
[`i128`]: ../../primitive.i128.html

‎src/libstd/os/raw.rs renamed to ‎src/libstd/os/raw/mod.rs

+33-5
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,19 @@
88
// option. This file may not be copied, modified, or distributed
99
// except according to those terms.
1010

11-
//! Raw OS-specific types for the current platform/architecture
11+
//! Platform-specific types, as defined by C.
12+
//!
13+
//! Code that interacts via FFI will almost certainly be using the
14+
//! base types provided by C, which aren't nearly as nicely defined
15+
//! as Rust's primitive types. This module provides types which will
16+
//! match those defined by C, so that code that interacts with C will
17+
//! refer to the correct types.
1218
1319
#![stable(feature = "raw_os", since = "1.1.0")]
1420

1521
use fmt;
1622

23+
#[doc(include = "os/raw/char.md")]
1724
#[cfg(any(all(target_os = "linux", any(target_arch = "aarch64",
1825
target_arch = "arm",
1926
target_arch = "powerpc",
@@ -25,6 +32,7 @@ use fmt;
2532
all(target_os = "openbsd", target_arch = "aarch64"),
2633
all(target_os = "fuchsia", target_arch = "aarch64")))]
2734
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_char = u8;
35+
#[doc(include = "os/raw/char.md")]
2836
#[cfg(not(any(all(target_os = "linux", any(target_arch = "aarch64",
2937
target_arch = "arm",
3038
target_arch = "powerpc",
@@ -36,30 +44,50 @@ use fmt;
3644
all(target_os = "openbsd", target_arch = "aarch64"),
3745
all(target_os = "fuchsia", target_arch = "aarch64"))))]
3846
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_char = i8;
47+
#[doc(include = "os/raw/schar.md")]
3948
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_schar = i8;
49+
#[doc(include = "os/raw/uchar.md")]
4050
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_uchar = u8;
51+
#[doc(include = "os/raw/short.md")]
4152
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_short = i16;
53+
#[doc(include = "os/raw/ushort.md")]
4254
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_ushort = u16;
55+
#[doc(include = "os/raw/int.md")]
4356
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_int = i32;
57+
#[doc(include = "os/raw/uint.md")]
4458
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_uint = u32;
59+
#[doc(include = "os/raw/long.md")]
4560
#[cfg(any(target_pointer_width = "32", windows))]
4661
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_long = i32;
62+
#[doc(include = "os/raw/ulong.md")]
4763
#[cfg(any(target_pointer_width = "32", windows))]
4864
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulong = u32;
65+
#[doc(include = "os/raw/long.md")]
4966
#[cfg(all(target_pointer_width = "64", not(windows)))]
5067
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_long = i64;
68+
#[doc(include = "os/raw/ulong.md")]
5169
#[cfg(all(target_pointer_width = "64", not(windows)))]
5270
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulong = u64;
71+
#[doc(include = "os/raw/longlong.md")]
5372
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_longlong = i64;
73+
#[doc(include = "os/raw/ulonglong.md")]
5474
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulonglong = u64;
75+
#[doc(include = "os/raw/float.md")]
5576
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_float = f32;
77+
#[doc(include = "os/raw/double.md")]
5678
#[stable(feature = "raw_os", since = "1.1.0")] pub type c_double = f64;
5779

58-
/// Type used to construct void pointers for use with C.
80+
/// Equivalent to C's `void` type when used as a [pointer].
5981
///
60-
/// This type is only useful as a pointer target. Do not use it as a
61-
/// return type for FFI functions which have the `void` return type in
62-
/// C. Use the unit type `()` or omit the return type instead.
82+
/// In essence, `*const c_void` is equivalent to C's `const void*`
83+
/// and `*mut c_void` is equivalent to C's `void*`. That said, this is
84+
/// *not* the same as C's `void` return type, which is Rust's `()` type.
85+
///
86+
/// Ideally, this type would be equivalent to [`!`], but currently it may
87+
/// be more ideal to use `c_void` for FFI purposes.
88+
///
89+
/// [`!`]: ../../primitive.never.html
90+
/// [pointer]: ../../primitive.pointer.html
6391
// NB: For LLVM to recognize the void pointer type and by extension
6492
// functions like malloc(), we need to have it represented as i8* in
6593
// LLVM bitcode. The enum used here ensures this and prevents misuse

‎src/libstd/os/raw/schar.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Equivalent to C's `signed char` type.
2+
3+
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`].
4+
5+
[`char`]: type.c_char.html
6+
[`i8`]: ../../primitive.i8.html

‎src/libstd/os/raw/short.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Equivalent to C's `signed short` (`short`) type.
2+
3+
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.
4+
5+
[`char`]: type.c_char.html
6+
[`i16`]: ../../primitive.i16.html

‎src/libstd/os/raw/uchar.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Equivalent to C's `unsigned char` type.
2+
3+
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`].
4+
5+
[`char`]: type.c_char.html
6+
[`u8`]: ../../primitive.u8.html

‎src/libstd/os/raw/uint.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Equivalent to C's `unsigned int` type.
2+
3+
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.
4+
5+
[`int`]: type.c_int.html
6+
[`u32`]: ../../primitive.u32.html
7+
[`u16`]: ../../primitive.u16.html

‎src/libstd/os/raw/ulong.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Equivalent to C's `unsigned long` type.
2+
3+
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`.
4+
5+
[`long`]: type.c_long.html
6+
[`u32`]: ../../primitive.u32.html
7+
[`u64`]: ../../primitive.u64.html

‎src/libstd/os/raw/ulonglong.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Equivalent to C's `unsigned long long` type.
2+
3+
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.
4+
5+
[`long long`]: type.c_longlong.html
6+
[`u64`]: ../../primitive.u64.html
7+
[`u128`]: ../../primitive.u128.html

‎src/libstd/os/raw/ushort.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Equivalent to C's `unsigned short` type.
2+
3+
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`].
4+
5+
[`short`]: type.c_short.html
6+
[`u16`]: ../../primitive.u16.html

0 commit comments

Comments
 (0)