dmlite  0.6
inode.h
Go to the documentation of this file.
1 /** @file include/dmlite/c/inode.h
2  * @brief C wrapper for DMLite INode API.
3  * @author Alejandro Álvarez Ayllon <aalvarez@cern.ch>
4  * @note This is a low-level API, so security checks will NOT be done.
5  */
6 #ifndef DMLITE_INODE_H
7 #define DMLITE_INODE_H
8 
9 #include "dmlite.h"
10 #include "any.h"
11 #include "utils.h"
12 #include <stdint.h>
13 
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17 
18 /** Possible replica statuses */
22  };
23 /** Possible replica types */
25  kPermanent = 'P'
26  };
27 
28 /** A replica of a file */
29 typedef struct dmlite_replica {
30  int64_t replicaid;
31  int64_t fileid;
32 
33  int64_t nbaccesses;
34  time_t atime;
35  time_t ptime;
36  time_t ltime;
37 
40 
42  char rfn [URL_MAX];
43 
44  dmlite_any_dict* extra; /**< @brief If != NULL, additional metadata will be
45  * put here.
46  * @details Caller is generally responsible for
47  * allocating and freeing. Exception:
48  * when an array is allocated by the called
49  * method */
51 
52 /** Posible file statuses */
54  kMigrated = 'm'
55  };
56 
57 /** File metadata */
58 typedef struct dmlite_xstat {
59  ino_t parent;
60  struct stat stat;
62  char name [NAME_MAX];
63  char guid [GUID_MAX];
67 
68  dmlite_any_dict* extra; /**< @brief If != NULL, additional metadata will be
69  * put here.
70  * @details Caller is responsible for allocating
71  * and freeing*/
72 } dmlite_xstat;
73 
74 /** Opaque directory handler */
75 typedef struct dmlite_idir dmlite_idir;
76 
77 /**
78  * @brief Starts a transaction.
79  * @details Depending on the plugin stack, it can be possible to nest
80  * several calls.
81  * @param context The DM context.
82  * @return 0 on success, error code otherwise.
83  */
84 int dmlite_ibegin(dmlite_context* context);
85 
86 /**
87  * @brief Commits the changes.
88  * @details Depending on the plugin stack, it can be possible to nest
89  * several calls, and there must be one icommit per ibegin
90  * for the changes to be permanent.
91  * @param context The DM context.
92  * @return 0 on success, error code otherwise.
93  */
94 int dmlite_icommit(dmlite_context* context);
95 
96 /**
97  * @brief Undo the changes.
98  * @details If several ibegin were nested, all the transactions will
99  * be probable be undone, regardless on the nesting level.
100  * @param context The DM context.
101  * @return 0 on success, error code otherwise.
102  */
103 int dmlite_irollback(dmlite_context* context);
104 
105 /**
106  * @brief Creates a new file.
107  * @param context The DM context.
108  * @param f Only some fields from this struct will be used. That would depend
109  * on the plugin, but usually it will be: parent, name, mode, uid, gid,
110  * size, status, checksum and ACL.
111  * @return 0 on success, error code otherwise.
112  * @note mode will probably be used raw (i.e. no cleanup or set of format bits)
113  */
114 int dmlite_icreate(dmlite_context* context, const dmlite_xstat* f);
115 
116 /**
117  * @brief Associates a symlink with an existing file.
118  * @param context The DM context.
119  * @param inode The file that will be a symlink.
120  * @param link The destination link.
121  * @return 0 on success, error code otherwise.
122  */
123 int dmlite_isymlink(dmlite_context* context, ino_t inode, const char* link);
124 
125 /**
126  * @brief Removes a file or directory from the database.
127  * @param context The DM context.
128  * @param inode The id of the entry to remove.
129  * @return 0 on success, error code otherwise.
130  * @note Not empty directories, or files will replicas may fail.
131  */
132 int dmlite_iunlink(dmlite_context* context, ino_t inode);
133 
134 /**
135  * @brief Moves a file to a different parent directory.
136  * @param context The DM context.
137  * @param inode The file id.
138  * @param dest The destination id.
139  * @return 0 on success, error code otherwise.
140  */
141 int dmlite_imove(dmlite_context* context, ino_t inode, ino_t dest);
142 
143 /**
144  * @brief Changes the name of an entry.
145  * @param context The DM context.
146  * @param inode The file id.
147  * @param name The new name.
148  * @return 0 on success, error code otherwise.
149  */
150 int dmlite_irename(dmlite_context* context, ino_t inode, const char* name);
151 
152 /**
153  * @brief Does a stat of an entry using the inode instead of the path.
154  * @param context The DM context.
155  * @param inode The entry inode.
156  * @param buf Where to put the retrieved information.
157  * @return 0 on success, error code otherwise.
158  * @note Security checks won't be done if you use this function,
159  * so keep in mind doing it yourself.
160  */
161 int dmlite_istat(dmlite_context* context, ino_t inode, struct stat* buf);
162 
163 /**
164  * @brief Does an extended stat of an entry using the inode instead of
165  * the path.
166  * @param context The DM context.
167  * @param inode The entry inode.
168  * @param buf Where to put the retrieved information.
169  * @return 0 on success, error code otherwise.
170  * @note Security checks won't be done if you use this function,
171  * so keep in mind doing it yourself.
172  */
173 int dmlite_istatx(dmlite_context* context, ino_t inode, dmlite_xstat* buf);
174 
175 /**
176  * @brief Does an extended stat using the parent inode and the entry name.
177  * @param context The DM context.
178  * @param parent The parent id.
179  * @param name The entry name.
180  * @param buf Where to put the retrieved information.
181  * @return 0 on success, error code otherwise.
182  */
183 int dmlite_istatx_by_name(dmlite_context* context, ino_t parent, const char* name,
184  dmlite_xstat* buf);
185 
186 /**
187  * @brief Reads a symbolic link.
188  * @param context The DM context.
189  * @param inode The file id.
190  * @param path The link will be put here.
191  * @param bufsize The size of the memory area pointed by path.
192  * @return 0 on success, error code otherwise.
193  */
194 int dmlite_ireadlink(dmlite_context* context, ino_t inode,
195  char* path, size_t bufsize);
196 
197 /**
198  * @brief Adds a new replica.
199  * @param context The DM context.
200  * @param replica The replica to add. replica->fileid must point to a valid file.
201  * @return 0 on success, error code otherwise.
202  */
203 int dmlite_iaddreplica(dmlite_context* context, const dmlite_replica* replica);
204 
205 /**
206  * @brief Deletes a replica.
207  * @param context The DM context.
208  * @param replica The replica to remove.
209  * @return 0 on success, error code otherwise.
210  */
211 int dmlite_ideletereplica(dmlite_context* context, const dmlite_replica* replica);
212 
213 /**
214  * @brief Gets a specific replica using its replica id.
215  * @param context The DM context.
216  * @param rid The replica id.
217  * @param buf Where to put the retrieved data.
218  * @return 0 on success, error code otherwise.
219  */
220 int dmlite_igetreplica(dmlite_context* context, int64_t rid, dmlite_replica* buf);
221 
222 /**
223  * @brief Gets all the replicas associated to a file.
224  * @param context The DM context.
225  * @param inode The file id.
226  * @param nreplicas The number of replicas will be put here.
227  * @param replicas It will be initialized to an array of nreplicas replicas.
228  * Free it with <b>dmlite_replicas_free</b>.
229  * @return 0 on success, error code otherwise.
230  */
231 int dmlite_igetreplicas(dmlite_context* context, ino_t inode,
232  unsigned* nreplicas, dmlite_replica** replicas);
233 
234 /**
235  * @brief Sets the access and modification time.
236  * @param context The DM context.
237  * @param inode The file id.
238  * @param buf The timestamps.
239  * @return 0 on success, error code otherwise.
240  */
241 int dmlite_iutime(dmlite_context* context, ino_t inode,
242  const struct utimbuf* buf);
243 
244 /**
245  * @brief Sets the mode and ACL of a file.
246  * @param context The DM context.
247  * @param inode The file id.
248  * @param uid The new UID.
249  * @param gid The new GID.
250  * @param mode The new mode.
251  * @param nentries The number of acl entries.
252  * @param acl The new ACL.
253  * @return 0 on success, error code otherwise.
254  * @note This call may not validate that uid, gid, mode and acl
255  * are coherent.
256  */
257 int dmlite_isetmode(dmlite_context* context, ino_t inode, uid_t uid, gid_t gid,
258  mode_t mode, unsigned nentries, dmlite_aclentry* acl);
259 
260 /**
261  * @brief Sets the size of a file.
262  * @param context The DM context.
263  * @param inode The file id.
264  * @param size The new size.
265  * @return 0 on success, error code otherwise.
266  */
267 int dmlite_isetsize(dmlite_context* context, ino_t inode, size_t size);
268 
269 /**
270  * @brief Sets the checksum of a file.
271  * @param context The DM context.
272  * @param inode The file id.
273  * @param csumtype The new checksum type.
274  * @param csumvalue The new checksum value.
275  * @return 0 on success, error code otherwise.
276  */
277 int dmlite_isetchecksum(dmlite_context* context, ino_t inode,
278  const char* csumtype, const char* csumvalue);
279 
280 /**
281  * @brief Gets the comment associated with an entry.
282  * @param context The DM context.
283  * @param inode The file id.
284  * @param comment Where to put the comment.
285  * @param bufsize The size of the memory pointed by comment.
286  * @return 0 on success, error code otherwise.
287  */
288 int dmlite_igetcomment(dmlite_context* context, ino_t inode,
289  char* comment, size_t bufsize);
290 
291 /**
292  * @brief Sets the comment associated with an entry.
293  * @param context The DM context.
294  * @param inode The file id.
295  * @param comment The new comment.
296  * @return 0 on success, error code otherwise.
297  */
298 int dmlite_isetcomment(dmlite_context* context, ino_t inode,
299  const char* comment);
300 
301 /**
302  * @brief Deletes the comment associated with an entry.
303  * @param context The DM context.
304  * @param inode The file id.
305  * @return 0 on success, error code otherwise.
306  */
307 int dmlite_ideletecomment(dmlite_context* context, ino_t inode);
308 
309 /**
310  * @brief Sets the file Grid Unique Identifier.
311  * @param context The DM context.
312  * @param inode The entry id.
313  * @param guid The new GUID.
314  * @return 0 on success, error code otherwise.
315  */
316 int dmlite_isetguid(dmlite_context* context, ino_t inode, const char* guid);
317 
318 /**
319  * @brief Updates the file extended attributes.
320  * @param context The DM context.
321  * @param inode The entry id.
322  * @param xattr The new set of extended attributes.
323  * @return 0 on success, error code otherwise.
324  */
325 int dmlite_iupdate_xattr(dmlite_context* context, ino_t inode,
326  const dmlite_any_dict* xattr);
327 
328 /**
329  * @brief Opens a directory.
330  * @param context The DM context.
331  * @param inode The directory ID.
332  * @return NULL on failure. A pointer to an internal struct to be used
333  * with dmlite_ireaddir*
334  */
335 dmlite_idir* dmlite_iopendir(dmlite_context* context, ino_t inode);
336 
337 /**
338  * @brief Closes a directory, freeing any internally allocated memory.
339  * @param context The DM context.
340  * @param dir The directory to close, as returned by dmlite_opendir.
341  * @return 0 on success, error code otherwise.
342  */
343 int dmlite_iclosedir(dmlite_context* context, dmlite_idir* dir);
344 
345 /**
346  * @brief Reads a directory. Extended data.
347  * @param context The DM context.
348  * @param dir The directory to read, as returned by dmlite_opendir.
349  * @return A pointer to a struct with the recovered data.
350  * NULL on failure, or end of dir. If an error occurred,
351  * dm_errno(context) will be different than 0.
352  * @note The pointer is internally allocated. Do not free it.
353  */
355 
356 /**
357  * @brief Reads a directory.
358  * @param context The DM context.
359  * @param dir The directory to read, as returned by dmlite_opendir.
360  * @return A pointer to a struct with the recovered data.
361  * NULL on failure, or end of dir. If an error occurred,
362  * dm_errno(context) will be different than 0.
363  * @note The pointer is internally allocated. Do not free it.
364  */
365 struct dirent* dmlite_ireaddir(dmlite_context* context, dmlite_idir* dir);
366 
367 #ifdef __cplusplus
368 }
369 #endif
370 
371 #endif /* DMLITE_INODE_H */
#define URL_MAX
Definition: utils.h:24
#define CSUMVALUE_MAX
Definition: utils.h:17
time_t ltime
Definition: inode.h:36
int dmlite_iclosedir(dmlite_context *context, dmlite_idir *dir)
Closes a directory, freeing any internally allocated memory.
int dmlite_ireadlink(dmlite_context *context, ino_t inode, char *path, size_t bufsize)
Reads a symbolic link.
Definition: inode.h:29
int dmlite_istatx_by_name(dmlite_context *context, ino_t parent, const char *name, dmlite_xstat *buf)
Does an extended stat using the parent inode and the entry name.
int dmlite_iaddreplica(dmlite_context *context, const dmlite_replica *replica)
Adds a new replica.
struct stat stat
Definition: inode.h:60
dmlite_replica_status
Definition: inode.h:19
struct dmlite_any_dict dmlite_any_dict
Handles key-&gt;value pairs.
Definition: any.h:25
int64_t replicaid
Definition: inode.h:30
int dmlite_ibegin(dmlite_context *context)
Starts a transaction.
int dmlite_iutime(dmlite_context *context, ino_t inode, const struct utimbuf *buf)
Sets the access and modification time.
Definition: inode.h:19
int dmlite_isetguid(dmlite_context *context, ino_t inode, const char *guid)
Sets the file Grid Unique Identifier.
#define ACL_SIZE
Definition: utils.h:15
C wrapper for DMLite.
int dmlite_iupdate_xattr(dmlite_context *context, ino_t inode, const dmlite_any_dict *xattr)
Updates the file extended attributes.
Definition: inode.h:58
enum dmlite_replica_status status
Definition: inode.h:38
char name[NAME_MAX]
Definition: inode.h:62
char acl[ACL_ENTRIES_MAX *ACL_SIZE]
Definition: inode.h:66
int dmlite_ideletereplica(dmlite_context *context, const dmlite_replica *replica)
Deletes a replica.
struct dmlite_xstat dmlite_xstat
enum dmlite_file_status status
Definition: inode.h:61
C wrapper for DMLite utils.
#define CSUMTYPE_MAX
Definition: utils.h:16
Definition: inode.h:54
dmlite_idir * dmlite_iopendir(dmlite_context *context, ino_t inode)
Opens a directory.
char rfn[URL_MAX]
Definition: inode.h:42
time_t ptime
Definition: inode.h:35
dmlite_file_status
Definition: inode.h:53
dmlite_any_dict * extra
If != NULL, additional metadata will be put here.
Definition: inode.h:44
char csumvalue[CSUMVALUE_MAX]
Definition: inode.h:65
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
char csumtype[CSUMTYPE_MAX]
Definition: inode.h:64
dmlite_xstat * dmlite_ireaddirx(dmlite_context *context, dmlite_idir *dir)
Reads a directory. Extended data.
int dmlite_isetcomment(dmlite_context *context, ino_t inode, const char *comment)
Sets the comment associated with an entry.
int dmlite_isymlink(dmlite_context *context, ino_t inode, const char *link)
Associates a symlink with an existing file.
dmlite_any_dict * extra
If != NULL, additional metadata will be put here.
Definition: inode.h:68
time_t atime
Definition: inode.h:34
enum dmlite_replica_type type
Definition: inode.h:39
ino_t parent
Definition: inode.h:59
struct dmlite_idir dmlite_idir
Definition: inode.h:75
char server[HOST_NAME_MAX]
Definition: inode.h:41
Definition: inode.h:24
int dmlite_isetchecksum(dmlite_context *context, ino_t inode, const char *csumtype, const char *csumvalue)
Sets the checksum of a file.
int dmlite_irollback(dmlite_context *context)
Undo the changes.
int64_t fileid
Definition: inode.h:31
#define ACL_ENTRIES_MAX
Definition: utils.h:14
int dmlite_imove(dmlite_context *context, ino_t inode, ino_t dest)
Moves a file to a different parent directory.
int dmlite_icommit(dmlite_context *context)
Commits the changes.
Handles ACL entries.
Definition: utils.h:48
#define HOST_NAME_MAX
Definition: utils.h:20
int dmlite_igetcomment(dmlite_context *context, ino_t inode, char *comment, size_t bufsize)
Gets the comment associated with an entry.
Definition: inode.h:25
int dmlite_icreate(dmlite_context *context, const dmlite_xstat *f)
Creates a new file.
Definition: inode.h:21
int dmlite_isetsize(dmlite_context *context, ino_t inode, size_t size)
Sets the size of a file.
int dmlite_istatx(dmlite_context *context, ino_t inode, dmlite_xstat *buf)
Does an extended stat of an entry using the inode instead of the path.
int64_t nbaccesses
Definition: inode.h:33
struct dirent * dmlite_ireaddir(dmlite_context *context, dmlite_idir *dir)
Reads a directory.
dmlite_replica_type
Definition: inode.h:24
int dmlite_isetmode(dmlite_context *context, ino_t inode, uid_t uid, gid_t gid, mode_t mode, unsigned nentries, dmlite_aclentry *acl)
Sets the mode and ACL of a file.
int dmlite_igetreplica(dmlite_context *context, int64_t rid, dmlite_replica *buf)
Gets a specific replica using its replica id.
char guid[GUID_MAX]
Definition: inode.h:63
Definition: inode.h:20
int dmlite_igetreplicas(dmlite_context *context, ino_t inode, unsigned *nreplicas, dmlite_replica **replicas)
Gets all the replicas associated to a file.
int dmlite_istat(dmlite_context *context, ino_t inode, struct stat *buf)
Does a stat of an entry using the inode instead of the path.
Definition: inode.h:53
struct dmlite_replica dmlite_replica
int dmlite_irename(dmlite_context *context, ino_t inode, const char *name)
Changes the name of an entry.
#define GUID_MAX
Definition: utils.h:18
int dmlite_iunlink(dmlite_context *context, ino_t inode)
Removes a file or directory from the database.
int dmlite_ideletecomment(dmlite_context *context, ino_t inode)
Deletes the comment associated with an entry.