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