include/io/channel-file.h

   1 /*
   2  * QEMU I/O channels files driver
   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_FILE_H
  22 #define QIO_CHANNEL_FILE_H
  23
  24 #include "io/channel.h"
  25 #include "qom/object.h"
  26
  27 #define TYPE_QIO_CHANNEL_FILE "qio-channel-file"
  28 OBJECT_DECLARE_SIMPLE_TYPE(QIOChannelFile, QIO_CHANNEL_FILE)
  29
  30
  31 /**
  32  * QIOChannelFile:
  33  *
  34  * The QIOChannelFile object provides a channel implementation
  35  * that is able to perform I/O on block devices, character
  36  * devices, FIFOs, pipes and plain files. While it is technically
  37  * able to work on sockets too on the UNIX platform, this is not
  38  * portable to Windows and lacks some extra sockets specific
  39  * functionality. So the QIOChannelSocket object is recommended
  40  * for that use case.
  41  *
  42  */
  43
  44 struct QIOChannelFile {
  45     QIOChannel parent;
  46     int fd;
  47 };
  48
  49
  50 /**
  51  * qio_channel_file_new_fd:
  52  * @fd: the file descriptor
  53  *
  54  * Create a new IO channel object for a file represented
  55  * by the @fd parameter. @fd can be associated with a
  56  * block device, character device, fifo, pipe, or a
  57  * regular file. For sockets, the QIOChannelSocket class
  58  * should be used instead, as this provides greater
  59  * functionality and cross platform portability.
  60  *
  61  * The channel will own the passed in file descriptor
  62  * and will take responsibility for closing it, so the
  63  * caller must not close it. If appropriate the caller
  64  * should dup() its FD before opening the channel.
  65  *
  66  * Returns: the new channel object
  67  */
  68 QIOChannelFile *
  69 qio_channel_file_new_fd(int fd);
  70
  71 /**
  72  * qio_channel_file_new_dupfd:
  73  * @fd: the file descriptor
  74  * @errp: pointer to initialized error object
  75  *
  76  * Create a new IO channel object for a file represented by the @fd
  77  * parameter. Like qio_channel_file_new_fd(), but the @fd is first
  78  * duplicated with dup().
  79  *
  80  * The channel will own the duplicated file descriptor and will take
  81  * responsibility for closing it, the original FD is owned by the
  82  * caller.
  83  *
  84  * Returns: the new channel object
  85  */
  86 QIOChannelFile *
  87 qio_channel_file_new_dupfd(int fd, Error **errp);
  88
  89 /**
  90  * qio_channel_file_new_path:
  91  * @path: the file path
  92  * @flags: the open flags (O_RDONLY|O_WRONLY|O_RDWR, etc)
  93  * @mode: the file creation mode if O_CREAT is set in @flags
  94  * @errp: pointer to initialized error object
  95  *
  96  * Create a new IO channel object for a file represented
  97  * by the @path parameter. @path can point to any
  98  * type of file on which sequential I/O can be
  99  * performed, whether it be a plain file, character
 100  * device or block device.
 101  *
 102  * Returns: the new channel object
 103  */
 104 QIOChannelFile *
 105 qio_channel_file_new_path(const char *path,
 106                           int flags,
 107                           mode_t mode,
 108                           Error **errp);
 109
 110 #endif /* QIO_CHANNEL_FILE_H */