Re: [PATCH v4 2/2] io/channel: document how qio_channel_readv_full() handles fds

[Peter Xu <peterx@redhat.com>]

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