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
13extern "C" {
14#endif
15
16typedef 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 */
24int 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 */
33char* 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 */
41mode_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 */
50int 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 */
59int 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 */
68int 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 */
77int 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 */
86int 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 */
95int 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 */
103int 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 */
111int 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 */
121int 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 */
130int 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 */
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 */
150int 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 */
159int 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 */
169int 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 */
178int 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 */
188int 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 */
198int 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 */
207int 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 */
218int 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
233int 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
247int 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 */
256int 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 */
266int 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 */
276int 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 */
285int 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 */
294int 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 */
304int 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 */
313int 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 */
321dmlite_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 */
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 */
340struct 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 */
360int 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 */
369int 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 */
377int 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 */
386int 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 */
395
396#ifdef __cplusplus
397}
398#endif
399
400#endif /* DMLITE_CATALOG_H */
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
Entry point for DMLite.
Low-level access API.
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_setfsize(dmlite_context *context, const char *path, uint64_t filesize)
Changes the size of a file in the catalog.
int dmlite_getcomment(dmlite_context *context, const char *path, char *comment, size_t bufsize)
Gets the comment associated with a file.
char * dmlite_getcwd(dmlite_context *context, char *buffer, size_t size)
Gets the current working directory.
int dmlite_utime(dmlite_context *context, const char *path, const struct utimbuf *buf)
Changes access and/or modification time.
struct dmlite_dir dmlite_dir
Definition catalog.h:16
int dmlite_readlink(dmlite_context *context, const char *path, char *buf, size_t bufsize)
Reads a symlink.
int dmlite_unlink(dmlite_context *context, const char *path)
Removes a file.
struct dirent * dmlite_readdir(dmlite_context *context, dmlite_dir *dir)
Reads an entry from a directory.
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_chmod(dmlite_context *context, const char *path, mode_t mode)
Changes the mode of a file or directory.
int dmlite_chown(dmlite_context *context, const char *path, uid_t newUid, gid_t newGid)
Changes the owner of a file or directory.
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).
int dmlite_getgrpbynam(dmlite_context *context, const char *groupName, gid_t *gid)
Gets the id of a group.
int dmlite_rename(dmlite_context *context, const char *oldPath, const char *newPath)
Renames a file, directory or symlink.
dmlite_xstat * dmlite_readdirx(dmlite_context *context, dmlite_dir *dir)
Reads an entry from a directory (extended data).
int dmlite_stat(dmlite_context *context, const char *path, struct stat *buf)
Does a stat of a file or directory.
int dmlite_closedir(dmlite_context *context, dmlite_dir *dir)
Closes a directory and free the internal structures.
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_mkdir(dmlite_context *context, const char *path, mode_t mode)
Creates a new directory.
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).
mode_t dmlite_umask(dmlite_context *context, mode_t mask)
Sets the file mode creation mask.
int dmlite_access(dmlite_context *context, const char *lfn, int mode)
Checks wether the process would be allowed to read, write, or check existence.
int dmlite_setcomment(dmlite_context *context, const char *path, const char *comment)
Sets the comment associated with a file.
int dmlite_symlink(dmlite_context *context, const char *oldPath, const char *newPath)
Creates a symlink.
int dmlite_getreplicas(dmlite_context *context, const char *path, unsigned *nReplicas, dmlite_replica **fileReplicas)
Gets the replicas of a file.
int dmlite_updatereplica(dmlite_context *context, const dmlite_replica *replica)
Updates a replica.
int dmlite_setacl(dmlite_context *context, const char *path, unsigned nEntries, dmlite_aclentry *acl)
Changes the ACL of a file.
int dmlite_setguid(dmlite_context *context, const char *path, const char *guid)
Sets the file Grid Unique Identifier.
int dmlite_getreplica_by_rfn(dmlite_context *context, const char *rfn, dmlite_replica *replica)
Gets a specific replica.
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_rmdir(dmlite_context *context, const char *path)
Deletes a directory. It must be empty.
int dmlite_update_xattr(dmlite_context *context, const char *path, const dmlite_any_dict *xattr)
Updates the file extended attributes.
int dmlite_addreplica(dmlite_context *context, const dmlite_replica *replica)
Adds a new replica to an entry.
int dmlite_getusrbynam(dmlite_context *context, const char *userName, uid_t *uid)
Get the user id.
dmlite_dir * dmlite_opendir(dmlite_context *context, const char *path)
Opens a directory to read it later.
int dmlite_chdir(dmlite_context *context, const char *path)
Changes the working dir.
int dmlite_create(dmlite_context *context, const char *path, mode_t mode)
Creates a file in the catalog (no replicas).
int dmlite_delreplica(dmlite_context *context, const dmlite_replica *replica)
Deletes a replica.
int dmlite_replicas_free(unsigned nReplicas, dmlite_replica *fileReplicas)
Frees a replica list.
int dmlite_statx(dmlite_context *context, const char *path, dmlite_xstat *buf)
Does an extended stat of a file, directory or symbolic link.
Handles ACL entries.
Definition utils.h:48
Definition inode.h:33
Definition inode.h:65
C wrapper for DMLite utils.