The only realization, which may have incoming fds is
qio_channel_socket_readv() (in io/channel-socket.c).
qio_channel_socket_readv() do call (through
qio_channel_socket_copy_fds()) qemu_socket_set_block() and
qemu_set_cloexec() for each fd.

Also, qio_channel_socket_copy_fds() is called at the end of
qio_channel_socket_readv(), on success path.

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
 include/io/channel.h | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/include/io/channel.h b/include/io/channel.h
index 12266256a8..c7f64506f7 100644
--- a/include/io/channel.h
+++ b/include/io/channel.h
@@ -118,6 +118,15 @@ struct QIOChannelClass {
                          size_t nfds,
                          int flags,
                          Error **errp);
+
+    /*
+     * The io_readv handler must guarantee that all
+     * incoming fds are set BLOCKING (unless
+     * QIO_CHANNEL_READ_FLAG_FD_PRESERVE_BLOCKING flag is set) and
+     * CLOEXEC (if available).
+     * @fds and @nfds are set only on success path, and untouched
+     * in case of errors.
+     */
     ssize_t (*io_readv)(QIOChannel *ioc,
                         const struct iovec *iov,
                         size_t niov,
@@ -125,6 +134,7 @@ struct QIOChannelClass {
                         size_t *nfds,
                         int flags,
                         Error **errp);
+
     int (*io_close)(QIOChannel *ioc,
                     Error **errp);
     GSource * (*io_create_watch)(QIOChannel *ioc,
@@ -235,6 +245,13 @@ void qio_channel_set_name(QIOChannel *ioc,
  * was allocated. It is the callers responsibility
  * to call close() on each file descriptor and to
  * call g_free() on the array pointer in @fds.
+ * @fds allocated and set (and @nfds is set too)
+ * _only_ on success path. These parameters are
+ * untouched in case of errors.
+ * qio_channel_readv_full() guarantees that all
+ * incoming fds are set BLOCKING (unless
+ * QIO_CHANNEL_READ_FLAG_FD_PRESERVE_BLOCKING flag
+ * is set) and CLOEXEC (if available).
  *
  * It is an error to pass a non-NULL @fds parameter
  * unless qio_channel_has_feature() returns a true
-- 
2.48.1

On Wed, Sep 10, 2025 at 10:31:12PM +0300, Vladimir Sementsov-Ogievskiy wrote:
> The only realization, which may have incoming fds is
> qio_channel_socket_readv() (in io/channel-socket.c).
> qio_channel_socket_readv() do call (through
> qio_channel_socket_copy_fds()) qemu_socket_set_block() and
> qemu_set_cloexec() for each fd.
> 
> Also, qio_channel_socket_copy_fds() is called at the end of
> qio_channel_socket_readv(), on success path.
> 
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
> ---
>  include/io/channel.h | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

On Wed, Sep 10, 2025 at 10:31:12PM +0300, Vladimir Sementsov-Ogievskiy wrote:
> The only realization, which may have incoming fds is
> qio_channel_socket_readv() (in io/channel-socket.c).
> qio_channel_socket_readv() do call (through
> qio_channel_socket_copy_fds()) qemu_socket_set_block() and
> qemu_set_cloexec() for each fd.
> 
> Also, qio_channel_socket_copy_fds() is called at the end of
> qio_channel_socket_readv(), on success path.
> 
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>

Maybe I'd just keep the io_readv() one, but drop the extra documents in
qio_channel_readv_full(), because that is almost a duplicate.

Meanwhile, we also have other higher level API that has the @fds
(qio_channel_readv_full_all_eof(), for example) that are not documented,
OTOH..

Totally no strong feelings.

Acked-by: Peter Xu <peterx@redhat.com>

> ---
>  include/io/channel.h | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
> 
> diff --git a/include/io/channel.h b/include/io/channel.h
> index 12266256a8..c7f64506f7 100644
> --- a/include/io/channel.h
> +++ b/include/io/channel.h
> @@ -118,6 +118,15 @@ struct QIOChannelClass {
>                           size_t nfds,
>                           int flags,
>                           Error **errp);
> +
> +    /*
> +     * The io_readv handler must guarantee that all
> +     * incoming fds are set BLOCKING (unless
> +     * QIO_CHANNEL_READ_FLAG_FD_PRESERVE_BLOCKING flag is set) and
> +     * CLOEXEC (if available).
> +     * @fds and @nfds are set only on success path, and untouched
> +     * in case of errors.
> +     */
>      ssize_t (*io_readv)(QIOChannel *ioc,
>                          const struct iovec *iov,
>                          size_t niov,
> @@ -125,6 +134,7 @@ struct QIOChannelClass {
>                          size_t *nfds,
>                          int flags,
>                          Error **errp);
> +
>      int (*io_close)(QIOChannel *ioc,
>                      Error **errp);
>      GSource * (*io_create_watch)(QIOChannel *ioc,
> @@ -235,6 +245,13 @@ void qio_channel_set_name(QIOChannel *ioc,
>   * was allocated. It is the callers responsibility
>   * to call close() on each file descriptor and to
>   * call g_free() on the array pointer in @fds.
> + * @fds allocated and set (and @nfds is set too)
> + * _only_ on success path. These parameters are
> + * untouched in case of errors.
> + * qio_channel_readv_full() guarantees that all
> + * incoming fds are set BLOCKING (unless
> + * QIO_CHANNEL_READ_FLAG_FD_PRESERVE_BLOCKING flag
> + * is set) and CLOEXEC (if available).
>   *
>   * It is an error to pass a non-NULL @fds parameter
>   * unless qio_channel_has_feature() returns a true
> -- 
> 2.48.1
> 

-- 
Peter Xu