include/dmlite/c/io.h

Go to the documentation of this file.
00001 /** @file   include/dmlite/c/io.h
00002  *  @brief  C wrapper for I/O interfaces.
00003  *  @author Alejandro Álvarez Ayllon <aalvarez@cern.ch>
00004  */
00005 #ifndef DMLITE_IO_H
00006 #define DMLITE_IO_H
00007 
00008 #include "dmlite.h"
00009 #include "any.h"
00010 #include "pool.h"
00011 #include <sys/uio.h>
00012 #include <unistd.h>
00013 
00014 
00015 #ifdef  __cplusplus
00016 extern "C" {
00017 #endif
00018 
00019 /** Use this flag in addition to the standard ones to skip any
00020  *  security check (i.e. token validation)
00021  */
00022 #define O_INSECURE 010
00023 
00024 /** Handle for a file descriptor. */
00025 typedef struct dmlite_fd dmlite_fd;
00026 
00027 /**
00028  * @brief         Opens a file.
00029  * @param context The DM context.
00030  * @param path    The path to open.
00031  * @param flags   See open()
00032  * @param extra   The key-value pairs.
00033  * @param ...     Should be mode_t when called with O_CREAT.
00034  * @return        An opaque handler for the file, NULL on failure.
00035  */
00036 dmlite_fd* dmlite_fopen(dmlite_context* context, const char* path, int flags,
00037                         const dmlite_any_dict* extra, ...);
00038 
00039 /**
00040  * @brief    Closes a file.
00041  * @param fd The file descriptor as returned by dmlite_open.
00042  * @return   0 on success, error code otherwise.
00043  */
00044 int dmlite_fclose(dmlite_fd* fd);
00045 
00046 /**
00047  * @brief     Gets information about a file descriptor.
00048  * @param fd  The file descriptor.
00049  * @param buf Where to put the information.
00050  * @return    0 on success, error code otherwise.
00051  * @note      Not all plug-ins will fill all the fields, but st_size is
00052  *            a reasonable expectation.
00053  */
00054 int dmlite_fstat(dmlite_fd* fd, struct stat* buf);
00055 
00056 /**
00057  * @brief        Sets the file position.
00058  * @param fd     The file descriptor.
00059  * @param offset The offset.
00060  * @param whence See fseek()
00061  * @return       0 on success, error code otherwise.
00062  */
00063 int dmlite_fseek(dmlite_fd* fd, off_t offset, int whence);
00064 
00065 /**
00066  * @brief    Returns the cursor position.
00067  * @param fd The file descriptor.
00068  * @return   The cursor position, or -1 on error.
00069  */
00070 off_t dmlite_ftell(dmlite_fd* fd);
00071 
00072 /**
00073  * @brief        Reads from a file.
00074  * @param fd     The file descriptor.
00075  * @param buffer Where to put the data.
00076  * @param count  Number of bytes to read.
00077  * @return       Number of bytes actually read on success. -1 on failure.
00078  */
00079 ssize_t dmlite_fread(dmlite_fd* fd, void* buffer, size_t count);
00080 
00081 /**
00082  * @brief        Writes to a file.
00083  * @param fd     The file descriptor.
00084  * @param buffer A pointer to the data.
00085  * @param count  Number of bytes to write.
00086  * @return       Number of bytes actually written. -1 on failure.
00087  */
00088 ssize_t dmlite_fwrite(dmlite_fd* fd, const void* buffer, size_t count);
00089 
00090 /**
00091  * @brief        Reads from a file into multiple buffers.
00092  * @param fd     The file descriptor.
00093  * @param vector Array of buffers.
00094  * @param count  Number of elements in the array of buffers.
00095  * @return       Number of bytes actually read on success. -1 on failure.
00096  */
00097 ssize_t dmlite_freadv(dmlite_fd* fd, const struct iovec* vector, size_t count);
00098 
00099 /**
00100 * @brief        Reads from a file into multiple buffers.
00101 * @param fd     The file descriptor.
00102 * @param vector Array of buffers.
00103 * @param count  Number of elements in the array of buffers.
00104 * @return       Number of bytes actually read on success. -1 on failure.
00105 */
00106 ssize_t dmlite_fwritev(dmlite_fd* fd, const struct iovec* vector, size_t count);
00107 
00108 /**
00109  * @brief        Reads up to count bytes starting at the given offset.
00110  *               Does not change internal offset.
00111  * @param fd     File descriptor.
00112  * @param buffer Buffer where to put the data.
00113  * @param count  Number of bytes to read.
00114  * @param offset Read offset.
00115  * @return       Number of bytes actually read on success. -1 on failure.
00116  */
00117 ssize_t dmlite_fpread(dmlite_fd* fd, void* buffer, size_t count, off_t offset);
00118 
00119 /**
00120  * @brief        Writes count bytes starting at the given offset.
00121  *               Does not change internal offset.
00122  * @param fd     File descriptor.
00123  * @param buffer Data to write.
00124  * @param count  Number of bytes to read.
00125  * @param offset Write offset.
00126  * @return       Number of bytes actually write on success. -1 on failure.
00127  */
00128 ssize_t dmlite_fpwrite(dmlite_fd* fd, const void* buffer, size_t count, off_t offset);
00129 
00130 /**
00131  * @brief    Returns 1 if EOF.
00132  * @param fd The file descriptor.
00133  * @return   0 if there is more to read. 1 if EOF.
00134  */
00135 int dmlite_feof(dmlite_fd* fd);
00136 
00137 /**
00138  * @brief    Returns the last errror code.
00139  * @param fd The file descriptor.
00140  * @return   The last error code.
00141  */
00142 int dmlite_ferrno(dmlite_fd* fd);
00143 
00144 /**
00145  * @brief    Returns the last error message.
00146  * @param fd The file descriptor.
00147  * @return   A pointer to an internal buffer with the last error message.
00148  * @note     This buffer is specific to each file descriptor.
00149  */
00150 const char* dmlite_ferrror(dmlite_fd* fd);
00151 
00152 /**
00153  * @brief         Finishes a PUT.
00154  * @param context The DM context.
00155  * @param loc     The location as returned by dmlite_put.
00156  * @return        0 on success, error code otherwise.
00157  */
00158 int dmlite_donewriting(dmlite_context* context,
00159                        const dmlite_location* loc);
00160 
00161 #ifdef  __cplusplus
00162 }
00163 #endif
00164 
00165 #endif /* DMLITE_IO_H */

Generated on 11 Jul 2013 for dmlite by  doxygen 1.4.7