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