include/io/channel.h

25 #include "qemu/coroutine-core.h"
28 #define TYPE_QIO_CHANNEL "qio-channel"
33 #define QIO_CHANNEL_ERR_BLOCK -2
62                                    gpointer data);
67  * The QIOChannel defines the core API for a generic I/O channel
71  *  - Use QOM to properly support arbitrary subclassing
72  *  - Support use of iovecs for efficient I/O with multiple blocks
73  *  - None of the character set translation, binary data exclusively
74  *  - Direct support for QEMU Error object reporting
75  *  - File descriptor passing
100  * must follow to provide specific channel implementations.
106  * must be thread-safe, terminate quickly and must not block.
173  * @ioc: the channel object
176  * Determine whether the channel implementation supports
186  * @ioc: the channel object
189  * Add channel support for the feature named in @feature.
196  * @ioc: the channel object
197  * @name: the name of the channel
199  * Sets the name of the channel, which serves as an aid
201  * watches for this channel.
208  * @ioc: the channel object
209  * @iov: the array of memory regions to read data into
214  * @errp: pointer to a NULL-initialized error object
216  * Read data from the IO channel, storing it in the
218  * in the @iov will be fully populated with data
223  * data. If the channel is in blocking mode, at least
224  * one byte of data will be read, but no more is
225  * guaranteed. If the channel is non-blocking and no
226  * data is available, it will return QIO_CHANNEL_ERR_BLOCK
228  * If the channel has passed any file descriptors,
237  * It is an error to pass a non-NULL @fds parameter
241  * Returns: the number of bytes read, or -1 on error,
242  * or QIO_CHANNEL_ERR_BLOCK if no data is available
243  * and the channel is non-blocking
256  * @ioc: the channel object
257  * @iov: the array of memory regions to write data from
262  * @errp: pointer to a NULL-initialized error object
264  * Write data to the IO channel, reading it from the
270  * It is not required for all @iov data to be fully
271  * sent. If the channel is in blocking mode, at least
272  * one byte of data will be sent, but no more is
273  * guaranteed. If the channel is non-blocking and no
274  * data can be sent, it will return QIO_CHANNEL_ERR_BLOCK
277  * array should be non-NULL and provide the handles.
279  * byte of data was sent.
281  * It is an error to pass a non-NULL @fds parameter
285  * Returns: the number of bytes sent, or -1 on error,
286  * or QIO_CHANNEL_ERR_BLOCK if no data is can be sent
287  * and the channel is non-blocking
299  * @ioc: the channel object
300  * @iov: the array of memory regions to read data into
302  * @errp: pointer to a NULL-initialized error object
304  * Read data from the IO channel, storing it in the
306  * in the @iov will be fully populated with data
310  * The function will wait for all requested data
314  * If end-of-file occurs before any data is read,
316  * before all requested data has been read, an error
319  * Returns: 1 if all bytes were read, 0 if end-of-file
320  *          occurs without data, or -1 on error
329  * @ioc: the channel object
330  * @iov: the array of memory regions to read data into
332  * @errp: pointer to a NULL-initialized error object
334  * Read data from the IO channel, storing it in the
336  * in the @iov will be fully populated with data
340  * The function will wait for all requested data
344  * If end-of-file occurs before all requested data
347  * Returns: 0 if all bytes were read, or -1 on error
357  * @ioc: the channel object
358  * @iov: the array of memory regions to write data from
360  * @errp: pointer to a NULL-initialized error object
362  * Write data to the IO channel, reading it from the
368  * The function will wait for all requested data
372  * Returns: 0 if all bytes were written, or -1 on error
381  * @ioc: the channel object
382  * @iov: the array of memory regions to read data into
384  * @errp: pointer to a NULL-initialized error object
396  * @ioc: the channel object
397  * @iov: the array of memory regions to write data from
399  * @errp: pointer to a NULL-initialized error object
411  * @ioc: the channel object
412  * @buf: the memory region to read data into
414  * @errp: pointer to a NULL-initialized error object
427  * @ioc: the channel object
428  * @buf: the memory regions to send data from
430  * @errp: pointer to a NULL-initialized error object
443  * @ioc: the channel object
444  * @buf: the memory region to read data into
446  * @errp: pointer to a NULL-initialized error object
449  * channel is non-blocking) yielding from the current coroutine
450  * multiple times until the entire content is read. If end-of-file
452  * data has been read it will return an error rather than a
453  * short-read. Otherwise behaves as qio_channel_read().
455  * Returns: 1 if all bytes were read, 0 if end-of-file occurs
456  *          without data, or -1 on error
465  * @ioc: the channel object
466  * @buf: the memory region to read data into
468  * @errp: pointer to a NULL-initialized error object
471  * channel is non-blocking) yielding from the current coroutine
472  * multiple times until the entire content is read. If end-of-file
473  * occurs it will return an error rather than a short-read. Otherwise
476  * Returns: 0 if all bytes were read, or -1 on error
485  * @ioc: the channel object
486  * @buf: the memory region to write data into
488  * @errp: pointer to a NULL-initialized error object
491  * channel is non-blocking) yielding from the current coroutine
495  * Returns: 0 if all bytes were written, or -1 on error
504  * @ioc: the channel object
506  * @errp: pointer to a NULL-initialized error object
508  * If @enabled is true, then the channel is put into
509  * blocking mode, otherwise it will be non-blocking.
511  * In non-blocking mode, read/write operations may
521  * @ioc: the channel object
536  * @ioc: the channel object
537  * @errp: pointer to a NULL-initialized error object
539  * Close the channel, flushing any pending I/O
541  * Returns: 0 on success, -1 on error
548  * @ioc: the channel object
549  * @iov: the array of memory regions to write data from
551  * @offset: offset in the channel where writes should begin
552  * @errp: pointer to a NULL-initialized error object
568  * @ioc: the channel object
569  * @buf: the memory region to write data into
571  * @offset: offset in the channel where writes should begin
572  * @errp: pointer to a NULL-initialized error object
584  * @ioc: the channel object
585  * @iov: the array of memory regions to read data into
587  * @offset: offset in the channel where writes should begin
588  * @errp: pointer to a NULL-initialized error object
604  * @ioc: the channel object
605  * @buf: the memory region to write data into
607  * @offset: offset in the channel where writes should begin
608  * @errp: pointer to a NULL-initialized error object
620  * @ioc: the channel object
622  * @errp: pointer to a NULL-initialized error object
624  * Shutdowns transmission and/or receiving of data
633  * This function is thread-safe, terminates quickly and does not block.
635  * Returns: 0 on success, -1 on error
643  * @ioc: the channel object
671  * @ioc: the channel object
675  * permitted to dispatch data that is written.
676  * If @enabled is true, then any data written will
697  * @ioc: the channel object
700  * @errp: pointer to a NULL-initialized error object
702  * Moves the current I/O position within the channel
706  * SEEK_SET - the position is set to @offset bytes
707  * SEEK_CUR - the position is moved by @offset bytes
708  * SEEK_END - the position is set to end of the file plus @offset bytes
713  * Returns: the new position on success, (off_t)-1 on failure
723  * @ioc: the channel object
739  * @ioc: the channel object
742  * @user_data: opaque data to pass to @func
768  * @ioc: the channel object
771  * @user_data: opaque data to pass to @func
789  * @ioc: the channel object
792  * @user_data: opaque data to pass to @func
813  * @ioc: the channel object
820  * and channel at the same time.
832  * @ioc: the channel object
834  * If qio_channel_yield() is currently waiting for the channel to become
842  * @ioc: the channel object
857  * @ioc: the channel object
865  * be used by channel implementations to forward the handlers
866  * to another channel (e.g. from #QIOChannelTLS to the
884  * @ioc: the channel object
885  * @iov: the array of memory regions to read data to
890  * @errp: pointer to a NULL-initialized error object
895  * over the channel. The function will wait for all
896  * requested data to be read, yielding from the current
897  * coroutine if required. data refers to both file
900  * Returns: 1 if all bytes were read, 0 if end-of-file
901  *          occurs without data, or -1 on error
913  * @ioc: the channel object
914  * @iov: the array of memory regions to read data to
918  * @errp: pointer to a NULL-initialized error object
923  * over the channel. The function will wait for all
924  * requested data to be read, yielding from the current
925  * coroutine if required. data refers to both file
928  * Returns: 0 if all bytes were read, or -1 on error
939  * @ioc: the channel object
940  * @iov: the array of memory regions to write data from
945  * @errp: pointer to a NULL-initialized error object
949  * to send all data passed (file handles and memory regions).
950  * The function will wait for all requested data
955  * instead of waiting for all requested data to be written,
962  * Returns: 0 if all bytes were written, or -1 on error
973  * @ioc: the channel object
974  * @errp: pointer to a NULL-initialized error object
980  * If not implemented, acts as a no-op, and returns 0.
982  * Returns -1 if any error is found,
992  * @ioc: the channel object
994  * @errp: pointer to a NULL-initialized error object
1001  * Return -1 on error with pid -1 for the non-Linux OS.