From eeea5c23b494782bf6a864005684d3405f5c062b Mon Sep 17 00:00:00 2001
From: LinkTed <LinkTed@users.noreply.github.com>
Date: Sat, 12 Sep 2020 15:37:02 +0200
Subject: [PATCH] Change API to unsafe and add doc comments

---
 library/std/src/sys/unix/ext/net/ancillary.rs | 23 ++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/library/std/src/sys/unix/ext/net/ancillary.rs b/library/std/src/sys/unix/ext/net/ancillary.rs
index bfca7ae4a9b8..d41984a532b6 100644
--- a/library/std/src/sys/unix/ext/net/ancillary.rs
+++ b/library/std/src/sys/unix/ext/net/ancillary.rs
@@ -137,7 +137,12 @@ struct AncillaryDataIter<'a, T> {
 }
 
 impl<'a, T> AncillaryDataIter<'a, T> {
-    pub fn new(data: &'a [u8]) -> AncillaryDataIter<'a, T> {
+    /// Create `AncillaryDataIter` struct to iterate through the data unit in the control message.
+    ///
+    /// # Safety
+    ///
+    /// `data` must contain a valid control message.
+    unsafe fn new(data: &'a [u8]) -> AncillaryDataIter<'a, T> {
         AncillaryDataIter { data, phantom: PhantomData }
     }
 }
@@ -325,12 +330,24 @@ pub enum AncillaryData<'a> {
 }
 
 impl<'a> AncillaryData<'a> {
-    fn as_rights(data: &'a [u8]) -> Self {
+    /// Create a `AncillaryData::ScmRights` variant.
+    ///
+    /// # Safety
+    ///
+    /// `data` must contain a valid control message and the control message must be type of
+    /// `SOL_SOCKET` and level of `SCM_RIGHTS`.
+    unsafe fn as_rights(data: &'a [u8]) -> Self {
         let ancillary_data_iter = AncillaryDataIter::new(data);
         let scm_rights = ScmRights(ancillary_data_iter);
         AncillaryData::ScmRights(scm_rights)
     }
 
+    /// Create a `AncillaryData::ScmCredentials` variant.
+    ///
+    /// # Safety
+    ///
+    /// `data` must contain a valid control message and the control message must be type of
+    /// `SOL_SOCKET` and level of `SCM_CREDENTIALS` or `SCM_CREDENTIALS`.
     #[cfg(any(
         doc,
         target_os = "android",
@@ -345,7 +362,7 @@ impl<'a> AncillaryData<'a> {
         target_os = "openbsd",
         target_env = "uclibc",
     ))]
-    fn as_credentials(data: &'a [u8]) -> Self {
+    unsafe fn as_credentials(data: &'a [u8]) -> Self {
         let ancillary_data_iter = AncillaryDataIter::new(data);
         let scm_credentials = ScmCredentials(ancillary_data_iter);
         AncillaryData::ScmCredentials(scm_credentials)