00001 /** @file include/dmlite/c/inode.h 00002 * @brief C wrapper for DMLite INode API. 00003 * @author Alejandro Álvarez Ayllon <aalvarez@cern.ch> 00004 * @note This is a low-level API, so security checks will NOT be done. 00005 */ 00006 #ifndef DMLITE_INODE_H 00007 #define DMLITE_INODE_H 00008 00009 #include "dmlite.h" 00010 #include "any.h" 00011 #include "utils.h" 00012 #include <stdint.h> 00013 00014 #ifdef __cplusplus 00015 extern "C" { 00016 #endif 00017 00018 /** Possible replica statuses */ 00019 enum dmlite_replica_status { kAvailable = '-', 00020 kBeingPopulated = 'P', 00021 kToBeDeleted = 'D' 00022 }; 00023 /** Possible replica types */ 00024 enum dmlite_replica_type { kVolatile = 'V', 00025 kPermanent = 'P' 00026 }; 00027 00028 /** A replica of a file */ 00029 typedef struct dmlite_replica { 00030 int64_t replicaid; 00031 int64_t fileid; 00032 00033 int64_t nbaccesses; 00034 time_t atime; 00035 time_t ptime; 00036 time_t ltime; 00037 00038 enum dmlite_replica_status status; 00039 enum dmlite_replica_type type; 00040 00041 char server[HOST_NAME_MAX]; 00042 char rfn [URL_MAX]; 00043 00044 00045 dmlite_any_dict* extra; /**< @brief If != NULL, additional metadata will be 00046 * put here. 00047 * @details Caller is generally responsible for 00048 * allocating and freeing. Exception: 00049 * when an array is allocated by the called 00050 * method */ 00051 } dmlite_replica; 00052 00053 /** Posible file statuses */ 00054 enum dmlite_file_status { kOnline = '-', 00055 kMigrated = 'm', 00056 kDeleted = 'D' 00057 }; 00058 00059 /** File metadata */ 00060 typedef struct dmlite_xstat { 00061 ino_t parent; 00062 struct stat stat; 00063 enum dmlite_file_status status; 00064 char name [NAME_MAX]; 00065 char guid [GUID_MAX]; 00066 char csumtype [CSUMTYPE_MAX]; 00067 char csumvalue[CSUMVALUE_MAX]; 00068 char acl [ACL_ENTRIES_MAX * ACL_SIZE]; 00069 00070 dmlite_any_dict* extra; /**< @brief If != NULL, additional metadata will be 00071 * put here. 00072 * @details Caller is responsible for allocating 00073 * and freeing*/ 00074 } dmlite_xstat; 00075 00076 /** Opaque directory handler */ 00077 typedef struct dmlite_idir dmlite_idir; 00078 00079 /** 00080 * @brief Starts a transaction. 00081 * @details Depending on the plugin stack, it can be possible to nest 00082 * several calls. 00083 * @param context The DM context. 00084 * @return 0 on success, error code otherwise. 00085 */ 00086 int dmlite_ibegin(dmlite_context* context); 00087 00088 /** 00089 * @brief Commits the changes. 00090 * @details Depending on the plugin stack, it can be possible to nest 00091 * several calls, and there must be one icommit per ibegin 00092 * for the changes to be permanent. 00093 * @param context The DM context. 00094 * @return 0 on success, error code otherwise. 00095 */ 00096 int dmlite_icommit(dmlite_context* context); 00097 00098 /** 00099 * @brief Undo the changes. 00100 * @details If several ibegin were nested, all the transactions will 00101 * be probable be undone, regardless on the nesting level. 00102 * @param context The DM context. 00103 * @return 0 on success, error code otherwise. 00104 */ 00105 int dmlite_irollback(dmlite_context* context); 00106 00107 /** 00108 * @brief Creates a new file. 00109 * @param context The DM context. 00110 * @param f Only some fields from this struct will be used. That would depend 00111 * on the plugin, but usually it will be: parent, name, mode, uid, gid, 00112 * size, status, checksum and ACL. 00113 * @return 0 on success, error code otherwise. 00114 * @note mode will probably be used raw (i.e. no cleanup or set of format bits) 00115 */ 00116 int dmlite_icreate(dmlite_context* context, const dmlite_xstat* f); 00117 00118 /** 00119 * @brief Associates a symlink with an existing file. 00120 * @param context The DM context. 00121 * @param inode The file that will be a symlink. 00122 * @param link The destination link. 00123 * @return 0 on success, error code otherwise. 00124 */ 00125 int dmlite_isymlink(dmlite_context* context, ino_t inode, const char* link); 00126 00127 /** 00128 * @brief Removes a file or directory from the database. 00129 * @param context The DM context. 00130 * @param inode The id of the entry to remove. 00131 * @return 0 on success, error code otherwise. 00132 * @note Not empty directories, or files will replicas may fail. 00133 */ 00134 int dmlite_iunlink(dmlite_context* context, ino_t inode); 00135 00136 /** 00137 * @brief Moves a file to a different parent directory. 00138 * @param context The DM context. 00139 * @param inode The file id. 00140 * @param dest The destination id. 00141 * @return 0 on success, error code otherwise. 00142 */ 00143 int dmlite_imove(dmlite_context* context, ino_t inode, ino_t dest); 00144 00145 /** 00146 * @brief Changes the name of an entry. 00147 * @param context The DM context. 00148 * @param inode The file id. 00149 * @param name The new name. 00150 * @return 0 on success, error code otherwise. 00151 */ 00152 int dmlite_irename(dmlite_context* context, ino_t inode, const char* name); 00153 00154 /** 00155 * @brief Does a stat of an entry using the inode instead of the path. 00156 * @param context The DM context. 00157 * @param inode The entry inode. 00158 * @param buf Where to put the retrieved information. 00159 * @return 0 on success, error code otherwise. 00160 * @note Security checks won't be done if you use this function, 00161 * so keep in mind doing it yourself. 00162 */ 00163 int dmlite_istat(dmlite_context* context, ino_t inode, struct stat* buf); 00164 00165 /** 00166 * @brief Does an extended stat of an entry using the inode instead of 00167 * the path. 00168 * @param context The DM context. 00169 * @param inode The entry inode. 00170 * @param buf Where to put the retrieved information. 00171 * @return 0 on success, error code otherwise. 00172 * @note Security checks won't be done if you use this function, 00173 * so keep in mind doing it yourself. 00174 */ 00175 int dmlite_istatx(dmlite_context* context, ino_t inode, dmlite_xstat* buf); 00176 00177 /** 00178 * @brief Does an extended stat using the parent inode and the entry name. 00179 * @param context The DM context. 00180 * @param parent The parent id. 00181 * @param name The entry name. 00182 * @param buf Where to put the retrieved information. 00183 * @return 0 on success, error code otherwise. 00184 */ 00185 int dmlite_istatx_by_name(dmlite_context* context, ino_t parent, const char* name, 00186 dmlite_xstat* buf); 00187 00188 /** 00189 * @brief Reads a symbolic link. 00190 * @param context The DM context. 00191 * @param inode The file id. 00192 * @param path The link will be put here. 00193 * @param bufsize The size of the memory area pointed by path. 00194 * @return 0 on success, error code otherwise. 00195 */ 00196 int dmlite_ireadlink(dmlite_context* context, ino_t inode, 00197 char* path, size_t bufsize); 00198 00199 /** 00200 * @brief Adds a new replica. 00201 * @param context The DM context. 00202 * @param replica The replica to add. replica->fileid must point to a valid file. 00203 * @return 0 on success, error code otherwise. 00204 */ 00205 int dmlite_iaddreplica(dmlite_context* context, const dmlite_replica* replica); 00206 00207 /** 00208 * @brief Deletes a replica. 00209 * @param context The DM context. 00210 * @param replica The replica to remove. 00211 * @return 0 on success, error code otherwise. 00212 */ 00213 int dmlite_ideletereplica(dmlite_context* context, const dmlite_replica* replica); 00214 00215 /** 00216 * @brief Gets a specific replica using its replica id. 00217 * @param context The DM context. 00218 * @param rid The replica id. 00219 * @param buf Where to put the retrieved data. 00220 * @return 0 on success, error code otherwise. 00221 */ 00222 int dmlite_igetreplica(dmlite_context* context, int64_t rid, dmlite_replica* buf); 00223 00224 /** 00225 * @brief Gets all the replicas associated to a file. 00226 * @param context The DM context. 00227 * @param inode The file id. 00228 * @param nreplicas The number of replicas will be put here. 00229 * @param replicas It will be initialized to an array of nreplicas replicas. 00230 * Free it with <b>dmlite_replicas_free</b>. 00231 * @return 0 on success, error code otherwise. 00232 */ 00233 int dmlite_igetreplicas(dmlite_context* context, ino_t inode, 00234 unsigned* nreplicas, dmlite_replica** replicas); 00235 00236 /** 00237 * @brief Sets the access and modification time. 00238 * @param context The DM context. 00239 * @param inode The file id. 00240 * @param buf The timestamps. 00241 * @return 0 on success, error code otherwise. 00242 */ 00243 int dmlite_iutime(dmlite_context* context, ino_t inode, 00244 const struct utimbuf* buf); 00245 00246 /** 00247 * @brief Sets the mode and ACL of a file. 00248 * @param context The DM context. 00249 * @param inode The file id. 00250 * @param uid The new UID. 00251 * @param gid The new GID. 00252 * @param mode The new mode. 00253 * @param nentries The number of acl entries. 00254 * @param acl The new ACL. 00255 * @return 0 on success, error code otherwise. 00256 * @note This call may not validate that uid, gid, mode and acl 00257 * are coherent. 00258 */ 00259 int dmlite_isetmode(dmlite_context* context, ino_t inode, uid_t uid, gid_t gid, 00260 mode_t mode, unsigned nentries, dmlite_aclentry* acl); 00261 00262 /** 00263 * @brief Sets the size of a file. 00264 * @param context The DM context. 00265 * @param inode The file id. 00266 * @param size The new size. 00267 * @return 0 on success, error code otherwise. 00268 */ 00269 int dmlite_isetsize(dmlite_context* context, ino_t inode, size_t size); 00270 00271 /** 00272 * @brief Sets the checksum of a file. 00273 * @param context The DM context. 00274 * @param inode The file id. 00275 * @param csumtype The new checksum type. 00276 * @param csumvalue The new checksum value. 00277 * @return 0 on success, error code otherwise. 00278 */ 00279 int dmlite_isetchecksum(dmlite_context* context, ino_t inode, 00280 const char* csumtype, const char* csumvalue); 00281 00282 /** 00283 * @brief Gets the comment associated with an entry. 00284 * @param context The DM context. 00285 * @param inode The file id. 00286 * @param comment Where to put the comment. 00287 * @param bufsize The size of the memory pointed by comment. 00288 * @return 0 on success, error code otherwise. 00289 */ 00290 int dmlite_igetcomment(dmlite_context* context, ino_t inode, 00291 char* comment, size_t bufsize); 00292 00293 /** 00294 * @brief Sets the comment associated with an entry. 00295 * @param context The DM context. 00296 * @param inode The file id. 00297 * @param comment The new comment. 00298 * @return 0 on success, error code otherwise. 00299 */ 00300 int dmlite_isetcomment(dmlite_context* context, ino_t inode, 00301 const char* comment); 00302 00303 /** 00304 * @brief Deletes the comment associated with an entry. 00305 * @param context The DM context. 00306 * @param inode The file id. 00307 * @return 0 on success, error code otherwise. 00308 */ 00309 int dmlite_ideletecomment(dmlite_context* context, ino_t inode); 00310 00311 /** 00312 * @brief Sets the file Grid Unique Identifier. 00313 * @param context The DM context. 00314 * @param inode The entry id. 00315 * @param guid The new GUID. 00316 * @return 0 on success, error code otherwise. 00317 */ 00318 int dmlite_isetguid(dmlite_context* context, ino_t inode, const char* guid); 00319 00320 /** 00321 * @brief Updates the file extended attributes. 00322 * @param context The DM context. 00323 * @param inode The entry id. 00324 * @param xattr The new set of extended attributes. 00325 * @return 0 on success, error code otherwise. 00326 */ 00327 int dmlite_iupdate_xattr(dmlite_context* context, ino_t inode, 00328 const dmlite_any_dict* xattr); 00329 00330 /** 00331 * @brief Opens a directory. 00332 * @param context The DM context. 00333 * @param inode The directory ID. 00334 * @return NULL on failure. A pointer to an internal struct to be used 00335 * with dmlite_ireaddir* 00336 */ 00337 dmlite_idir* dmlite_iopendir(dmlite_context* context, ino_t inode); 00338 00339 /** 00340 * @brief Closes a directory, freeing any internally allocated memory. 00341 * @param context The DM context. 00342 * @param dir The directory to close, as returned by dmlite_opendir. 00343 * @return 0 on success, error code otherwise. 00344 */ 00345 int dmlite_iclosedir(dmlite_context* context, dmlite_idir* dir); 00346 00347 /** 00348 * @brief Reads a directory. Extended data. 00349 * @param context The DM context. 00350 * @param dir The directory to read, as returned by dmlite_opendir. 00351 * @return A pointer to a struct with the recovered data. 00352 * NULL on failure, or end of dir. If an error occurred, 00353 * dm_errno(context) will be different than 0. 00354 * @note The pointer is internally allocated. Do not free it. 00355 */ 00356 dmlite_xstat* dmlite_ireaddirx(dmlite_context* context, dmlite_idir* dir); 00357 00358 /** 00359 * @brief Reads a directory. 00360 * @param context The DM context. 00361 * @param dir The directory to read, as returned by dmlite_opendir. 00362 * @return A pointer to a struct with the recovered data. 00363 * NULL on failure, or end of dir. If an error occurred, 00364 * dm_errno(context) will be different than 0. 00365 * @note The pointer is internally allocated. Do not free it. 00366 */ 00367 struct dirent* dmlite_ireaddir(dmlite_context* context, dmlite_idir* dir); 00368 00369 #ifdef __cplusplus 00370 } 00371 #endif 00372 00373 #endif /* DMLITE_INODE_H */