[−][src]Module uapi::docs
Module containing the crate documentation
This crate provides safe wrappers for Unix APIs.
All wrappers are provided in the crate root. There are no wrapper types unless the raw types cannot be used safely and as noted below.
File Descriptors
This crate implements lifecycle management of file descriptors with two types:
OwnedFd
- An owned file descriptorFd
- Any kind of file descriptor
OwnedFd
is distinct from Fd
in that it assumes ownership of the contained file
descriptor. It implements Drop
and can be converted from and to many libstd types.
Both OwnedFd
and Fd
implement Read
and Write
, and Deref
to libc::c_int
.
APIs that return owned file descriptors return OwnedFd
. APIs that assume ownership
take OwnedFd
.
It's important to recognize that OwnedFd
is not about safety but about convenience.
An OwnedFd
can be created from any integer by calling OwnedFd::new
. An OwnedFd
can be unwrapped by calling OwnedFd::unwrap
.
Strings
This crate contains 3 string types:
&Bstr
- Any sequence of bytes&Ustr
- Any sequence of bytes with a terminating nul byteUstring
- Owned version of&Ustr
And several associated traits:
AsUstr
- Cheap conversion into&Ustr
Bytes
- Types with a binary representationIntoUstr
- Types that can be converted intoCov<'a, Ustr>
&Bstr
is a simple wrapper around &[u8]
which supports conversions from and to many
libstd string types:
&[u8]
&str
&Path
&OsStr
&CStr
&Bstr
supports Debug
and Display
. The implementations are the same as the ones
used for &Path
. To access the Display
implementation, call Bstr::display()
.
&Bstr
supports PartialEq
for many libstd types, &Ustr
, and Ustring
.
&Ustr
is like &Bstr
but guarantees that there is a nul byte after the last element
of the sequence. Unlike &CStr
, &Ustr
can contain inner nul bytes. &Ustr
derefs
to &Bstr
. Like &Bstr
, &Ustr
can be converted from and to many libstd types.
Ustring
is the owned version of &Ustr
. It supports conversion from and to many
owned libstd string types.
APIs that return strings usually return &CStr
. Since &CStr
is uncomfortable to
work with, AsUstr
provides the as_ustr
method on &CStr
.
APIs that accept strings usually accept impl IntoUstr
. IntoUstr
is implemented for
many libstd string types, &Bstr
, &Ustr
, and Ustring
. The implementations of
IntoUstr
perform least-cost conversions into &Ustr
. For example
fn f<'a>(s: impl IntoUstr<'a>) { let _ = s.into_ustr(); } f("abc"); // allocates f("abc\0"); // does not allocate f("abc".to_string()); // appends a nul byte to the `String` f(CStr::from_ptr(p)); // does not allocate
Pod & Packed
This crate contains two traits for conversions of data structures from and to bytes:
Pod
- Plain Old DataPacked
- Types without padding bytes
The central property of Pod
types is that they can be converted from bytes without
first having to validate the bytes. All C types are Pod
, though this crate only
implements Pod
for a selected number of types. More implementations might get added
in the future.
A Packed
type does not contain padding bytes. This means that they can be safely
converted into bytes because all bytes are guaranteed to be initialized.
These types are useful for working with APIs that transfer structures over byte-oriented APIs like cmsg, inotify, signalfd, etc.
The utilities to facilitate this are
pod_zeroed
- Returns an instance of aPod
type with all bytes zeroed.pod_read
- Reads an instance of aPacked
type as an instance of aPod
type.pod_iter
- Iterates over the instances of aPod
typed stored in an instance of aPacked
type.pod_read_init
- Reads an initial part of an instance of aPacked
type as an instance of aPod
type.pod_write
- Writes an instance of aPacked
type to an instance of aPod
type.as_bytes
- Returns the bytes of an instance of aPacked
type.
If a certain type does not implement Pod
or Packed
and you require it, you can
use assert_pod
or assert_packed
.
Control Messages (cmsg)
This crate provides safe functions for writing and reading control messages:
cmsg_write
- Writes a cmsg to a byte buffercmsg_read
- Reads a cmsg from a byte buffer