include/io/channel.h

17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
25 #include "qemu/coroutine-core.h"
28 #define TYPE_QIO_CHANNEL "qio-channel"
33 #define QIO_CHANNEL_ERR_BLOCK -2
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
78  * will be subclasses for dealing with sockets, files, and higher
87     Coroutine *read_coroutine;
89     Coroutine *write_coroutine;
92     HANDLE event; /* For use with GSource on Win32 */
106  * must be thread-safe, terminate quickly and must not block.
212  * @nfds: pointer filled with number of elements in @fds on return
214  * @errp: pointer to a NULL-initialized error object
218  * in the @iov will be fully populated with data
222  * It is not required for all @iov to be filled with
225  * guaranteed. If the channel is non-blocking and no
230  * the elements filled with the received file
237  * It is an error to pass a non-NULL @fds parameter
241  * Returns: the number of bytes read, or -1 on error,
243  * and the channel is non-blocking
262  * @errp: pointer to a NULL-initialized error object
273  * guaranteed. If the channel is non-blocking and no
277  * array should be non-NULL and provide the handles.
281  * It is an error to pass a non-NULL @fds parameter
285  * Returns: the number of bytes sent, or -1 on error,
287  * and the channel is non-blocking
302  * @errp: pointer to a NULL-initialized error object
306  * in the @iov will be fully populated with data
311  * to be read, yielding from the current coroutine
314  * If end-of-file occurs before any data is read,
319  * Returns: 1 if all bytes were read, 0 if end-of-file
320  *          occurs without data, or -1 on error
332  * @errp: pointer to a NULL-initialized error object
336  * in the @iov will be fully populated with data
341  * to be read, yielding from the current coroutine
344  * If end-of-file occurs before all requested data
347  * Returns: 0 if all bytes were read, or -1 on error
360  * @errp: pointer to a NULL-initialized error object
369  * to be written, yielding from the current coroutine
372  * Returns: 0 if all bytes were written, or -1 on error
384  * @errp: pointer to a NULL-initialized error object
399  * @errp: pointer to a NULL-initialized error object
414  * @errp: pointer to a NULL-initialized error object
430  * @errp: pointer to a NULL-initialized error object
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
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
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
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
506  * @errp: pointer to a NULL-initialized error object
509  * blocking mode, otherwise it will be non-blocking.
511  * In non-blocking mode, read/write operations may
522  * @enabled: whether or not to follow the coroutine's AioContext
525  * coroutine's AioContext. Usually this is desirable.
530  * default for compatibility with code that is not aware of AioContexts.
537  * @errp: pointer to a NULL-initialized error object
541  * Returns: 0 on success, -1 on error
552  * @errp: pointer to a NULL-initialized error object
572  * @errp: pointer to a NULL-initialized error object
588  * @errp: pointer to a NULL-initialized error object
608  * @errp: pointer to a NULL-initialized error object
622  * @errp: pointer to a NULL-initialized error object
633  * This function is thread-safe, terminates quickly and does not block.
635  * Returns: 0 on success, -1 on error
651  * is false, writes are dispatched immediately with
700  * @errp: pointer to a NULL-initialized error object
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
753  * The returned source ID can be used with g_source_remove()
798  * instead of tag ID, with the GSource referenced already.
816  * Yields execution from the current coroutine until the condition
819  * addition, no two coroutine can be waiting on the same condition
822  * This must only be called from coroutine context. It is safe to
823  * reenter the coroutine externally while it is waiting; in this
890  * @errp: pointer to a NULL-initialized error object
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
918  * @errp: pointer to a NULL-initialized error object
925  * coroutine if required. data refers to both file
928  * Returns: 0 if all bytes were read, or -1 on error
945  * @errp: pointer to a NULL-initialized error object
951  * to be written, yielding from the current coroutine
962  * Returns: 0 if all bytes were written, or -1 on error
974  * @errp: pointer to a NULL-initialized error object
976  * Will block until every packet queued with
980  * If not implemented, acts as a no-op, and returns 0.
982  * Returns -1 if any error is found,
994  * @errp: pointer to a NULL-initialized error object
1001  * Return -1 on error with pid -1 for the non-Linux OS.