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