1 /* 2 * QEMU I/O channels 3 * 4 * Copyright (c) 2015 Red Hat, Inc. 5 * 6 * This library is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2.1 of the License, or (at your option) any later version. 10 * 11 * This library is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with this library; if not, see <http://www.gnu.org/licenses/>. 18 * 19 */ 20 21 #ifndef QIO_CHANNEL_H 22 #define QIO_CHANNEL_H 23 24 #include "qom/object.h" 25 #include "qemu/coroutine-core.h" 26 #include "block/aio.h" 27 28 #define TYPE_QIO_CHANNEL "qio-channel" 29 OBJECT_DECLARE_TYPE(QIOChannel, QIOChannelClass, 30 QIO_CHANNEL) 31 32 33 #define QIO_CHANNEL_ERR_BLOCK -2 34 35 #define QIO_CHANNEL_WRITE_FLAG_ZERO_COPY 0x1 36 37 #define QIO_CHANNEL_READ_FLAG_MSG_PEEK 0x1 38 #define QIO_CHANNEL_READ_FLAG_RELAXED_EOF 0x2 39 40 typedef enum QIOChannelFeature QIOChannelFeature; 41 42 enum QIOChannelFeature { 43 QIO_CHANNEL_FEATURE_FD_PASS, 44 QIO_CHANNEL_FEATURE_SHUTDOWN, 45 QIO_CHANNEL_FEATURE_LISTEN, 46 QIO_CHANNEL_FEATURE_WRITE_ZERO_COPY, 47 QIO_CHANNEL_FEATURE_READ_MSG_PEEK, 48 QIO_CHANNEL_FEATURE_SEEKABLE, 49 QIO_CHANNEL_FEATURE_CONCURRENT_IO, 50 }; 51 52 53 typedef enum QIOChannelShutdown QIOChannelShutdown; 54 55 enum QIOChannelShutdown { 56 QIO_CHANNEL_SHUTDOWN_READ = 1, 57 QIO_CHANNEL_SHUTDOWN_WRITE = 2, 58 QIO_CHANNEL_SHUTDOWN_BOTH = 3, 59 }; 60 61 typedef gboolean (*QIOChannelFunc)(QIOChannel *ioc, 62 GIOCondition condition, 63 gpointer data); 64 65 /** 66 * QIOChannel: 67 * 68 * The QIOChannel defines the core API for a generic I/O channel 69 * class hierarchy. It is inspired by GIOChannel, but has the 70 * following differences 71 * 72 * - Use QOM to properly support arbitrary subclassing 73 * - Support use of iovecs for efficient I/O with multiple blocks 74 * - None of the character set translation, binary data exclusively 75 * - Direct support for QEMU Error object reporting 76 * - File descriptor passing 77 * 78 * This base class is abstract so cannot be instantiated. There 79 * will be subclasses for dealing with sockets, files, and higher 80 * level protocols such as TLS, WebSocket, etc. 81 */ 82 83 struct QIOChannel { 84 Object parent; 85 unsigned int features; /* bitmask of QIOChannelFeatures */ 86 char *name; 87 AioContext *read_ctx; 88 Coroutine *read_coroutine; 89 AioContext *write_ctx; 90 Coroutine *write_coroutine; 91 bool follow_coroutine_ctx; 92 #ifdef _WIN32 93 HANDLE event; /* For use with GSource on Win32 */ 94 #endif 95 }; 96 97 /** 98 * QIOChannelClass: 99 * 100 * This class defines the contract that all subclasses 101 * must follow to provide specific channel implementations. 102 * The first five callbacks are mandatory to support, others 103 * provide additional optional features. 104 * 105 * Consult the corresponding public API docs for a description 106 * of the semantics of each callback. io_shutdown in particular 107 * must be thread-safe, terminate quickly and must not block. 108 */ 109 struct QIOChannelClass { 110 ObjectClass parent; 111 112 /* Mandatory callbacks */ 113 ssize_t (*io_writev)(QIOChannel *ioc, 114 const struct iovec *iov, 115 size_t niov, 116 int *fds, 117 size_t nfds, 118 int flags, 119 Error **errp); 120 ssize_t (*io_readv)(QIOChannel *ioc, 121 const struct iovec *iov, 122 size_t niov, 123 int **fds, 124 size_t *nfds, 125 int flags, 126 Error **errp); 127 int (*io_close)(QIOChannel *ioc, 128 Error **errp); 129 GSource * (*io_create_watch)(QIOChannel *ioc, 130 GIOCondition condition); 131 int (*io_set_blocking)(QIOChannel *ioc, 132 bool enabled, 133 Error **errp); 134 135 /* Optional callbacks */ 136 ssize_t (*io_pwritev)(QIOChannel *ioc, 137 const struct iovec *iov, 138 size_t niov, 139 off_t offset, 140 Error **errp); 141 ssize_t (*io_preadv)(QIOChannel *ioc, 142 const struct iovec *iov, 143 size_t niov, 144 off_t offset, 145 Error **errp); 146 int (*io_shutdown)(QIOChannel *ioc, 147 QIOChannelShutdown how, 148 Error **errp); 149 void (*io_set_cork)(QIOChannel *ioc, 150 bool enabled); 151 void (*io_set_delay)(QIOChannel *ioc, 152 bool enabled); 153 off_t (*io_seek)(QIOChannel *ioc, 154 off_t offset, 155 int whence, 156 Error **errp); 157 void (*io_set_aio_fd_handler)(QIOChannel *ioc, 158 AioContext *read_ctx, 159 IOHandler *io_read, 160 AioContext *write_ctx, 161 IOHandler *io_write, 162 void *opaque); 163 int (*io_flush)(QIOChannel *ioc, 164 Error **errp); 165 int (*io_peerpid)(QIOChannel *ioc, 166 unsigned int *pid, 167 Error **errp); 168 }; 169 170 /* General I/O handling functions */ 171 172 /** 173 * qio_channel_has_feature: 174 * @ioc: the channel object 175 * @feature: the feature to check support of 176 * 177 * Determine whether the channel implementation supports 178 * the optional feature named in @feature. 179 * 180 * Returns: true if supported, false otherwise. 181 */ 182 bool qio_channel_has_feature(QIOChannel *ioc, 183 QIOChannelFeature feature); 184 185 /** 186 * qio_channel_set_feature: 187 * @ioc: the channel object 188 * @feature: the feature to set support for 189 * 190 * Add channel support for the feature named in @feature. 191 */ 192 void qio_channel_set_feature(QIOChannel *ioc, 193 QIOChannelFeature feature); 194 195 /** 196 * qio_channel_set_name: 197 * @ioc: the channel object 198 * @name: the name of the channel 199 * 200 * Sets the name of the channel, which serves as an aid 201 * to debugging. The name is used when creating GSource 202 * watches for this channel. 203 */ 204 void qio_channel_set_name(QIOChannel *ioc, 205 const char *name); 206 207 /** 208 * qio_channel_readv_full: 209 * @ioc: the channel object 210 * @iov: the array of memory regions to read data into 211 * @niov: the length of the @iov array 212 * @fds: pointer to an array that will received file handles 213 * @nfds: pointer filled with number of elements in @fds on return 214 * @flags: read flags (QIO_CHANNEL_READ_FLAG_*) 215 * @errp: pointer to a NULL-initialized error object 216 * 217 * Read data from the IO channel, storing it in the 218 * memory regions referenced by @iov. Each element 219 * in the @iov will be fully populated with data 220 * before the next one is used. The @niov parameter 221 * specifies the total number of elements in @iov. 222 * 223 * It is not required for all @iov to be filled with 224 * data. If the channel is in blocking mode, at least 225 * one byte of data will be read, but no more is 226 * guaranteed. If the channel is non-blocking and no 227 * data is available, it will return QIO_CHANNEL_ERR_BLOCK 228 * 229 * If the channel has passed any file descriptors, 230 * the @fds array pointer will be allocated and 231 * the elements filled with the received file 232 * descriptors. The @nfds pointer will be updated 233 * to indicate the size of the @fds array that 234 * was allocated. It is the callers responsibility 235 * to call close() on each file descriptor and to 236 * call g_free() on the array pointer in @fds. 237 * 238 * It is an error to pass a non-NULL @fds parameter 239 * unless qio_channel_has_feature() returns a true 240 * value for the QIO_CHANNEL_FEATURE_FD_PASS constant. 241 * 242 * Returns: the number of bytes read, or -1 on error, 243 * or QIO_CHANNEL_ERR_BLOCK if no data is available 244 * and the channel is non-blocking 245 */ 246 ssize_t qio_channel_readv_full(QIOChannel *ioc, 247 const struct iovec *iov, 248 size_t niov, 249 int **fds, 250 size_t *nfds, 251 int flags, 252 Error **errp); 253 254 255 /** 256 * qio_channel_writev_full: 257 * @ioc: the channel object 258 * @iov: the array of memory regions to write data from 259 * @niov: the length of the @iov array 260 * @fds: an array of file handles to send 261 * @nfds: number of file handles in @fds 262 * @flags: write flags (QIO_CHANNEL_WRITE_FLAG_*) 263 * @errp: pointer to a NULL-initialized error object 264 * 265 * Write data to the IO channel, reading it from the 266 * memory regions referenced by @iov. Each element 267 * in the @iov will be fully sent, before the next 268 * one is used. The @niov parameter specifies the 269 * total number of elements in @iov. 270 * 271 * It is not required for all @iov data to be fully 272 * sent. If the channel is in blocking mode, at least 273 * one byte of data will be sent, but no more is 274 * guaranteed. If the channel is non-blocking and no 275 * data can be sent, it will return QIO_CHANNEL_ERR_BLOCK 276 * 277 * If there are file descriptors to send, the @fds 278 * array should be non-NULL and provide the handles. 279 * All file descriptors will be sent if at least one 280 * byte of data was sent. 281 * 282 * It is an error to pass a non-NULL @fds parameter 283 * unless qio_channel_has_feature() returns a true 284 * value for the QIO_CHANNEL_FEATURE_FD_PASS constant. 285 * 286 * Returns: the number of bytes sent, or -1 on error, 287 * or QIO_CHANNEL_ERR_BLOCK if no data is can be sent 288 * and the channel is non-blocking 289 */ 290 ssize_t qio_channel_writev_full(QIOChannel *ioc, 291 const struct iovec *iov, 292 size_t niov, 293 int *fds, 294 size_t nfds, 295 int flags, 296 Error **errp); 297 298 /** 299 * qio_channel_readv_all_eof: 300 * @ioc: the channel object 301 * @iov: the array of memory regions to read data into 302 * @niov: the length of the @iov array 303 * @errp: pointer to a NULL-initialized error object 304 * 305 * Read data from the IO channel, storing it in the 306 * memory regions referenced by @iov. Each element 307 * in the @iov will be fully populated with data 308 * before the next one is used. The @niov parameter 309 * specifies the total number of elements in @iov. 310 * 311 * The function will wait for all requested data 312 * to be read, yielding from the current coroutine 313 * if required. 314 * 315 * If end-of-file occurs before any data is read, 316 * no error is reported; otherwise, if it occurs 317 * before all requested data has been read, an error 318 * will be reported. 319 * 320 * Returns: 1 if all bytes were read, 0 if end-of-file 321 * occurs without data, or -1 on error 322 */ 323 int coroutine_mixed_fn qio_channel_readv_all_eof(QIOChannel *ioc, 324 const struct iovec *iov, 325 size_t niov, 326 Error **errp); 327 328 /** 329 * qio_channel_readv_all: 330 * @ioc: the channel object 331 * @iov: the array of memory regions to read data into 332 * @niov: the length of the @iov array 333 * @errp: pointer to a NULL-initialized error object 334 * 335 * Read data from the IO channel, storing it in the 336 * memory regions referenced by @iov. Each element 337 * in the @iov will be fully populated with data 338 * before the next one is used. The @niov parameter 339 * specifies the total number of elements in @iov. 340 * 341 * The function will wait for all requested data 342 * to be read, yielding from the current coroutine 343 * if required. 344 * 345 * If end-of-file occurs before all requested data 346 * has been read, an error will be reported. 347 * 348 * Returns: 0 if all bytes were read, or -1 on error 349 */ 350 int coroutine_mixed_fn qio_channel_readv_all(QIOChannel *ioc, 351 const struct iovec *iov, 352 size_t niov, 353 Error **errp); 354 355 356 /** 357 * qio_channel_writev_all: 358 * @ioc: the channel object 359 * @iov: the array of memory regions to write data from 360 * @niov: the length of the @iov array 361 * @errp: pointer to a NULL-initialized error object 362 * 363 * Write data to the IO channel, reading it from the 364 * memory regions referenced by @iov. Each element 365 * in the @iov will be fully sent, before the next 366 * one is used. The @niov parameter specifies the 367 * total number of elements in @iov. 368 * 369 * The function will wait for all requested data 370 * to be written, yielding from the current coroutine 371 * if required. 372 * 373 * Returns: 0 if all bytes were written, or -1 on error 374 */ 375 int coroutine_mixed_fn qio_channel_writev_all(QIOChannel *ioc, 376 const struct iovec *iov, 377 size_t niov, 378 Error **errp); 379 380 /** 381 * qio_channel_readv: 382 * @ioc: the channel object 383 * @iov: the array of memory regions to read data into 384 * @niov: the length of the @iov array 385 * @errp: pointer to a NULL-initialized error object 386 * 387 * Behaves as qio_channel_readv_full() but does not support 388 * receiving of file handles. 389 */ 390 ssize_t qio_channel_readv(QIOChannel *ioc, 391 const struct iovec *iov, 392 size_t niov, 393 Error **errp); 394 395 /** 396 * qio_channel_writev: 397 * @ioc: the channel object 398 * @iov: the array of memory regions to write data from 399 * @niov: the length of the @iov array 400 * @errp: pointer to a NULL-initialized error object 401 * 402 * Behaves as qio_channel_writev_full() but does not support 403 * sending of file handles. 404 */ 405 ssize_t qio_channel_writev(QIOChannel *ioc, 406 const struct iovec *iov, 407 size_t niov, 408 Error **errp); 409 410 /** 411 * qio_channel_read: 412 * @ioc: the channel object 413 * @buf: the memory region to read data into 414 * @buflen: the length of @buf 415 * @errp: pointer to a NULL-initialized error object 416 * 417 * Behaves as qio_channel_readv_full() but does not support 418 * receiving of file handles, and only supports reading into 419 * a single memory region. 420 */ 421 ssize_t qio_channel_read(QIOChannel *ioc, 422 char *buf, 423 size_t buflen, 424 Error **errp); 425 426 /** 427 * qio_channel_write: 428 * @ioc: the channel object 429 * @buf: the memory regions to send data from 430 * @buflen: the length of @buf 431 * @errp: pointer to a NULL-initialized error object 432 * 433 * Behaves as qio_channel_writev_full() but does not support 434 * sending of file handles, and only supports writing from a 435 * single memory region. 436 */ 437 ssize_t qio_channel_write(QIOChannel *ioc, 438 const char *buf, 439 size_t buflen, 440 Error **errp); 441 442 /** 443 * qio_channel_read_all_eof: 444 * @ioc: the channel object 445 * @buf: the memory region to read data into 446 * @buflen: the number of bytes to @buf 447 * @errp: pointer to a NULL-initialized error object 448 * 449 * Reads @buflen bytes into @buf, possibly blocking or (if the 450 * channel is non-blocking) yielding from the current coroutine 451 * multiple times until the entire content is read. If end-of-file 452 * occurs immediately it is not an error, but if it occurs after 453 * data has been read it will return an error rather than a 454 * short-read. Otherwise behaves as qio_channel_read(). 455 * 456 * Returns: 1 if all bytes were read, 0 if end-of-file occurs 457 * without data, or -1 on error 458 */ 459 int coroutine_mixed_fn qio_channel_read_all_eof(QIOChannel *ioc, 460 char *buf, 461 size_t buflen, 462 Error **errp); 463 464 /** 465 * qio_channel_read_all: 466 * @ioc: the channel object 467 * @buf: the memory region to read data into 468 * @buflen: the number of bytes to @buf 469 * @errp: pointer to a NULL-initialized error object 470 * 471 * Reads @buflen bytes into @buf, possibly blocking or (if the 472 * channel is non-blocking) yielding from the current coroutine 473 * multiple times until the entire content is read. If end-of-file 474 * occurs it will return an error rather than a short-read. Otherwise 475 * behaves as qio_channel_read(). 476 * 477 * Returns: 0 if all bytes were read, or -1 on error 478 */ 479 int coroutine_mixed_fn qio_channel_read_all(QIOChannel *ioc, 480 char *buf, 481 size_t buflen, 482 Error **errp); 483 484 /** 485 * qio_channel_write_all: 486 * @ioc: the channel object 487 * @buf: the memory region to write data into 488 * @buflen: the number of bytes to @buf 489 * @errp: pointer to a NULL-initialized error object 490 * 491 * Writes @buflen bytes from @buf, possibly blocking or (if the 492 * channel is non-blocking) yielding from the current coroutine 493 * multiple times until the entire content is written. Otherwise 494 * behaves as qio_channel_write(). 495 * 496 * Returns: 0 if all bytes were written, or -1 on error 497 */ 498 int coroutine_mixed_fn qio_channel_write_all(QIOChannel *ioc, 499 const char *buf, 500 size_t buflen, 501 Error **errp); 502 503 /** 504 * qio_channel_set_blocking: 505 * @ioc: the channel object 506 * @enabled: the blocking flag state 507 * @errp: pointer to a NULL-initialized error object 508 * 509 * If @enabled is true, then the channel is put into 510 * blocking mode, otherwise it will be non-blocking. 511 * 512 * In non-blocking mode, read/write operations may 513 * return QIO_CHANNEL_ERR_BLOCK if they would otherwise 514 * block on I/O 515 */ 516 int qio_channel_set_blocking(QIOChannel *ioc, 517 bool enabled, 518 Error **errp); 519 520 /** 521 * qio_channel_set_follow_coroutine_ctx: 522 * @ioc: the channel object 523 * @enabled: whether or not to follow the coroutine's AioContext 524 * 525 * If @enabled is true, calls to qio_channel_yield() use the current 526 * coroutine's AioContext. Usually this is desirable. 527 * 528 * If @enabled is false, calls to qio_channel_yield() use the global iohandler 529 * AioContext. This is may be used by coroutines that run in the main loop and 530 * do not wish to respond to I/O during nested event loops. This is the 531 * default for compatibility with code that is not aware of AioContexts. 532 */ 533 void qio_channel_set_follow_coroutine_ctx(QIOChannel *ioc, bool enabled); 534 535 /** 536 * qio_channel_close: 537 * @ioc: the channel object 538 * @errp: pointer to a NULL-initialized error object 539 * 540 * Close the channel, flushing any pending I/O 541 * 542 * Returns: 0 on success, -1 on error 543 */ 544 int qio_channel_close(QIOChannel *ioc, 545 Error **errp); 546 547 /** 548 * qio_channel_pwritev 549 * @ioc: the channel object 550 * @iov: the array of memory regions to write data from 551 * @niov: the length of the @iov array 552 * @offset: offset in the channel where writes should begin 553 * @errp: pointer to a NULL-initialized error object 554 * 555 * Not all implementations will support this facility, so may report 556 * an error. To avoid errors, the caller may check for the feature 557 * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method. 558 * 559 * Behaves as qio_channel_writev_full, apart from not supporting 560 * sending of file handles as well as beginning the write at the 561 * passed @offset 562 * 563 */ 564 ssize_t qio_channel_pwritev(QIOChannel *ioc, const struct iovec *iov, 565 size_t niov, off_t offset, Error **errp); 566 567 /** 568 * qio_channel_pwrite 569 * @ioc: the channel object 570 * @buf: the memory region to write data into 571 * @buflen: the number of bytes to @buf 572 * @offset: offset in the channel where writes should begin 573 * @errp: pointer to a NULL-initialized error object 574 * 575 * Not all implementations will support this facility, so may report 576 * an error. To avoid errors, the caller may check for the feature 577 * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method. 578 * 579 */ 580 ssize_t qio_channel_pwrite(QIOChannel *ioc, char *buf, size_t buflen, 581 off_t offset, Error **errp); 582 583 /** 584 * qio_channel_preadv 585 * @ioc: the channel object 586 * @iov: the array of memory regions to read data into 587 * @niov: the length of the @iov array 588 * @offset: offset in the channel where writes should begin 589 * @errp: pointer to a NULL-initialized error object 590 * 591 * Not all implementations will support this facility, so may report 592 * an error. To avoid errors, the caller may check for the feature 593 * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method. 594 * 595 * Behaves as qio_channel_readv_full, apart from not supporting 596 * receiving of file handles as well as beginning the read at the 597 * passed @offset 598 * 599 */ 600 ssize_t qio_channel_preadv(QIOChannel *ioc, const struct iovec *iov, 601 size_t niov, off_t offset, Error **errp); 602 603 /** 604 * qio_channel_pread 605 * @ioc: the channel object 606 * @buf: the memory region to write data into 607 * @buflen: the number of bytes to @buf 608 * @offset: offset in the channel where writes should begin 609 * @errp: pointer to a NULL-initialized error object 610 * 611 * Not all implementations will support this facility, so may report 612 * an error. To avoid errors, the caller may check for the feature 613 * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method. 614 * 615 */ 616 ssize_t qio_channel_pread(QIOChannel *ioc, char *buf, size_t buflen, 617 off_t offset, Error **errp); 618 619 /** 620 * qio_channel_shutdown: 621 * @ioc: the channel object 622 * @how: the direction to shutdown 623 * @errp: pointer to a NULL-initialized error object 624 * 625 * Shutdowns transmission and/or receiving of data 626 * without closing the underlying transport. 627 * 628 * Not all implementations will support this facility, 629 * so may report an error. To avoid errors, the 630 * caller may check for the feature flag 631 * QIO_CHANNEL_FEATURE_SHUTDOWN prior to calling 632 * this method. 633 * 634 * This function is thread-safe, terminates quickly and does not block. 635 * 636 * Returns: 0 on success, -1 on error 637 */ 638 int qio_channel_shutdown(QIOChannel *ioc, 639 QIOChannelShutdown how, 640 Error **errp); 641 642 /** 643 * qio_channel_set_delay: 644 * @ioc: the channel object 645 * @enabled: the new flag state 646 * 647 * Controls whether the underlying transport is 648 * permitted to delay writes in order to merge 649 * small packets. If @enabled is true, then the 650 * writes may be delayed in order to opportunistically 651 * merge small packets into larger ones. If @enabled 652 * is false, writes are dispatched immediately with 653 * no delay. 654 * 655 * When @enabled is false, applications may wish to 656 * use the qio_channel_set_cork() method to explicitly 657 * control write merging. 658 * 659 * On channels which are backed by a socket, this 660 * API corresponds to the inverse of TCP_NODELAY flag, 661 * controlling whether the Nagle algorithm is active. 662 * 663 * This setting is merely a hint, so implementations are 664 * free to ignore this without it being considered an 665 * error. 666 */ 667 void qio_channel_set_delay(QIOChannel *ioc, 668 bool enabled); 669 670 /** 671 * qio_channel_set_cork: 672 * @ioc: the channel object 673 * @enabled: the new flag state 674 * 675 * Controls whether the underlying transport is 676 * permitted to dispatch data that is written. 677 * If @enabled is true, then any data written will 678 * be queued in local buffers until @enabled is 679 * set to false once again. 680 * 681 * This feature is typically used when the automatic 682 * write coalescing facility is disabled via the 683 * qio_channel_set_delay() method. 684 * 685 * On channels which are backed by a socket, this 686 * API corresponds to the TCP_CORK flag. 687 * 688 * This setting is merely a hint, so implementations are 689 * free to ignore this without it being considered an 690 * error. 691 */ 692 void qio_channel_set_cork(QIOChannel *ioc, 693 bool enabled); 694 695 696 /** 697 * qio_channel_seek: 698 * @ioc: the channel object 699 * @offset: the position to seek to, relative to @whence 700 * @whence: one of the (POSIX) SEEK_* constants listed below 701 * @errp: pointer to a NULL-initialized error object 702 * 703 * Moves the current I/O position within the channel 704 * @ioc, to be @offset. The value of @offset is 705 * interpreted relative to @whence: 706 * 707 * SEEK_SET - the position is set to @offset bytes 708 * SEEK_CUR - the position is moved by @offset bytes 709 * SEEK_END - the position is set to end of the file plus @offset bytes 710 * 711 * Not all implementations will support this facility, 712 * so may report an error. 713 * 714 * Returns: the new position on success, (off_t)-1 on failure 715 */ 716 off_t qio_channel_io_seek(QIOChannel *ioc, 717 off_t offset, 718 int whence, 719 Error **errp); 720 721 722 /** 723 * qio_channel_create_watch: 724 * @ioc: the channel object 725 * @condition: the I/O condition to monitor 726 * 727 * Create a new main loop source that is used to watch 728 * for the I/O condition @condition. Typically the 729 * qio_channel_add_watch() method would be used instead 730 * of this, since it directly attaches a callback to 731 * the source 732 * 733 * Returns: the new main loop source. 734 */ 735 GSource *qio_channel_create_watch(QIOChannel *ioc, 736 GIOCondition condition); 737 738 /** 739 * qio_channel_add_watch: 740 * @ioc: the channel object 741 * @condition: the I/O condition to monitor 742 * @func: callback to invoke when the source becomes ready 743 * @user_data: opaque data to pass to @func 744 * @notify: callback to free @user_data 745 * 746 * Create a new main loop source that is used to watch 747 * for the I/O condition @condition. The callback @func 748 * will be registered against the source, to be invoked 749 * when the source becomes ready. The optional @user_data 750 * will be passed to @func when it is invoked. The @notify 751 * callback will be used to free @user_data when the 752 * watch is deleted 753 * 754 * The returned source ID can be used with g_source_remove() 755 * to remove and free the source when no longer required. 756 * Alternatively the @func callback can return a FALSE 757 * value. 758 * 759 * Returns: the source ID 760 */ 761 guint qio_channel_add_watch(QIOChannel *ioc, 762 GIOCondition condition, 763 QIOChannelFunc func, 764 gpointer user_data, 765 GDestroyNotify notify); 766 767 /** 768 * qio_channel_add_watch_full: 769 * @ioc: the channel object 770 * @condition: the I/O condition to monitor 771 * @func: callback to invoke when the source becomes ready 772 * @user_data: opaque data to pass to @func 773 * @notify: callback to free @user_data 774 * @context: the context to run the watch source 775 * 776 * Similar as qio_channel_add_watch(), but allows to specify context 777 * to run the watch source. 778 * 779 * Returns: the source ID 780 */ 781 guint qio_channel_add_watch_full(QIOChannel *ioc, 782 GIOCondition condition, 783 QIOChannelFunc func, 784 gpointer user_data, 785 GDestroyNotify notify, 786 GMainContext *context); 787 788 /** 789 * qio_channel_add_watch_source: 790 * @ioc: the channel object 791 * @condition: the I/O condition to monitor 792 * @func: callback to invoke when the source becomes ready 793 * @user_data: opaque data to pass to @func 794 * @notify: callback to free @user_data 795 * @context: gcontext to bind the source to 796 * 797 * Similar as qio_channel_add_watch(), but allows to specify context 798 * to run the watch source, meanwhile return the GSource object 799 * instead of tag ID, with the GSource referenced already. 800 * 801 * Note: callers is responsible to unref the source when not needed. 802 * 803 * Returns: the source pointer 804 */ 805 GSource *qio_channel_add_watch_source(QIOChannel *ioc, 806 GIOCondition condition, 807 QIOChannelFunc func, 808 gpointer user_data, 809 GDestroyNotify notify, 810 GMainContext *context); 811 812 /** 813 * qio_channel_yield: 814 * @ioc: the channel object 815 * @condition: the I/O condition to wait for 816 * 817 * Yields execution from the current coroutine until the condition 818 * indicated by @condition becomes available. @condition must 819 * be either %G_IO_IN or %G_IO_OUT; it cannot contain both. In 820 * addition, no two coroutine can be waiting on the same condition 821 * and channel at the same time. 822 * 823 * This must only be called from coroutine context. It is safe to 824 * reenter the coroutine externally while it is waiting; in this 825 * case the function will return even if @condition is not yet 826 * available. 827 */ 828 void coroutine_fn qio_channel_yield(QIOChannel *ioc, 829 GIOCondition condition); 830 831 /** 832 * qio_channel_wake_read: 833 * @ioc: the channel object 834 * 835 * If qio_channel_yield() is currently waiting for the channel to become 836 * readable, interrupt it and reenter immediately. This function is safe to call 837 * from any thread. 838 */ 839 void qio_channel_wake_read(QIOChannel *ioc); 840 841 /** 842 * qio_channel_wait: 843 * @ioc: the channel object 844 * @condition: the I/O condition to wait for 845 * 846 * Block execution from the current thread until 847 * the condition indicated by @condition becomes 848 * available. 849 * 850 * This will enter a nested event loop to perform 851 * the wait. 852 */ 853 void qio_channel_wait(QIOChannel *ioc, 854 GIOCondition condition); 855 856 /** 857 * qio_channel_set_aio_fd_handler: 858 * @ioc: the channel object 859 * @read_ctx: the AioContext to set the read handler on or NULL 860 * @io_read: the read handler 861 * @write_ctx: the AioContext to set the write handler on or NULL 862 * @io_write: the write handler 863 * @opaque: the opaque value passed to the handler 864 * 865 * This is used internally by qio_channel_yield(). It can 866 * be used by channel implementations to forward the handlers 867 * to another channel (e.g. from #QIOChannelTLS to the 868 * underlying socket). 869 * 870 * When @read_ctx is NULL, don't touch the read handler. When @write_ctx is 871 * NULL, don't touch the write handler. Note that setting the read handler 872 * clears the write handler, and vice versa, if they share the same AioContext. 873 * Therefore the caller must pass both handlers together when sharing the same 874 * AioContext. 875 */ 876 void qio_channel_set_aio_fd_handler(QIOChannel *ioc, 877 AioContext *read_ctx, 878 IOHandler *io_read, 879 AioContext *write_ctx, 880 IOHandler *io_write, 881 void *opaque); 882 883 /** 884 * qio_channel_readv_full_all_eof: 885 * @ioc: the channel object 886 * @iov: the array of memory regions to read data to 887 * @niov: the length of the @iov array 888 * @fds: an array of file handles to read 889 * @nfds: number of file handles in @fds 890 * @flags: read flags (QIO_CHANNEL_READ_FLAG_*) 891 * @errp: pointer to a NULL-initialized error object 892 * 893 * 894 * Performs same function as qio_channel_readv_all_eof. 895 * Additionally, attempts to read file descriptors shared 896 * over the channel. The function will wait for all 897 * requested data to be read, yielding from the current 898 * coroutine if required. data refers to both file 899 * descriptors and the iovs. 900 * 901 * Returns: 1 if all bytes were read, 0 if end-of-file 902 * occurs without data, or -1 on error 903 */ 904 905 int coroutine_mixed_fn qio_channel_readv_full_all_eof(QIOChannel *ioc, 906 const struct iovec *iov, 907 size_t niov, 908 int **fds, size_t *nfds, 909 int flags, 910 Error **errp); 911 912 /** 913 * qio_channel_readv_full_all: 914 * @ioc: the channel object 915 * @iov: the array of memory regions to read data to 916 * @niov: the length of the @iov array 917 * @fds: an array of file handles to read 918 * @nfds: number of file handles in @fds 919 * @errp: pointer to a NULL-initialized error object 920 * 921 * 922 * Performs same function as qio_channel_readv_all_eof. 923 * Additionally, attempts to read file descriptors shared 924 * over the channel. The function will wait for all 925 * requested data to be read, yielding from the current 926 * coroutine if required. data refers to both file 927 * descriptors and the iovs. 928 * 929 * Returns: 0 if all bytes were read, or -1 on error 930 */ 931 932 int coroutine_mixed_fn qio_channel_readv_full_all(QIOChannel *ioc, 933 const struct iovec *iov, 934 size_t niov, 935 int **fds, size_t *nfds, 936 Error **errp); 937 938 /** 939 * qio_channel_writev_full_all: 940 * @ioc: the channel object 941 * @iov: the array of memory regions to write data from 942 * @niov: the length of the @iov array 943 * @fds: an array of file handles to send 944 * @nfds: number of file handles in @fds 945 * @flags: write flags (QIO_CHANNEL_WRITE_FLAG_*) 946 * @errp: pointer to a NULL-initialized error object 947 * 948 * 949 * Behaves like qio_channel_writev_full but will attempt 950 * to send all data passed (file handles and memory regions). 951 * The function will wait for all requested data 952 * to be written, yielding from the current coroutine 953 * if required. 954 * 955 * If QIO_CHANNEL_WRITE_FLAG_ZERO_COPY is passed in flags, 956 * instead of waiting for all requested data to be written, 957 * this function will wait until it's all queued for writing. 958 * In this case, if the buffer gets changed between queueing and 959 * sending, the updated buffer will be sent. If this is not a 960 * desired behavior, it's suggested to call qio_channel_flush() 961 * before reusing the buffer. 962 * 963 * Returns: 0 if all bytes were written, or -1 on error 964 */ 965 966 int coroutine_mixed_fn qio_channel_writev_full_all(QIOChannel *ioc, 967 const struct iovec *iov, 968 size_t niov, 969 int *fds, size_t nfds, 970 int flags, Error **errp); 971 972 /** 973 * qio_channel_flush: 974 * @ioc: the channel object 975 * @errp: pointer to a NULL-initialized error object 976 * 977 * Will block until every packet queued with 978 * qio_channel_writev_full() + QIO_CHANNEL_WRITE_FLAG_ZERO_COPY 979 * is sent, or return in case of any error. 980 * 981 * If not implemented, acts as a no-op, and returns 0. 982 * 983 * Returns -1 if any error is found, 984 * 1 if every send failed to use zero copy. 985 * 0 otherwise. 986 */ 987 988 int qio_channel_flush(QIOChannel *ioc, 989 Error **errp); 990 991 /** 992 * qio_channel_get_peercred: 993 * @ioc: the channel object 994 * @pid: pointer to pid 995 * @errp: pointer to a NULL-initialized error object 996 * 997 * Returns the pid of the peer process connected to this socket. 998 * 999 * The use of this function is possible only for connected 1000 * AF_UNIX stream sockets and for AF_UNIX stream and datagram 1001 * socket pairs on Linux. 1002 * Return -1 on error with pid -1 for the non-Linux OS. 1003 * 1004 */ 1005 int qio_channel_get_peerpid(QIOChannel *ioc, 1006 unsigned int *pid, 1007 Error **errp); 1008 1009 #endif /* QIO_CHANNEL_H */ 1010