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