gio/

unix_fd_list.rs

// Take a look at the license at the top of the repository in the LICENSE file.

#[cfg(unix)]
use std::os::unix::io::{AsFd, AsRawFd, FromRawFd, IntoRawFd, OwnedFd, RawFd};
use std::{mem, ptr};

use glib::{prelude::*, translate::*};
#[cfg(all(not(unix), docsrs))]
use socket::{AsFd, AsRawFd, FromRawFd, IntoRawFd, OwnedFd, RawFd};

use crate::{UnixFDList, ffi};

impl UnixFDList {
    /// Creates a new [`UnixFDList`][crate::UnixFDList] containing the file descriptors given
    /// in @fds. The file descriptors become the property of the new list and may no
    /// longer be used by the caller. The array itself is owned by the caller.
    ///
    /// Each file descriptor in the array should be set to close-on-exec.
    ///
    /// If @n_fds is -1 then @fds must be terminated with -1.
    /// ## `fds`
    /// the initial list of file descriptors
    ///
    /// # Returns
    ///
    /// a new [`UnixFDList`][crate::UnixFDList]
    #[doc(alias = "g_unix_fd_list_new_from_array")]
    pub fn from_array(fds: impl IntoIterator<Item = impl IntoRawFd>) -> UnixFDList {
        let fds = fds.into_iter().map(|t| t.into_raw_fd()).collect::<Vec<_>>();
        unsafe {
            from_glib_full(ffi::g_unix_fd_list_new_from_array(
                fds.to_glib_none().0,
                fds.len() as i32,
            ))
        }
    }
}

pub trait UnixFDListExtManual: IsA<UnixFDList> + Sized {
    /// Adds a file descriptor to @self.
    ///
    /// The file descriptor is duplicated using `dup()`. You keep your copy
    /// of the descriptor and the copy contained in @self will be closed
    /// when @self is finalized.
    ///
    /// A possible cause of failure is exceeding the per-process or
    /// system-wide file descriptor limit.
    ///
    /// The index of the file descriptor in the list is returned.  If you use
    /// this index with [`UnixFDListExtManual::get()`][crate::prelude::UnixFDListExtManual::get()] then you will receive back a
    /// duplicated copy of the same file descriptor.
    /// ## `fd`
    /// a valid open file descriptor
    ///
    /// # Returns
    ///
    /// the index of the appended fd in case of success, else `-1`
    ///          (and @error is set)
    #[doc(alias = "g_unix_fd_list_append")]
    fn append(&self, fd: impl AsFd) -> Result<i32, glib::Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let ret = ffi::g_unix_fd_list_append(
                self.as_ref().to_glib_none().0,
                fd.as_fd().as_raw_fd(),
                &mut error,
            );
            if error.is_null() {
                Ok(ret)
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Gets a file descriptor out of @self.
    ///
    /// @index_ specifies the index of the file descriptor to get.  It is a
    /// programmer error for @index_ to be out of range. Either use
    /// [`UnixFDListExtManual::lookup()`][crate::prelude::UnixFDListExtManual::lookup()] to do a checked lookup, or check the index
    /// against the list length using [`UnixFDListExt::length()`][crate::prelude::UnixFDListExt::length()].
    ///
    /// The file descriptor is duplicated using `dup()` and set as
    /// close-on-exec before being returned.  You must call `close()` on it
    /// when you are done.
    ///
    /// A possible cause of failure is exceeding the per-process or
    /// system-wide file descriptor limit.
    /// ## `index_`
    /// the index into the list
    ///
    /// # Returns
    ///
    /// the file descriptor, or `-1` in case of error
    #[doc(alias = "g_unix_fd_list_get")]
    fn get(&self, index_: i32) -> Result<OwnedFd, glib::Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let raw_fd =
                ffi::g_unix_fd_list_get(self.as_ref().to_glib_none().0, index_, &mut error);
            if error.is_null() {
                let fd = OwnedFd::from_raw_fd(raw_fd);
                Ok(fd)
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the array of file descriptors that is contained in this
    /// object.
    ///
    /// After this call, the descriptors remain the property of @self.  The
    /// caller must not close them and must not free the array.  The array is
    /// valid only until @self is changed in any way.
    ///
    /// If @length is non-`NULL` then it is set to the number of file
    /// descriptors in the returned array. The returned array is also
    /// terminated with `-1`.
    ///
    /// This function never returns `NULL`. In case there are no file
    /// descriptors contained in @self, an empty array is returned.
    ///
    /// # Returns
    ///
    /// an array of file
    ///     descriptors
    #[doc(alias = "g_unix_fd_list_peek_fds")]
    fn peek_fds(&self) -> Vec<RawFd> {
        unsafe {
            let mut length = mem::MaybeUninit::uninit();

            FromGlibContainer::from_glib_none_num(
                ffi::g_unix_fd_list_peek_fds(self.as_ref().to_glib_none().0, length.as_mut_ptr()),
                length.assume_init() as usize,
            )
        }
    }

    /// Returns the array of file descriptors that is contained in this
    /// object.
    ///
    /// After this call, the descriptors are no longer contained in
    /// @self. Further calls will return an empty list (unless more
    /// descriptors have been added).
    ///
    /// The return result of this function must be freed with `g_free()`.
    /// The caller is also responsible for closing all of the file
    /// descriptors.  The file descriptors in the array are set to
    /// close-on-exec.
    ///
    /// If @length is non-`NULL` then it is set to the number of file
    /// descriptors in the returned array. The returned array is also
    /// terminated with `-1`.
    ///
    /// This function never returns `NULL`. In case there are no file
    /// descriptors contained in @self, an empty array is returned.
    ///
    /// # Returns
    ///
    /// an array of file
    ///     descriptors
    #[doc(alias = "g_unix_fd_list_steal_fds")]
    fn steal_fds(&self) -> Vec<RawFd> {
        unsafe {
            let mut length = mem::MaybeUninit::uninit();

            FromGlibContainer::from_glib_full_num(
                ffi::g_unix_fd_list_steal_fds(self.as_ref().to_glib_none().0, length.as_mut_ptr()),
                length.assume_init() as usize,
            )
        }
    }

    /// Adds a file descriptor to @self.
    ///
    /// After this call, @fd belongs to the @self and may no longer be closed by the
    /// caller.
    ///
    /// The file descriptor @fd should be set to close-on-exec.
    ///
    /// The index of the file descriptor in the list is returned. If you use this
    /// index with [`UnixFDListExtManual::get()`][crate::prelude::UnixFDListExtManual::get()] then you will receive back a
    /// duplicated copy of the same file descriptor.
    /// ## `fd`
    /// a valid open file descriptor
    ///
    /// # Returns
    ///
    /// the index of the appended @fd
    #[cfg(feature = "v2_90")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_90")))]
    #[doc(alias = "g_unix_fd_list_append_take")]
    fn append_take(&self, fd: impl IntoRawFd) -> usize {
        unsafe { ffi::g_unix_fd_list_append_take(self.as_ref().to_glib_none().0, fd.into_raw_fd()) }
    }

    /// Looks up a file descriptor in @self at position @index_.
    ///
    /// @index_ specifies the index of the file descriptor to get. If no file
    /// descriptor exists at this index, `-1` is returned.
    ///
    /// After this call, the descriptor remains the property of @self. The caller
    /// must not close it. The descriptor is valid only until @self is changed in any
    /// way.
    /// ## `index_`
    /// the file descriptor index
    ///
    /// # Returns
    ///
    /// the file descriptor, or `-1` if not found
    #[cfg(feature = "v2_90")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_90")))]
    #[doc(alias = "g_unix_fd_list_lookup")]
    fn lookup(&self, index_: usize) -> RawFd {
        unsafe { ffi::g_unix_fd_list_lookup(self.as_ref().to_glib_none().0, index_) }
    }

    /// Gets a file descriptor out of @self.
    ///
    /// @index_ specifies the index of the file descriptor to get. It is a programmer
    /// error for @index_ to be out of range; see [`UnixFDListExt::length()`][crate::prelude::UnixFDListExt::length()].
    ///
    /// This will always return a valid (non-negative) file descriptor.
    ///
    /// After this call, the descriptor remains the property of @self. The caller
    /// must not close it. The descriptor is valid only until @self is changed in any
    /// way.
    /// ## `index_`
    /// the index into the list
    ///
    /// # Returns
    ///
    /// the file descriptor
    #[cfg(feature = "v2_90")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_90")))]
    #[doc(alias = "g_unix_fd_list_peek")]
    fn peek(&self, index_: usize) -> RawFd {
        unsafe { ffi::g_unix_fd_list_peek(self.as_ref().to_glib_none().0, index_) }
    }
}

impl<O: IsA<UnixFDList>> UnixFDListExtManual for O {}