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
16extern "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. */
25typedef 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 */
36dmlite_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 */
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 */
54int 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 */
63int 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 */
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 */
79ssize_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 */
88ssize_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 */
97ssize_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*/
106ssize_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 */
117ssize_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 */
128ssize_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 */
136
137/**
138 * @brief Returns the last errror code.
139 * @param fd The file descriptor.
140 * @return The last error code.
141 */
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 */
150const 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 */
169
170#ifdef __cplusplus
171}
172#endif
173
174#endif /* DMLITE_IO_H */
Opaque handler to pass different types of values to the API.
struct dmlite_any_dict dmlite_any_dict
Handles key->value pairs.
Definition: any.h:25
struct dmlite_context dmlite_context
Handle for a initialized context.
Definition: dmlite.h:23
int dmlite_ferrno(dmlite_fd *fd)
Returns the last errror code.
const char * dmlite_ferror(dmlite_fd *fd)
Returns the last error message.
dmlite_fd * dmlite_fopen(dmlite_context *context, const char *path, int flags, const dmlite_any_dict *extra,...)
Opens a file.
int dmlite_donewriting(dmlite_context *context, const dmlite_location *loc)
Finishes a PUT.
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.
int dmlite_fseek(dmlite_fd *fd, off_t offset, int whence)
Sets the file position.
struct dmlite_fd dmlite_fd
Definition: io.h:25
ssize_t dmlite_fwrite(dmlite_fd *fd, const void *buffer, size_t count)
Writes to a file.
off_t dmlite_ftell(dmlite_fd *fd)
Returns the cursor position.
ssize_t dmlite_fwritev(dmlite_fd *fd, const struct iovec *vector, size_t count)
Reads from a file into multiple buffers.
ssize_t dmlite_fread(dmlite_fd *fd, void *buffer, size_t count)
Reads from a file.
ssize_t dmlite_freadv(dmlite_fd *fd, const struct iovec *vector, size_t count)
Reads from a file into multiple buffers.
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.
int dmlite_feof(dmlite_fd *fd)
Returns 1 if EOF.
int dmlite_fstat(dmlite_fd *fd, struct stat *buf)
Gets information about a file descriptor.
int dmlite_fileno(dmlite_fd *fd)
Returns the system file descriptor if available.
int dmlite_fclose(dmlite_fd *fd)
Closes a file.
Entry point for DMLite.
C wrapper for DMLite Pool API.
Collection of chunks that form a replica.
Definition: pool.h:42