00001 /** @file include/dmlite/c/catalog.h 00002 * @brief C wrapper for DMLite Catalog API. 00003 * @author Alejandro Álvarez Ayllon <aalvarez@cern.ch> 00004 */ 00005 #ifndef DMLITE_CATALOG_H 00006 #define DMLITE_CATALOG_H 00007 00008 #include "dmlite.h" 00009 #include "inode.h" 00010 #include "utils.h" 00011 00012 #ifdef __cplusplus 00013 extern "C" { 00014 #endif 00015 00016 typedef struct dmlite_dir dmlite_dir; 00017 00018 /** 00019 * @brief Changes the working dir. 00020 * @param context The DM context. 00021 * @param path The new working dir. 00022 * @return 0 on success, error code otherwise. 00023 */ 00024 int dmlite_chdir(dmlite_context* context, const char* path); 00025 00026 /** 00027 * @brief Gets the current working directory. 00028 * @param context The DM context. 00029 * @param buffer If not NULL, the path will be stored here. <b>malloc</b> will be used otherwise. 00030 * @param size The buffer size. 00031 * @return A pointer to a string with the current working dir. 00032 */ 00033 char* dmlite_getcwd(dmlite_context* context, char* buffer, size_t size); 00034 00035 /** 00036 * @brief Sets the file mode creation mask. 00037 * @param context The DM context. 00038 * @param mask The new mask. 00039 * @return The previous mask. 00040 */ 00041 mode_t dmlite_umask(dmlite_context* context, mode_t mask); 00042 00043 /** 00044 * @brief Does a stat of a file or directory. 00045 * @param context The DM context. 00046 * @param path The path. 00047 * @param buf Where to put the retrieved information. 00048 * @return 0 on success, error code otherwise. 00049 */ 00050 int dmlite_stat(dmlite_context* context, const char* path, struct stat* buf); 00051 00052 /** 00053 * @brief Does a stat of a file, directory, or symbolic link (does not follow). 00054 * @param context The DM context. 00055 * @param path The path. 00056 * @param buf Where to put the retrieved information. 00057 * @return 0 on success, error code otherwise. 00058 */ 00059 int dmlite_statl(dmlite_context* context, const char* path, struct stat* buf); 00060 00061 /** 00062 * @brief Does an extended stat of a file, directory or symbolic link. 00063 * @param context The DM context. 00064 * @param path The path. 00065 * @param buf Where to put the retrieved information. 00066 * @return 0 on success, error code otherwise. 00067 */ 00068 int dmlite_statx(dmlite_context* context, const char* path, dmlite_xstat* buf); 00069 00070 /** 00071 * @brief Does an extended stat of a logical file using an associated replica filename. 00072 * @param context The DM context. 00073 * @param rfn Replica filename. 00074 * @param buf Where to put the retrieved information. 00075 * @return 0 on success, error code otherwise. 00076 */ 00077 int dmlite_rstatx(dmlite_context* context, const char* rfn, dmlite_xstat* buf); 00078 00079 /** 00080 * @brief Checks wether the process would be allowed to read, write, or check existence. 00081 * @param context The DM context. 00082 * @param lfn Logical filename. 00083 * @param mode A mask consisting of one or more of R_OK, W_OK, X_OK and F_OK. 00084 * @return 0 on success, error code otherwise. 00085 */ 00086 int dmlite_access(dmlite_context* context, const char* lfn, int mode); 00087 00088 /** 00089 * @brief Checks wether the process would be allowed to read, write, or check existence. 00090 * @param context The DM context. 00091 * @param rfn Replica filename. 00092 * @param mode A mask consisting of one or more of R_OK, W_OK, X_OK and F_OK. 00093 * @return 0 on success, error code otherwise. 00094 */ 00095 int dmlite_accessr(dmlite_context* context, const char* rfn, int mode); 00096 00097 /** 00098 * @brief Adds a new replica to an entry. 00099 * @param context The DM context. 00100 * @param replica The replica to add. 00101 * @return 0 on success, error code otherwise. 00102 */ 00103 int dmlite_addreplica(dmlite_context* context, const dmlite_replica* replica); 00104 00105 /** 00106 * @brief Deletes a replica. 00107 * @param context The DM context. 00108 * @param replica The replica to delete. 00109 * @return 0 on success, error code otherwise. 00110 */ 00111 int dmlite_delreplica(dmlite_context* context, const dmlite_replica* replica); 00112 00113 /** 00114 * @brief Gets the replicas of a file. 00115 * @param context The DM context. 00116 * @param path The logical file name. 00117 * @param nReplicas The number of entries will be put here. 00118 * @param fileReplicas An array with nEntries elements will be stored here. <b>Use dmlite_replicas_free to free it.</b> 00119 * @return 0 on success, error code otherwise. 00120 */ 00121 int dmlite_getreplicas(dmlite_context* context, const char* path, unsigned *nReplicas, 00122 dmlite_replica** fileReplicas); 00123 00124 /** 00125 * @brief Frees a replica list. 00126 * @param nReplicas The number of replicas contained in the array. 00127 * @param fileReplicas The array to free. 00128 * @return 0 on success, error code otherwise. 00129 */ 00130 int dmlite_replicas_free(unsigned nReplicas, dmlite_replica* fileReplicas); 00131 00132 /** 00133 * @brief Creates a symlink 00134 * @param context The DM context. 00135 * @param oldPath The old path. 00136 * @param newPath The new path. 00137 * @return 0 on success, error code otherwise. 00138 */ 00139 int dmlite_symlink(dmlite_context* context, 00140 const char* oldPath, const char* newPath); 00141 00142 /** 00143 * @brief Reads a symlink. 00144 * @param context The DM context. 00145 * @param path The symlink file. 00146 * @param buf Where to put the symlink target. 00147 * @param bufsize The size of the memory pointed by buf. 00148 * @return 0 on success, error code otherwise. 00149 */ 00150 int dmlite_readlink(dmlite_context* context, const char* path, 00151 char* buf, size_t bufsize); 00152 00153 /** 00154 * @brief Removes a file. 00155 * @param context The DM context. 00156 * @param path The logical file name. 00157 * @return 0 on success, error code otherwise. 00158 */ 00159 int dmlite_unlink(dmlite_context* context, const char* path); 00160 00161 00162 /** 00163 * @brief Creates a file in the catalog (no replicas). 00164 * @param context The DM context. 00165 * @param path The logical file name. 00166 * @param mode The creation mode. 00167 * @return 0 on success, error code otherwise. 00168 */ 00169 int dmlite_create(dmlite_context* context, const char* path, mode_t mode); 00170 00171 /** 00172 * @brief Changes the mode of a file or directory. 00173 * @param context The DM context. 00174 * @param path The logical path. 00175 * @param mode The new mode. 00176 * @return 0 on success, error code otherwise. 00177 */ 00178 int dmlite_chmod(dmlite_context* context, const char* path, mode_t mode); 00179 00180 /** 00181 * @brief Changes the owner of a file or directory. 00182 * @param context The DM context. 00183 * @param path The logical path. 00184 * @param newUid The new owner. 00185 * @param newGid The new group. 00186 * @return 0 on success, error code otherwise. 00187 */ 00188 int dmlite_chown(dmlite_context* context, const char* path, uid_t newUid, gid_t newGid); 00189 00190 /** 00191 * @brief Changes the owner of a file, directory or symlink (does not follow). 00192 * @param context The DM context. 00193 * @param path The logical path. 00194 * @param newUid The new owner. 00195 * @param newGid The new group. 00196 * @return 0 on success, error code otherwise. 00197 */ 00198 int dmlite_lchown(dmlite_context* context, const char* path, uid_t newUid, gid_t newGid); 00199 00200 /** 00201 * @brief Changes the size of a file in the catalog. 00202 * @param context The DM context. 00203 * @param path The logical path. 00204 * @param filesize The new file size. 00205 * @return 0 on success, error code otherwise. 00206 */ 00207 int dmlite_setfsize(dmlite_context* context, const char* path, uint64_t filesize); 00208 00209 /** 00210 * @brief Changes the size and checksum of a file in the catalog. 00211 * @param context The DM context. 00212 * @param path The logical path. 00213 * @param filesize The new file size. 00214 * @param csumtype The new checksum type (CS, AD or MD). 00215 * @param csumvalue The new checksum value. 00216 * @return 0 on success, error code otherwise. 00217 */ 00218 int dmlite_setfsizec(dmlite_context* context, const char* path, uint64_t filesize, 00219 const char* csumtype, const char* csumvalue); 00220 /** 00221 * @brief Gets the checksum of a file in the catalog. 00222 * @param context The DM context. 00223 * @param path The logical path. 00224 * @param csumtype The wanted checksum type (CS, AD or MD. We can also pass a long checksum name (e.g. checksum.adler32)) 00225 * @param csumvalue The wanted checksum value will be written into this string. Make sure it has enough space. 00226 * @param maxcksumlen Max allowed length for a checksum, to avoid buffer overflows. 00227 * @param pfn Optional: the corresponding replica for which to calculate a checksum 00228 * @param forcerecalc True if nonzero. Force recalculation of the checksum (may take long and return EAGAIN) 00229 * @param waitsecs Seconds to wait for a checksum to be calculated. Returns EAGAIN if timeouts. Set to 0 for blocking behavior. 00230 * @return 0 on success, error code otherwise. 00231 */ 00232 00233 int dmlite_getchecksum(dmlite_context* context, const char* path, 00234 const char* csumtype, char* csumvalue, const int maxcksumlen, 00235 const char* pfn, const int forcerecalc, const int waitsecs); 00236 00237 /** 00238 * @brief Changes the ACL of a file. 00239 * @param context The DM context. 00240 * @param path The logical path. 00241 * @param nEntries The number of entries in the acl array. 00242 * @param acl An ACL array. 00243 * @return 0 on success, error code otherwise. 00244 */ 00245 00246 00247 int dmlite_setacl(dmlite_context* context, const char* path, unsigned nEntries, dmlite_aclentry* acl); 00248 00249 /** 00250 * @brief Changes access and/or modification time 00251 * @param context The DM context. 00252 * @param path The file path. 00253 * @param buf A struct holding the new times. 00254 * @return 0 on success, error code otherwise. 00255 */ 00256 int dmlite_utime(dmlite_context* context, const char* path, const struct utimbuf* buf); 00257 00258 /** 00259 * @brief Gets the comment associated with a file. 00260 * @param context The DM context. 00261 * @param path The logical path. 00262 * @param comment Where to put the retrieved comment. It must be at least of size COMMENT_MAX. 00263 * @param bufsize Size of the memory zone pointed by comment. 00264 * @return 0 on success, error code otherwise. 00265 */ 00266 int dmlite_getcomment(dmlite_context* context, const char* path, 00267 char* comment, size_t bufsize); 00268 00269 /** 00270 * @brief Sets the comment associated with a file. 00271 * @param context The DM context. 00272 * @param path The logical path. 00273 * @param comment The comment to associate. '\\0' terminated string. 00274 * @return 0 on success, error code otherwise. 00275 */ 00276 int dmlite_setcomment(dmlite_context* context, const char* path, const char* comment); 00277 00278 /** 00279 * @brief Sets the file Grid Unique Identifier. 00280 * @param context The DM context. 00281 * @param path The logical path. 00282 * @param guid The new GUID. 00283 * @return 0 on success, error code otherwise. 00284 */ 00285 int dmlite_setguid(dmlite_context* context, const char* path, const char* guid); 00286 00287 /** 00288 * @brief Updates the file extended attributes. 00289 * @param context The DM context. 00290 * @param path The logical path. 00291 * @param xattr The new set of extended attributes. 00292 * @return 0 on success, error code otherwise. 00293 */ 00294 int dmlite_update_xattr(dmlite_context* context, const char* path, 00295 const dmlite_any_dict* xattr); 00296 00297 /** 00298 * @brief Gets the id of a group. 00299 * @param context The DM context. 00300 * @param groupName The group name. 00301 * @param gid Where to put the group ID. 00302 * @return 0 on success, error code otherwise. 00303 */ 00304 int dmlite_getgrpbynam(dmlite_context* context, const char* groupName, gid_t* gid); 00305 00306 /** 00307 * @brief Get the user id. 00308 * @param context The DM context. 00309 * @param userName The user name. 00310 * @param uid Where to put the user ID. 00311 * @return 0 on success, error code otherwise. 00312 */ 00313 int dmlite_getusrbynam(dmlite_context* context, const char* userName, uid_t* uid); 00314 00315 /** 00316 * @brief Opens a directory to read it later. 00317 * @param context The DM context. 00318 * @param path The directory to open. 00319 * @return A pointer to an internal structure, or NULL on failure. 00320 */ 00321 dmlite_dir* dmlite_opendir(dmlite_context* context, const char* path); 00322 00323 /** 00324 * @brief Closes a directory and free the internal structures. 00325 * @param context The DM context. 00326 * @param dir The pointer returned by dmlite_opendir. 00327 * @return 0 on success, error code otherwise. 00328 */ 00329 int dmlite_closedir(dmlite_context* context, dmlite_dir* dir); 00330 00331 /** 00332 * @brief Reads an entry from a directory. 00333 * @param context The DM context. 00334 * @param dir The pointer returned by dmlite_opendir. 00335 * @return A pointer to a struct with the recovered data. 00336 * NULL on failure, or end of dir. If an error occurred, 00337 * dm_errno(context) will be different than 0. 00338 * @note The pointer is internally allocated. Do not free it. 00339 */ 00340 struct dirent *dmlite_readdir(dmlite_context* context, dmlite_dir* dir); 00341 00342 /** 00343 * @brief Reads an entry from a directory (extended data). 00344 * @param context The DM context. 00345 * @param dir The pointer returned by dmlite_opendir. 00346 * @return A pointer to a struct with the recovered data. 00347 * NULL on failure, or end of dir. If an error occurred, 00348 * dm_errno(context) will be different than 0. 00349 * @note The pointer is internally allocated. Do not free it. 00350 */ 00351 dmlite_xstat *dmlite_readdirx(dmlite_context* context, dmlite_dir* dir); 00352 00353 /** 00354 * @brief Creates a new directory. 00355 * @param context The DM context. 00356 * @param path The directory for the new path. All the precedent folders must exist. 00357 * @param mode Permissions to use for the creation. 00358 * @return 0 on success, error code otherwise. 00359 */ 00360 int dmlite_mkdir(dmlite_context* context, const char* path, mode_t mode); 00361 00362 /** 00363 * @brief Renames a file, directory or symlink. 00364 * @param context The DM context. 00365 * @param oldPath The old name. 00366 * @param newPath The new name. 00367 * @return 0 on success, error code otherwise. 00368 */ 00369 int dmlite_rename(dmlite_context* context, const char* oldPath, const char* newPath); 00370 00371 /** 00372 * @brief Deletes a directory. It must be empty. 00373 * @param context The DM context. 00374 * @param path The directory to remove. 00375 * @return 0 on success, error code otherwise. 00376 */ 00377 int dmlite_rmdir(dmlite_context* context, const char* path); 00378 00379 /** 00380 * @brief Gets a specific replica. 00381 * @param context The DM context. 00382 * @param rfn The replica file name. 00383 * @param replica A buffer where the retrieved data will be put. 00384 * @return 0 on success, error code otherwise. 00385 */ 00386 int dmlite_getreplica_by_rfn(dmlite_context* context, const char* rfn, dmlite_replica* replica); 00387 00388 /** 00389 * @brief Updates a replica. 00390 * @param context The DM context. 00391 * @param replica The replica to modify. 00392 * @return 0 on success, error code otherwise. 00393 */ 00394 int dmlite_updatereplica(dmlite_context* context, const dmlite_replica* replica); 00395 00396 #ifdef __cplusplus 00397 } 00398 #endif 00399 00400 #endif /* DMLITE_CATALOG_H */