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