| // Licensed to the Apache Software Foundation (ASF) under one |
| // or more contributor license agreements. See the NOTICE file |
| // distributed with this work for additional information |
| // regarding copyright ownership. The ASF licenses this file |
| // to you under the Apache License, Version 2.0 (the |
| // "License"); you may not use this file except in compliance |
| // with the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, |
| // software distributed under the License is distributed on an |
| // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| // KIND, either express or implied. See the License for the |
| // specific language governing permissions and limitations |
| // under the License.. |
| |
| //! Raw Unix-like file descriptors. |
| |
| use crate::fs; |
| #[cfg(feature = "stdio")] |
| use crate::io; |
| use crate::os::raw; |
| use crate::os::unix::io::OwnedFd; |
| use crate::sys_common::{AsInner, IntoInner}; |
| |
| #[cfg(feature = "stdio")] |
| use sgx_oc as libc; |
| |
| /// Raw file descriptors. |
| pub type RawFd = raw::c_int; |
| |
| /// A trait to extract the raw file descriptor from an underlying object. |
| /// |
| /// This is only available on unix and WASI platforms and must be imported in |
| /// order to call the method. Windows platforms have a corresponding |
| /// `AsRawHandle` and `AsRawSocket` set of traits. |
| pub trait AsRawFd { |
| /// Extracts the raw file descriptor. |
| /// |
| /// This method does **not** pass ownership of the raw file descriptor |
| /// to the caller. The descriptor is only guaranteed to be valid while |
| /// the original object has not yet been destroyed. |
| /// |
| /// # Example |
| /// |
| /// ```no_run |
| /// use std::fs::File; |
| /// # use std::io; |
| /// #[cfg(unix)] |
| /// use std::os::unix::io::{AsRawFd, RawFd}; |
| /// #[cfg(target_os = "wasi")] |
| /// use std::os::wasi::io::{AsRawFd, RawFd}; |
| /// |
| /// let mut f = File::open("foo.txt")?; |
| /// // Note that `raw_fd` is only valid as long as `f` exists. |
| /// #[cfg(any(unix, target_os = "wasi"))] |
| /// let raw_fd: RawFd = f.as_raw_fd(); |
| /// # Ok::<(), io::Error>(()) |
| /// ``` |
| fn as_raw_fd(&self) -> RawFd; |
| } |
| |
| /// A trait to express the ability to construct an object from a raw file |
| /// descriptor. |
| pub trait FromRawFd { |
| /// Constructs a new instance of `Self` from the given raw file |
| /// descriptor. |
| /// |
| /// This function **consumes ownership** of the specified file |
| /// descriptor. The returned object will take responsibility for closing |
| /// it when the object goes out of scope. |
| /// |
| /// This function is also unsafe as the primitives currently returned |
| /// have the contract that they are the sole owner of the file |
| /// descriptor they are wrapping. Usage of this function could |
| /// accidentally allow violating this contract which can cause memory |
| /// unsafety in code that relies on it being true. |
| /// |
| /// # Example |
| /// |
| /// ```no_run |
| /// use std::fs::File; |
| /// # use std::io; |
| /// #[cfg(unix)] |
| /// use std::os::unix::io::{FromRawFd, IntoRawFd, RawFd}; |
| /// #[cfg(target_os = "wasi")] |
| /// use std::os::wasi::io::{FromRawFd, IntoRawFd, RawFd}; |
| /// |
| /// let f = File::open("foo.txt")?; |
| /// # #[cfg(any(unix, target_os = "wasi"))] |
| /// let raw_fd: RawFd = f.into_raw_fd(); |
| /// // SAFETY: no other functions should call `from_raw_fd`, so there |
| /// // is only one owner for the file descriptor. |
| /// # #[cfg(any(unix, target_os = "wasi"))] |
| /// let f = unsafe { File::from_raw_fd(raw_fd) }; |
| /// # Ok::<(), io::Error>(()) |
| /// ``` |
| unsafe fn from_raw_fd(fd: RawFd) -> Self; |
| } |
| |
| /// A trait to express the ability to consume an object and acquire ownership of |
| /// its raw file descriptor. |
| pub trait IntoRawFd { |
| /// Consumes this object, returning the raw underlying file descriptor. |
| /// |
| /// This function **transfers ownership** of the underlying file descriptor |
| /// to the caller. Callers are then the unique owners of the file descriptor |
| /// and must close the descriptor once it's no longer needed. |
| /// |
| /// # Example |
| /// |
| /// ```no_run |
| /// use std::fs::File; |
| /// # use std::io; |
| /// #[cfg(unix)] |
| /// use std::os::unix::io::{IntoRawFd, RawFd}; |
| /// #[cfg(target_os = "wasi")] |
| /// use std::os::wasi::io::{IntoRawFd, RawFd}; |
| /// |
| /// let f = File::open("foo.txt")?; |
| /// #[cfg(any(unix, target_os = "wasi"))] |
| /// let raw_fd: RawFd = f.into_raw_fd(); |
| /// # Ok::<(), io::Error>(()) |
| /// ``` |
| fn into_raw_fd(self) -> RawFd; |
| } |
| |
| impl AsRawFd for RawFd { |
| #[inline] |
| fn as_raw_fd(&self) -> RawFd { |
| *self |
| } |
| } |
| |
| impl IntoRawFd for RawFd { |
| #[inline] |
| fn into_raw_fd(self) -> RawFd { |
| self |
| } |
| } |
| |
| impl FromRawFd for RawFd { |
| #[inline] |
| unsafe fn from_raw_fd(fd: RawFd) -> RawFd { |
| fd |
| } |
| } |
| |
| impl AsRawFd for fs::File { |
| #[inline] |
| fn as_raw_fd(&self) -> RawFd { |
| self.as_inner().as_raw_fd() |
| } |
| } |
| |
| impl FromRawFd for fs::File { |
| #[inline] |
| unsafe fn from_raw_fd(fd: RawFd) -> fs::File { |
| unsafe { fs::File::from(OwnedFd::from_raw_fd(fd)) } |
| } |
| } |
| |
| impl IntoRawFd for fs::File { |
| #[inline] |
| fn into_raw_fd(self) -> RawFd { |
| self.into_inner().into_inner().into_raw_fd() |
| } |
| } |
| |
| #[cfg(feature = "stdio")] |
| impl AsRawFd for io::Stdin { |
| #[inline] |
| fn as_raw_fd(&self) -> RawFd { |
| libc::STDIN_FILENO |
| } |
| } |
| |
| #[cfg(feature = "stdio")] |
| impl AsRawFd for io::Stdout { |
| #[inline] |
| fn as_raw_fd(&self) -> RawFd { |
| libc::STDOUT_FILENO |
| } |
| } |
| |
| #[cfg(feature = "stdio")] |
| impl AsRawFd for io::Stderr { |
| #[inline] |
| fn as_raw_fd(&self) -> RawFd { |
| libc::STDERR_FILENO |
| } |
| } |
| |
| #[cfg(feature = "stdio")] |
| impl<'a> AsRawFd for io::StdinLock<'a> { |
| #[inline] |
| fn as_raw_fd(&self) -> RawFd { |
| libc::STDIN_FILENO |
| } |
| } |
| |
| #[cfg(feature = "stdio")] |
| impl<'a> AsRawFd for io::StdoutLock<'a> { |
| #[inline] |
| fn as_raw_fd(&self) -> RawFd { |
| libc::STDOUT_FILENO |
| } |
| } |
| |
| #[cfg(feature = "stdio")] |
| impl<'a> AsRawFd for io::StderrLock<'a> { |
| #[inline] |
| fn as_raw_fd(&self) -> RawFd { |
| libc::STDERR_FILENO |
| } |
| } |