dmlite  0.6
catalog.h
Go to the documentation of this file.
1 /** @file include/dmlite/c/catalog.h
2  * @brief C wrapper for DMLite Catalog API.
3  * @author Alejandro Álvarez Ayllon <aalvarez@cern.ch>
4  */
5 #ifndef DMLITE_CATALOG_H
6 #define DMLITE_CATALOG_H
7 
8 #include "dmlite.h"
9 #include "inode.h"
10 #include "utils.h"
11 
12 #ifdef __cplusplus
13 extern "C" {
14 #endif
15 
16 typedef struct dmlite_dir dmlite_dir;
17 
18 /**
19  * @brief Changes the working dir.
20  * @param context The DM context.
21  * @param path The new working dir.
22  * @return 0 on success, error code otherwise.
23  */
24 int dmlite_chdir(dmlite_context* context, const char* path);
25 
26 /**
27  * @brief Gets the current working directory.
28  * @param context The DM context.
29  * @param buffer If not NULL, the path will be stored here. <b>malloc</b> will be used otherwise.
30  * @param size The buffer size.
31  * @return A pointer to a string with the current working dir.
32  */
33 char* dmlite_getcwd(dmlite_context* context, char* buffer, size_t size);
34 
35 /**
36  * @brief Sets the file mode creation mask.
37  * @param context The DM context.
38  * @param mask The new mask.
39  * @return The previous mask.
40  */
41 mode_t dmlite_umask(dmlite_context* context, mode_t mask);
42 
43 /**
44  * @brief Does a stat of a file or directory.
45  * @param context The DM context.
46  * @param path The path.
47  * @param buf Where to put the retrieved information.
48  * @return 0 on success, error code otherwise.
49  */
50 int dmlite_stat(dmlite_context* context, const char* path, struct stat* buf);
51 
52 /**
53  * @brief Does a stat of a file, directory, or symbolic link (does not follow).
54  * @param context The DM context.
55  * @param path The path.
56  * @param buf Where to put the retrieved information.
57  * @return 0 on success, error code otherwise.
58  */
59 int dmlite_statl(dmlite_context* context, const char* path, struct stat* buf);
60 
61 /**
62  * @brief Does an extended stat of a file, directory or symbolic link.
63  * @param context The DM context.
64  * @param path The path.
65  * @param buf Where to put the retrieved information.
66  * @return 0 on success, error code otherwise.
67  */
68 int dmlite_statx(dmlite_context* context, const char* path, dmlite_xstat* buf);
69 
70 /**
71  * @brief Does an extended stat of a logical file using an associated replica filename.
72  * @param context The DM context.
73  * @param rfn Replica filename.
74  * @param buf Where to put the retrieved information.
75  * @return 0 on success, error code otherwise.
76  */
77 int dmlite_rstatx(dmlite_context* context, const char* rfn, dmlite_xstat* buf);
78 
79 /**
80  * @brief Checks wether the process would be allowed to read, write, or check existence.
81  * @param context The DM context.
82  * @param lfn Logical filename.
83  * @param mode A mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.
84  * @return 0 on success, error code otherwise.
85  */
86 int dmlite_access(dmlite_context* context, const char* lfn, int mode);
87 
88 /**
89  * @brief Checks wether the process would be allowed to read, write, or check existence.
90  * @param context The DM context.
91  * @param rfn Replica filename.
92  * @param mode A mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.
93  * @return 0 on success, error code otherwise.
94  */
95 int dmlite_accessr(dmlite_context* context, const char* rfn, int mode);
96 
97 /**
98  * @brief Adds a new replica to an entry.
99  * @param context The DM context.
100  * @param replica The replica to add.
101  * @return 0 on success, error code otherwise.
102  */
103 int dmlite_addreplica(dmlite_context* context, const dmlite_replica* replica);
104 
105 /**
106  * @brief Deletes a replica.
107  * @param context The DM context.
108  * @param replica The replica to delete.
109  * @return 0 on success, error code otherwise.
110  */
111 int dmlite_delreplica(dmlite_context* context, const dmlite_replica* replica);
112 
113 /**
114  * @brief Gets the replicas of a file.
115  * @param context The DM context.
116  * @param path The logical file name.
117  * @param nReplicas The number of entries will be put here.
118  * @param fileReplicas An array with nEntries elements will be stored here. <b>Use dmlite_replicas_free to free it.</b>
119  * @return 0 on success, error code otherwise.
120  */
121 int dmlite_getreplicas(dmlite_context* context, const char* path, unsigned *nReplicas,
122  dmlite_replica** fileReplicas);
123 
124 /**
125  * @brief Frees a replica list.
126  * @param nReplicas The number of replicas contained in the array.
127  * @param fileReplicas The array to free.
128  * @return 0 on success, error code otherwise.
129  */
130 int dmlite_replicas_free(unsigned nReplicas, dmlite_replica* fileReplicas);
131 
132 /**
133  * @brief Creates a symlink
134  * @param context The DM context.
135  * @param oldPath The old path.
136  * @param newPath The new path.
137  * @return 0 on success, error code otherwise.
138  */
139 int dmlite_symlink(dmlite_context* context,
140  const char* oldPath, const char* newPath);
141 
142 /**
143  * @brief Reads a symlink.
144  * @param context The DM context.
145  * @param path The symlink file.
146  * @param buf Where to put the symlink target.
147  * @param bufsize The size of the memory pointed by buf.
148  * @return 0 on success, error code otherwise.
149  */
150 int dmlite_readlink(dmlite_context* context, const char* path,
151  char* buf, size_t bufsize);
152 
153 /**
154  * @brief Removes a file.
155  * @param context The DM context.
156  * @param path The logical file name.
157  * @return 0 on success, error code otherwise.
158  */
159 int dmlite_unlink(dmlite_context* context, const char* path);
160 
161 
162 /**
163  * @brief Creates a file in the catalog (no replicas).
164  * @param context The DM context.
165  * @param path The logical file name.
166  * @param mode The creation mode.
167  * @return 0 on success, error code otherwise.
168  */
169 int dmlite_create(dmlite_context* context, const char* path, mode_t mode);
170 
171 /**
172  * @brief Changes the mode of a file or directory.
173  * @param context The DM context.
174  * @param path The logical path.
175  * @param mode The new mode.
176  * @return 0 on success, error code otherwise.
177  */
178 int dmlite_chmod(dmlite_context* context, const char* path, mode_t mode);
179 
180 /**
181  * @brief Changes the owner of a file or directory.
182  * @param context The DM context.
183  * @param path The logical path.
184  * @param newUid The new owner.
185  * @param newGid The new group.
186  * @return 0 on success, error code otherwise.
187  */
188 int dmlite_chown(dmlite_context* context, const char* path, uid_t newUid, gid_t newGid);
189 
190 /**
191  * @brief Changes the owner of a file, directory or symlink (does not follow).
192  * @param context The DM context.
193  * @param path The logical path.
194  * @param newUid The new owner.
195  * @param newGid The new group.
196  * @return 0 on success, error code otherwise.
197  */
198 int dmlite_lchown(dmlite_context* context, const char* path, uid_t newUid, gid_t newGid);
199 
200 /**
201  * @brief Changes the size of a file in the catalog.
202  * @param context The DM context.
203  * @param path The logical path.
204  * @param filesize The new file size.
205  * @return 0 on success, error code otherwise.
206  */
207 int dmlite_setfsize(dmlite_context* context, const char* path, uint64_t filesize);
208 
209 /**
210  * @brief Changes the size and checksum of a file in the catalog.
211  * @param context The DM context.
212  * @param path The logical path.
213  * @param filesize The new file size.
214  * @param csumtype The new checksum type (CS, AD or MD).
215  * @param csumvalue The new checksum value.
216  * @return 0 on success, error code otherwise.
217  */
218 int dmlite_setfsizec(dmlite_context* context, const char* path, uint64_t filesize,
219  const char* csumtype, const char* csumvalue);
220 /**
221  * @brief Gets the checksum of a file in the catalog.
222  * @param context The DM context.
223  * @param path The logical path.
224  * @param csumtype The wanted checksum type (CS, AD or MD. We can also pass a long checksum name (e.g. checksum.adler32))
225  * @param csumvalue The wanted checksum value will be written into this string. Make sure it has enough space.
226  * @param maxcksumlen Max allowed length for a checksum, to avoid buffer overflows.
227  * @param pfn Optional: the corresponding replica for which to calculate a checksum
228  * @param forcerecalc True if nonzero. Force recalculation of the checksum (may take long and return EAGAIN)
229  * @param waitsecs Seconds to wait for a checksum to be calculated. Returns EAGAIN if timeouts. Set to 0 for blocking behavior.
230  * @return 0 on success, error code otherwise.
231  */
232 
233 int dmlite_getchecksum(dmlite_context* context, const char* path,
234  const char* csumtype, char* csumvalue, const int maxcksumlen,
235  const char* pfn, const int forcerecalc, const int waitsecs);
236 
237 /**
238  * @brief Changes the ACL of a file.
239  * @param context The DM context.
240  * @param path The logical path.
241  * @param nEntries The number of entries in the acl array.
242  * @param acl An ACL array.
243  * @return 0 on success, error code otherwise.
244  */
245 
246 
247 int dmlite_setacl(dmlite_context* context, const char* path, unsigned nEntries, dmlite_aclentry* acl);
248 
249 /**
250  * @brief Changes access and/or modification time
251  * @param context The DM context.
252  * @param path The file path.
253  * @param buf A struct holding the new times.
254  * @return 0 on success, error code otherwise.
255  */
256 int dmlite_utime(dmlite_context* context, const char* path, const struct utimbuf* buf);
257 
258 /**
259  * @brief Gets the comment associated with a file.
260  * @param context The DM context.
261  * @param path The logical path.
262  * @param comment Where to put the retrieved comment. It must be at least of size COMMENT_MAX.
263  * @param bufsize Size of the memory zone pointed by comment.
264  * @return 0 on success, error code otherwise.
265  */
266 int dmlite_getcomment(dmlite_context* context, const char* path,
267  char* comment, size_t bufsize);
268 
269 /**
270  * @brief Sets the comment associated with a file.
271  * @param context The DM context.
272  * @param path The logical path.
273  * @param comment The comment to associate. '\\0' terminated string.
274  * @return 0 on success, error code otherwise.
275  */
276 int dmlite_setcomment(dmlite_context* context, const char* path, const char* comment);
277 
278 /**
279  * @brief Sets the file Grid Unique Identifier.
280  * @param context The DM context.
281  * @param path The logical path.
282  * @param guid The new GUID.
283  * @return 0 on success, error code otherwise.
284  */
285 int dmlite_setguid(dmlite_context* context, const char* path, const char* guid);
286 
287 /**
288  * @brief Updates the file extended attributes.
289  * @param context The DM context.
290  * @param path The logical path.
291  * @param xattr The new set of extended attributes.
292  * @return 0 on success, error code otherwise.
293  */
294 int dmlite_update_xattr(dmlite_context* context, const char* path,
295  const dmlite_any_dict* xattr);
296 
297 /**
298  * @brief Gets the id of a group.
299  * @param context The DM context.
300  * @param groupName The group name.
301  * @param gid Where to put the group ID.
302  * @return 0 on success, error code otherwise.
303  */
304 int dmlite_getgrpbynam(dmlite_context* context, const char* groupName, gid_t* gid);
305 
306 /**
307  * @brief Get the user id.
308  * @param context The DM context.
309  * @param userName The user name.
310  * @param uid Where to put the user ID.
311  * @return 0 on success, error code otherwise.
312  */
313 int dmlite_getusrbynam(dmlite_context* context, const char* userName, uid_t* uid);
314 
315 /**
316  * @brief Opens a directory to read it later.
317  * @param context The DM context.
318  * @param path The directory to open.
319  * @return A pointer to an internal structure, or NULL on failure.
320  */
321 dmlite_dir* dmlite_opendir(dmlite_context* context, const char* path);
322 
323 /**
324  * @brief Closes a directory and free the internal structures.
325  * @param context The DM context.
326  * @param dir The pointer returned by dmlite_opendir.
327  * @return 0 on success, error code otherwise.
328  */
329 int dmlite_closedir(dmlite_context* context, dmlite_dir* dir);
330 
331 /**
332  * @brief Reads an entry from a directory.
333  * @param context The DM context.
334  * @param dir The pointer returned by dmlite_opendir.
335  * @return A pointer to a struct with the recovered data.
336  * NULL on failure, or end of dir. If an error occurred,
337  * dm_errno(context) will be different than 0.
338  * @note The pointer is internally allocated. Do not free it.
339  */
340 struct dirent *dmlite_readdir(dmlite_context* context, dmlite_dir* dir);
341 
342 /**
343  * @brief Reads an entry from a directory (extended data).
344  * @param context The DM context.
345  * @param dir The pointer returned by dmlite_opendir.
346  * @return A pointer to a struct with the recovered data.
347  * NULL on failure, or end of dir. If an error occurred,
348  * dm_errno(context) will be different than 0.
349  * @note The pointer is internally allocated. Do not free it.
350  */
352 
353 /**
354  * @brief Creates a new directory.
355  * @param context The DM context.
356  * @param path The directory for the new path. All the precedent folders must exist.
357  * @param mode Permissions to use for the creation.
358  * @return 0 on success, error code otherwise.
359  */
360 int dmlite_mkdir(dmlite_context* context, const char* path, mode_t mode);
361 
362 /**
363  * @brief Renames a file, directory or symlink.
364  * @param context The DM context.
365  * @param oldPath The old name.
366  * @param newPath The new name.
367  * @return 0 on success, error code otherwise.
368  */
369 int dmlite_rename(dmlite_context* context, const char* oldPath, const char* newPath);
370 
371 /**
372  * @brief Deletes a directory. It must be empty.
373  * @param context The DM context.
374  * @param path The directory to remove.
375  * @return 0 on success, error code otherwise.
376  */
377 int dmlite_rmdir(dmlite_context* context, const char* path);
378 
379 /**
380  * @brief Gets a specific replica.
381  * @param context The DM context.
382  * @param rfn The replica file name.
383  * @param replica A buffer where the retrieved data will be put.
384  * @return 0 on success, error code otherwise.
385  */
386 int dmlite_getreplica_by_rfn(dmlite_context* context, const char* rfn, dmlite_replica* replica);
387 
388 /**
389  * @brief Updates a replica.
390  * @param context The DM context.
391  * @param replica The replica to modify.
392  * @return 0 on success, error code otherwise.
393  */
394 int dmlite_updatereplica(dmlite_context* context, const dmlite_replica* replica);
395 
396 #ifdef __cplusplus
397 }
398 #endif
399 
400 #endif /* DMLITE_CATALOG_H */
int dmlite_setfsize(dmlite_context *context, const char *path, uint64_t filesize)
Changes the size of a file in the catalog.
int dmlite_setfsizec(dmlite_context *context, const char *path, uint64_t filesize, const char *csumtype, const char *csumvalue)
Changes the size and checksum of a file in the catalog.
int dmlite_getgrpbynam(dmlite_context *context, const char *groupName, gid_t *gid)
Gets the id of a group.
int dmlite_utime(dmlite_context *context, const char *path, const struct utimbuf *buf)
Changes access and/or modification time.
Definition: inode.h:33
int dmlite_accessr(dmlite_context *context, const char *rfn, int mode)
Checks wether the process would be allowed to read, write, or check existence.
int dmlite_symlink(dmlite_context *context, const char *oldPath, const char *newPath)
Creates a symlink.
int dmlite_chown(dmlite_context *context, const char *path, uid_t newUid, gid_t newGid)
Changes the owner of a file or directory.
struct dmlite_any_dict dmlite_any_dict
Handles key->value pairs.
Definition: any.h:25
int dmlite_unlink(dmlite_context *context, const char *path)
Removes a file.
int dmlite_getcomment(dmlite_context *context, const char *path, char *comment, size_t bufsize)
Gets the comment associated with a file.
int dmlite_setcomment(dmlite_context *context, const char *path, const char *comment)
Sets the comment associated with a file.
int dmlite_delreplica(dmlite_context *context, const dmlite_replica *replica)
Deletes a replica.
C wrapper for DMLite.
Definition: inode.h:65
int dmlite_chmod(dmlite_context *context, const char *path, mode_t mode)
Changes the mode of a file or directory.
int dmlite_readlink(dmlite_context *context, const char *path, char *buf, size_t bufsize)
Reads a symlink.
int dmlite_access(dmlite_context *context, const char *lfn, int mode)
Checks wether the process would be allowed to read, write, or check existence.
struct dmlite_dir dmlite_dir
Definition: catalog.h:16
dmlite_dir * dmlite_opendir(dmlite_context *context, const char *path)
Opens a directory to read it later.
C wrapper for DMLite utils.
dmlite_xstat * dmlite_readdirx(dmlite_context *context, dmlite_dir *dir)
Reads an entry from a directory (extended data).
mode_t dmlite_umask(dmlite_context *context, mode_t mask)
Sets the file mode creation mask.
int dmlite_stat(dmlite_context *context, const char *path, struct stat *buf)
Does a stat of a file or directory.
int dmlite_replicas_free(unsigned nReplicas, dmlite_replica *fileReplicas)
Frees a replica list.
struct dirent * dmlite_readdir(dmlite_context *context, dmlite_dir *dir)
Reads an entry from a directory.
struct dmlite_context dmlite_context
Handle for a initialized context.
Definition: dmlite.h:23
int dmlite_addreplica(dmlite_context *context, const dmlite_replica *replica)
Adds a new replica to an entry.
int dmlite_rename(dmlite_context *context, const char *oldPath, const char *newPath)
Renames a file, directory or symlink.
int dmlite_create(dmlite_context *context, const char *path, mode_t mode)
Creates a file in the catalog (no replicas).
int dmlite_setacl(dmlite_context *context, const char *path, unsigned nEntries, dmlite_aclentry *acl)
Changes the ACL of a file.
int dmlite_getreplica_by_rfn(dmlite_context *context, const char *rfn, dmlite_replica *replica)
Gets a specific replica.
int dmlite_setguid(dmlite_context *context, const char *path, const char *guid)
Sets the file Grid Unique Identifier.
int dmlite_chdir(dmlite_context *context, const char *path)
Changes the working dir.
int dmlite_mkdir(dmlite_context *context, const char *path, mode_t mode)
Creates a new directory.
int dmlite_updatereplica(dmlite_context *context, const dmlite_replica *replica)
Updates a replica.
int dmlite_closedir(dmlite_context *context, dmlite_dir *dir)
Closes a directory and free the internal structures.
int dmlite_getreplicas(dmlite_context *context, const char *path, unsigned *nReplicas, dmlite_replica **fileReplicas)
Gets the replicas of a file.
Handles ACL entries.
Definition: utils.h:48
char * dmlite_getcwd(dmlite_context *context, char *buffer, size_t size)
Gets the current working directory.
int dmlite_getusrbynam(dmlite_context *context, const char *userName, uid_t *uid)
Get the user id.
int dmlite_rstatx(dmlite_context *context, const char *rfn, dmlite_xstat *buf)
Does an extended stat of a logical file using an associated replica filename.
int dmlite_getchecksum(dmlite_context *context, const char *path, const char *csumtype, char *csumvalue, const int maxcksumlen, const char *pfn, const int forcerecalc, const int waitsecs)
Gets the checksum of a file in the catalog.
int dmlite_update_xattr(dmlite_context *context, const char *path, const dmlite_any_dict *xattr)
Updates the file extended attributes.
int dmlite_rmdir(dmlite_context *context, const char *path)
Deletes a directory. It must be empty.
int dmlite_statl(dmlite_context *context, const char *path, struct stat *buf)
Does a stat of a file, directory, or symbolic link (does not follow).
C wrapper for DMLite INode API.
int dmlite_statx(dmlite_context *context, const char *path, dmlite_xstat *buf)
Does an extended stat of a file, directory or symbolic link.
int dmlite_lchown(dmlite_context *context, const char *path, uid_t newUid, gid_t newGid)
Changes the owner of a file, directory or symlink (does not follow).