dmlite  0.6
io.h
Go to the documentation of this file.
1 /** @file include/dmlite/c/io.h
2  * @brief C wrapper for I/O interfaces.
3  * @author Alejandro Álvarez Ayllon <aalvarez@cern.ch>
4  */
5 #ifndef DMLITE_IO_H
6 #define DMLITE_IO_H
7 
8 #include "dmlite.h"
9 #include "any.h"
10 #include "pool.h"
11 #include <sys/uio.h>
12 #include <unistd.h>
13 
14 
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18 
19 /** Use this flag in addition to the standard ones to skip any
20  * security check (i.e. token validation)
21  */
22 #define O_INSECURE 010
23 
24 /** Handle for a file descriptor. */
25 typedef struct dmlite_fd dmlite_fd;
26 
27 /**
28  * @brief Opens a file.
29  * @param context The DM context.
30  * @param path The path to open.
31  * @param flags See open()
32  * @param extra The key-value pairs.
33  * @param ... Should be mode_t when called with O_CREAT.
34  * @return An opaque handler for the file, NULL on failure.
35  */
36 dmlite_fd* dmlite_fopen(dmlite_context* context, const char* path, int flags,
37  const dmlite_any_dict* extra, ...);
38 
39 /**
40  * @brief Closes a file.
41  * @param fd The file descriptor as returned by dmlite_open.
42  * @return 0 on success, error code otherwise.
43  */
44 int dmlite_fclose(dmlite_fd* fd);
45 
46 /**
47  * @brief Gets information about a file descriptor.
48  * @param fd The file descriptor.
49  * @param buf Where to put the information.
50  * @return 0 on success, error code otherwise.
51  * @note Not all plug-ins will fill all the fields, but st_size is
52  * a reasonable expectation.
53  */
54 int dmlite_fstat(dmlite_fd* fd, struct stat* buf);
55 
56 /**
57  * @brief Sets the file position.
58  * @param fd The file descriptor.
59  * @param offset The offset.
60  * @param whence See fseek()
61  * @return 0 on success, error code otherwise.
62  */
63 int dmlite_fseek(dmlite_fd* fd, off_t offset, int whence);
64 
65 /**
66  * @brief Returns the cursor position.
67  * @param fd The file descriptor.
68  * @return The cursor position, or -1 on error.
69  */
70 off_t dmlite_ftell(dmlite_fd* fd);
71 
72 /**
73  * @brief Reads from a file.
74  * @param fd The file descriptor.
75  * @param buffer Where to put the data.
76  * @param count Number of bytes to read.
77  * @return Number of bytes actually read on success. -1 on failure.
78  */
79 ssize_t dmlite_fread(dmlite_fd* fd, void* buffer, size_t count);
80 
81 /**
82  * @brief Writes to a file.
83  * @param fd The file descriptor.
84  * @param buffer A pointer to the data.
85  * @param count Number of bytes to write.
86  * @return Number of bytes actually written. -1 on failure.
87  */
88 ssize_t dmlite_fwrite(dmlite_fd* fd, const void* buffer, size_t count);
89 
90 /**
91  * @brief Reads from a file into multiple buffers.
92  * @param fd The file descriptor.
93  * @param vector Array of buffers.
94  * @param count Number of elements in the array of buffers.
95  * @return Number of bytes actually read on success. -1 on failure.
96  */
97 ssize_t dmlite_freadv(dmlite_fd* fd, const struct iovec* vector, size_t count);
98 
99 /**
100 * @brief Reads from a file into multiple buffers.
101 * @param fd The file descriptor.
102 * @param vector Array of buffers.
103 * @param count Number of elements in the array of buffers.
104 * @return Number of bytes actually read on success. -1 on failure.
105 */
106 ssize_t dmlite_fwritev(dmlite_fd* fd, const struct iovec* vector, size_t count);
107 
108 /**
109  * @brief Reads up to count bytes starting at the given offset.
110  * Does not change internal offset.
111  * @param fd File descriptor.
112  * @param buffer Buffer where to put the data.
113  * @param count Number of bytes to read.
114  * @param offset Read offset.
115  * @return Number of bytes actually read on success. -1 on failure.
116  */
117 ssize_t dmlite_fpread(dmlite_fd* fd, void* buffer, size_t count, off_t offset);
118 
119 /**
120  * @brief Writes count bytes starting at the given offset.
121  * Does not change internal offset.
122  * @param fd File descriptor.
123  * @param buffer Data to write.
124  * @param count Number of bytes to read.
125  * @param offset Write offset.
126  * @return Number of bytes actually write on success. -1 on failure.
127  */
128 ssize_t dmlite_fpwrite(dmlite_fd* fd, const void* buffer, size_t count, off_t offset);
129 
130 /**
131  * @brief Returns 1 if EOF.
132  * @param fd The file descriptor.
133  * @return 0 if there is more to read. 1 if EOF.
134  */
135 int dmlite_feof(dmlite_fd* fd);
136 
137 /**
138  * @brief Returns the last errror code.
139  * @param fd The file descriptor.
140  * @return The last error code.
141  */
142 int dmlite_ferrno(dmlite_fd* fd);
143 
144 /**
145  * @brief Returns the last error message.
146  * @param fd The file descriptor.
147  * @return A pointer to an internal buffer with the last error message.
148  * @note This buffer is specific to each file descriptor.
149  */
150 const char* dmlite_ferror(dmlite_fd* fd);
151 
152 /**
153  * @brief Finishes a PUT.
154  * @param context The DM context.
155  * @param loc The location as returned by dmlite_put.
156  * @return 0 on success, error code otherwise.
157  */
159  const dmlite_location* loc);
160 
161 /**
162  * @brief Returns the system file descriptor if available.
163  * @param fd The file descriptor.
164  * @return The file descriptor, -1 if it can not be retrieved.
165  * @note Support depends on the plugin providing the file.
166  * @note Calling dmlite_fclose _will_ close the file descriptor returned by this.
167  */
168 int dmlite_fileno(dmlite_fd* fd);
169 
170 #ifdef __cplusplus
171 }
172 #endif
173 
174 #endif /* DMLITE_IO_H */
int dmlite_ferrno(dmlite_fd *fd)
Returns the last errror code.
C wrapper for DMLite Pool API.
struct dmlite_any_dict dmlite_any_dict
Handles key->value pairs.
Definition: any.h:25
const char * dmlite_ferror(dmlite_fd *fd)
Returns the last error message.
C wrapper for DMLite.
dmlite_fd * dmlite_fopen(dmlite_context *context, const char *path, int flags, const dmlite_any_dict *extra,...)
Opens a file.
int dmlite_fileno(dmlite_fd *fd)
Returns the system file descriptor if available.
ssize_t dmlite_fwritev(dmlite_fd *fd, const struct iovec *vector, size_t count)
Reads from a file into multiple buffers.
ssize_t dmlite_freadv(dmlite_fd *fd, const struct iovec *vector, size_t count)
Reads from a file into multiple buffers.
ssize_t dmlite_fwrite(dmlite_fd *fd, const void *buffer, size_t count)
Writes to a file.
Opaque handler to pass different types of values to the API.
struct dmlite_context dmlite_context
Handle for a initialized context.
Definition: dmlite.h:23
int dmlite_donewriting(dmlite_context *context, const dmlite_location *loc)
Finishes a PUT.
ssize_t dmlite_fread(dmlite_fd *fd, void *buffer, size_t count)
Reads from a file.
struct dmlite_fd dmlite_fd
Definition: io.h:25
int dmlite_fstat(dmlite_fd *fd, struct stat *buf)
Gets information about a file descriptor.
int dmlite_feof(dmlite_fd *fd)
Returns 1 if EOF.
ssize_t dmlite_fpread(dmlite_fd *fd, void *buffer, size_t count, off_t offset)
Reads up to count bytes starting at the given offset. Does not change internal offset.
off_t dmlite_ftell(dmlite_fd *fd)
Returns the cursor position.
int dmlite_fclose(dmlite_fd *fd)
Closes a file.
ssize_t dmlite_fpwrite(dmlite_fd *fd, const void *buffer, size_t count, off_t offset)
Writes count bytes starting at the given offset. Does not change internal offset. ...
Collection of chunks that form a replica.
Definition: pool.h:42
int dmlite_fseek(dmlite_fd *fd, off_t offset, int whence)
Sets the file position.