dmlite  0.4
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 Adds a new replica to an entry.
72  * @param context The DM context.
73  * @param replica The replica to add.
74  * @return 0 on success, error code otherwise.
75  */
76 int dmlite_addreplica(dmlite_context* context, const dmlite_replica* replica);
77 
78 /**
79  * @brief Deletes a replica.
80  * @param context The DM context.
81  * @param replica The replica to delete.
82  * @return 0 on success, error code otherwise.
83  */
84 int dmlite_delreplica(dmlite_context* context, const dmlite_replica* replica);
85 
86 /**
87  * @brief Gets the replicas of a file.
88  * @param context The DM context.
89  * @param path The logical file name.
90  * @param nReplicas The number of entries will be put here.
91  * @param fileReplicas An array with nEntries elements will be stored here. <b>Use dmlite_replicas_free to free it.</b>
92  * @return 0 on success, error code otherwise.
93  */
94 int dmlite_getreplicas(dmlite_context* context, const char* path, unsigned *nReplicas,
95  dmlite_replica** fileReplicas);
96 
97 /**
98  * @brief Frees a replica list.
99  * @param context The DM context.
100  * @param nReplicas The number of replicas contained in the array.
101  * @param fileReplicas The array to free.
102  * @return 0 on success, error code otherwise.
103  */
105  unsigned nReplicas, dmlite_replica* fileReplicas);
106 
107 /**
108  * @brief Creates a symlink
109  * @param context The DM context.
110  * @param oldPath The old path.
111  * @param newPath The new path.
112  * @return 0 on success, error code otherwise.
113  */
114 int dmlite_symlink(dmlite_context* context,
115  const char* oldPath, const char* newPath);
116 
117 /**
118  * @brief Reads a symlink.
119  * @param context The DM context.
120  * @param path The symlink file.
121  * @param buf Where to put the symlink target.
122  * @param bufsize The size of the memory pointed by buf.
123  * @return 0 on success, error code otherwise.
124  */
125 int dmlite_readlink(dmlite_context* context, const char* path,
126  char* buf, size_t bufsize);
127 
128 /**
129  * @brief Removes a file.
130  * @param context The DM context.
131  * @param path The logical file name.
132  * @return 0 on success, error code otherwise.
133  */
134 int dmlite_unlink(dmlite_context* context, const char* path);
135 
136 
137 /**
138  * @brief Creates a file in the catalog (no replicas).
139  * @param context The DM context.
140  * @param path The logical file name.
141  * @param mode The creation mode.
142  * @return 0 on success, error code otherwise.
143  */
144 int dmlite_create(dmlite_context* context, const char* path, mode_t mode);
145 
146 /**
147  * @brief Changes the mode of a file or directory.
148  * @param context The DM context.
149  * @param path The logical path.
150  * @param mode The new mode.
151  * @return 0 on success, error code otherwise.
152  */
153 int dmlite_chmod(dmlite_context* context, const char* path, mode_t mode);
154 
155 /**
156  * @brief Changes the owner of a file or directory.
157  * @param context The DM context.
158  * @param path The logical path.
159  * @param newUid The new owner.
160  * @param newGid The new group.
161  * @return 0 on success, error code otherwise.
162  */
163 int dmlite_chown(dmlite_context* context, const char* path, uid_t newUid, gid_t newGid);
164 
165 /**
166  * @brief Changes the owner of a file, directory or symlink (does not follow).
167  * @param context The DM context.
168  * @param path The logical path.
169  * @param newUid The new owner.
170  * @param newGid The new group.
171  * @return 0 on success, error code otherwise.
172  */
173 int dmlite_lchown(dmlite_context* context, const char* path, uid_t newUid, gid_t newGid);
174 
175 /**
176  * @brief Changes the size of a file in the catalog.
177  * @param context The DM context.
178  * @param path The logical path.
179  * @param filesize The new file size.
180  * @return 0 on success, error code otherwise.
181  */
182 int dmlite_setfsize(dmlite_context* context, const char* path, uint64_t filesize);
183 
184 /**
185  * @brief Changes the size and checksum of a file in the catalog.
186  * @param context The DM context.
187  * @param path The logical path.
188  * @param filesize The new file size.
189  * @param csumtype The new checksum type (CS, AD or MD).
190  * @param csumvalue The new checksum value.
191  * @return 0 on success, error code otherwise.
192  */
193 int dmlite_setfsizec(dmlite_context* context, const char* path, uint64_t filesize,
194  const char* csumtype, const char* csumvalue);
195 
196 /**
197  * @brief Changes the ACL of a file.
198  * @param context The DM context.
199  * @param path The logical path.
200  * @param nEntries The number of entries in the acl array.
201  * @param acl An ACL array.
202  * @return 0 on success, error code otherwise.
203  */
204 int dmlite_setacl(dmlite_context* context, const char* path, unsigned nEntries, dmlite_aclentry* acl);
205 
206 /**
207  * @brief Changes access and/or modification time
208  * @param context The DM context.
209  * @param path The file path.
210  * @param buf A struct holding the new times.
211  * @return 0 on success, error code otherwise.
212  */
213 int dmlite_utime(dmlite_context* context, const char* path, const struct utimbuf* buf);
214 
215 /**
216  * @brief Gets the comment associated with a file.
217  * @param context The DM context.
218  * @param path The logical path.
219  * @param comment Where to put the retrieved comment. It must be at least of size COMMENT_MAX.
220  * @param bufsize Size of the memory zone pointed by comment.
221  * @return 0 on success, error code otherwise.
222  */
223 int dmlite_getcomment(dmlite_context* context, const char* path,
224  char* comment, size_t bufsize);
225 
226 /**
227  * @brief Sets the comment associated with a file.
228  * @param context The DM context.
229  * @param path The logical path.
230  * @param comment The comment to associate. '\\0' terminated string.
231  * @return 0 on success, error code otherwise.
232  */
233 int dmlite_setcomment(dmlite_context* context, const char* path, const char* comment);
234 
235 /**
236  * @brief Sets the file Grid Unique Identifier.
237  * @param context The DM context.
238  * @param path The logical path.
239  * @param guid The new GUID.
240  * @return 0 on success, error code otherwise.
241  */
242 int dmlite_setguid(dmlite_context* context, const char* path, const char* guid);
243 
244 /**
245  * @brief Updates the file extended attributes.
246  * @param context The DM context.
247  * @param path The logical path.
248  * @param xattr The new set of extended attributes.
249  * @return 0 on success, error code otherwise.
250  */
251 int dmlite_update_xattr(dmlite_context* context, const char* path,
252  const dmlite_any_dict* xattr);
253 
254 /**
255  * @brief Gets the id of a group.
256  * @param context The DM context.
257  * @param groupName The group name.
258  * @param gid Where to put the group ID.
259  * @return 0 on success, error code otherwise.
260  */
261 int dmlite_getgrpbynam(dmlite_context* context, const char* groupName, gid_t* gid);
262 
263 /**
264  * @brief Get the user id.
265  * @param context The DM context.
266  * @param userName The user name.
267  * @param uid Where to put the user ID.
268  * @return 0 on success, error code otherwise.
269  */
270 int dmlite_getusrbynam(dmlite_context* context, const char* userName, uid_t* uid);
271 
272 /**
273  * @brief Opens a directory to read it later.
274  * @param context The DM context.
275  * @param path The directory to open.
276  * @return A pointer to an internal structure, or NULL on failure.
277  */
278 dmlite_dir* dmlite_opendir(dmlite_context* context, const char* path);
279 
280 /**
281  * @brief Closes a directory and free the internal structures.
282  * @param context The DM context.
283  * @param dir The pointer returned by dmlite_opendir.
284  * @return 0 on success, error code otherwise.
285  */
286 int dmlite_closedir(dmlite_context* context, dmlite_dir* dir);
287 
288 /**
289  * @brief Reads an entry from a directory.
290  * @param context The DM context.
291  * @param dir The pointer returned by dmlite_opendir.
292  * @return A pointer to a struct with the recovered data, or NULL on failure or end of directory. Do NOT free it.
293  */
294 struct dirent *dmlite_readdir(dmlite_context* context, dmlite_dir* dir);
295 
296 /**
297  * @brief Reads an entry from a directory (extended data).
298  * @param context The DM context.
299  * @param dir The pointer returned by dmlite_opendir.
300  * @return A pointer to a struct with the recovered data, or NULL on failure or end of directory. Do NOT free it.
301  */
303 
304 /**
305  * @brief Creates a new directory.
306  * @param context The DM context.
307  * @param path The directory for the new path. All the precedent folders must exist.
308  * @param mode Permissions to use for the creation.
309  * @return 0 on success, error code otherwise.
310  */
311 int dmlite_mkdir(dmlite_context* context, const char* path, mode_t mode);
312 
313 /**
314  * @brief Renames a file, directory or symlink.
315  * @param context The DM context.
316  * @param oldPath The old name.
317  * @param newPath The new name.
318  * @return 0 on success, error code otherwise.
319  */
320 int dmlite_rename(dmlite_context* context, const char* oldPath, const char* newPath);
321 
322 /**
323  * @brief Deletes a directory. It must be empty.
324  * @param context The DM context.
325  * @param path The directory to remove.
326  * @return 0 on success, error code otherwise.
327  */
328 int dmlite_rmdir(dmlite_context* context, const char* path);
329 
330 /**
331  * @brief Gets a specific replica.
332  * @param context The DM context.
333  * @param rfn The replica file name.
334  * @param replica A buffer where the retrieved data will be put.
335  * @return 0 on success, error code otherwise.
336  */
337 int dmlite_getreplica(dmlite_context* context, const char* rfn, dmlite_replica* replica);
338 
339 /**
340  * @brief Updates a replica.
341  * @param context The DM context.
342  * @param replica The replica to modify.
343  * @return 0 on success, error code otherwise.
344  */
345 int dmlite_updatereplica(dmlite_context* context, const dmlite_replica* replica);
346 
347 #ifdef __cplusplus
348 }
349 #endif
350 
351 #endif /* DMLITE_CATALOG_H */