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