 |
DAOS API (v2.1 - dev)
|
|
DAOS API (v2.1 - dev)
|
#include <dirent.h>#include <inttypes.h>#include <sys/stat.h>#include <daos_types.h>#include <daos_obj.h>#include <daos_obj_class.h>#include <daos_array.h>#include <daos_cont.h>Go to the source code of this file.
Data Structures | |
| struct | dfs_attr_t |
| struct | dfs_iod_t |
| struct | dfs_obj_info_t |
| struct | dfs_predicate_t |
Macros | |
| #define | DFS_MAX_NAME NAME_MAX |
| #define | DFS_MAX_PATH PATH_MAX |
| #define | DFS_MAX_FSIZE (~0ULL) |
| #define | DFS_DEFAULT_CHUNK_SIZE 1048576 |
| #define | DFS_MAX_XATTR_NAME 255 |
| #define | DFS_MAX_XATTR_LEN 65536 |
| #define | DFS_BALANCED 4 |
| #define | DFS_RELAXED 0 |
| #define | DFS_RDONLY O_RDONLY |
| #define | DFS_RDWR O_RDWR |
| #define | DFS_SET_ATTR_MODE (1 << 0) |
| #define | DFS_SET_ATTR_ATIME (1 << 1) |
| #define | DFS_SET_ATTR_MTIME (1 << 2) |
| #define | DFS_SET_ATTR_SIZE (1 << 3) |
| #define | DFS_SET_ATTR_UID (1 << 4) |
| #define | DFS_SET_ATTR_GID (1 << 5) |
Typedefs | |
| typedef struct dfs_obj | dfs_obj_t |
| typedef struct dfs | dfs_t |
| typedef int(* | dfs_filler_cb_t) (dfs_t *dfs, dfs_obj_t *obj, const char name[], void *arg) |
| typedef struct dfs_pipeline | dfs_pipeline_t |
Enumerations | |
| enum | { DFS_CHECK_PRINT = (1 << 0) , DFS_CHECK_REMOVE = (1 << 1) , DFS_CHECK_RELINK = (1 << 2) , DFS_CHECK_VERIFY = (1 << 3) , DFS_CHECK_EVICT_ALL = (1 << 4) } |
| enum | { DFS_FILTER_NAME = (1 << 1) , DFS_FILTER_NEWER = (1 << 2) , DFS_FILTER_INCLUDE_DIRS = (1 << 3) } |
Functions | |
| int | dfs_init (void) |
| int | dfs_fini (void) |
| int | dfs_connect (const char *pool, const char *sys, const char *cont, int flags, dfs_attr_t *attr, dfs_t **dfs) |
| int | dfs_disconnect (dfs_t *dfs) |
| int | dfs_destroy (const char *pool, const char *sys, const char *cont, int force, daos_event_t *ev) |
| int | dfs_cont_create (daos_handle_t poh, uuid_t *uuid, dfs_attr_t *attr, daos_handle_t *coh, dfs_t **dfs) |
| int | dfs_cont_create_with_label (daos_handle_t poh, const char *label, dfs_attr_t *attr, uuid_t *uuid, daos_handle_t *coh, dfs_t **dfs) |
| int | dfs_mount (daos_handle_t poh, daos_handle_t coh, int flags, dfs_t **dfs) |
| int | dfs_umount (dfs_t *dfs) |
| int | dfs_pool_get (dfs_t *dfs, daos_handle_t *poh) |
| int | dfs_pool_put (dfs_t *dfs, daos_handle_t poh) |
| int | dfs_cont_get (dfs_t *dfs, daos_handle_t *coh) |
| int | dfs_cont_put (dfs_t *dfs, daos_handle_t coh) |
| int | dfs_query (dfs_t *dfs, dfs_attr_t *attr) |
| int | dfs_local2global (dfs_t *dfs, d_iov_t *glob) |
| int | dfs_global2local (daos_handle_t poh, daos_handle_t coh, int flags, d_iov_t glob, dfs_t **dfs) |
| int | dfs_local2global_all (dfs_t *dfs, d_iov_t *glob) |
| int | dfs_global2local_all (int flags, d_iov_t glob, dfs_t **dfs) |
| int | dfs_set_prefix (dfs_t *dfs, const char *prefix) |
| int | dfs_obj2id (dfs_obj_t *obj, daos_obj_id_t *oid) |
| int | dfs_lookup (dfs_t *dfs, const char *path, int flags, dfs_obj_t **obj, mode_t *mode, struct stat *stbuf) |
| int | dfs_lookup_rel (dfs_t *dfs, dfs_obj_t *parent, const char *name, int flags, dfs_obj_t **obj, mode_t *mode, struct stat *stbuf) |
| int | dfs_suggest_oclass (dfs_t *dfs, const char *hint, daos_oclass_id_t *cid) |
| int | dfs_open (dfs_t *dfs, dfs_obj_t *parent, const char *name, mode_t mode, int flags, daos_oclass_id_t cid, daos_size_t chunk_size, const char *value, dfs_obj_t **obj) |
| int | dfs_dup (dfs_t *dfs, dfs_obj_t *obj, int flags, dfs_obj_t **new_obj) |
| int | dfs_obj_local2global (dfs_t *dfs, dfs_obj_t *obj, d_iov_t *glob) |
| int | dfs_obj_global2local (dfs_t *dfs, int flags, d_iov_t glob, dfs_obj_t **obj) |
| int | dfs_release (dfs_obj_t *obj) |
| int | dfs_read (dfs_t *dfs, dfs_obj_t *obj, d_sg_list_t *sgl, daos_off_t off, daos_size_t *read_size, daos_event_t *ev) |
| int | dfs_readx (dfs_t *dfs, dfs_obj_t *obj, dfs_iod_t *iod, d_sg_list_t *sgl, daos_size_t *read_size, daos_event_t *ev) |
| int | dfs_write (dfs_t *dfs, dfs_obj_t *obj, d_sg_list_t *sgl, daos_off_t off, daos_event_t *ev) |
| int | dfs_writex (dfs_t *dfs, dfs_obj_t *obj, dfs_iod_t *iod, d_sg_list_t *sgl, daos_event_t *ev) |
| int | dfs_get_size (dfs_t *dfs, dfs_obj_t *obj, daos_size_t *size) |
| int | dfs_punch (dfs_t *dfs, dfs_obj_t *obj, daos_off_t offset, daos_size_t len) |
| int | dfs_readdir (dfs_t *dfs, dfs_obj_t *obj, daos_anchor_t *anchor, uint32_t *nr, struct dirent *dirs) |
| int | dfs_readdirplus (dfs_t *dfs, dfs_obj_t *obj, daos_anchor_t *anchor, uint32_t *nr, struct dirent *dirs, struct stat *stbufs) |
| int | dfs_iterate (dfs_t *dfs, dfs_obj_t *obj, daos_anchor_t *anchor, uint32_t *nr, size_t size, dfs_filler_cb_t op, void *arg) |
| int | dfs_dir_anchor_set (dfs_obj_t *obj, const char name[], daos_anchor_t *anchor) |
| int | dfs_obj_anchor_split (dfs_obj_t *obj, uint32_t *nr, daos_anchor_t *anchors) |
| int | dfs_obj_anchor_set (dfs_obj_t *obj, uint32_t index, daos_anchor_t *anchor) |
| int | dfs_mkdir (dfs_t *dfs, dfs_obj_t *parent, const char *name, mode_t mode, daos_oclass_id_t cid) |
| int | dfs_remove (dfs_t *dfs, dfs_obj_t *parent, const char *name, bool force, daos_obj_id_t *oid) |
| int | dfs_move (dfs_t *dfs, dfs_obj_t *parent, const char *name, dfs_obj_t *new_parent, const char *new_name, daos_obj_id_t *oid) |
| int | dfs_exchange (dfs_t *dfs, dfs_obj_t *parent1, const char *name1, dfs_obj_t *parent2, const char *name2) |
| int | dfs_get_mode (dfs_obj_t *obj, mode_t *mode) |
| int | dfs_obj_get_info (dfs_t *dfs, dfs_obj_t *obj, dfs_obj_info_t *info) |
| int | dfs_obj_set_oclass (dfs_t *dfs, dfs_obj_t *obj, int flags, daos_oclass_id_t cid) |
| int | dfs_obj_set_chunk_size (dfs_t *dfs, dfs_obj_t *obj, int flags, daos_size_t csize) |
| int | dfs_get_file_oh (dfs_obj_t *obj, daos_handle_t *oh) |
| int | dfs_get_chunk_size (dfs_obj_t *obj, daos_size_t *chunk_size) |
| int | dfs_get_symlink_value (dfs_obj_t *obj, char *buf, daos_size_t *size) |
| int | dfs_update_parent (dfs_obj_t *obj, dfs_obj_t *src_obj, const char *name) |
| int | dfs_stat (dfs_t *dfs, dfs_obj_t *parent, const char *name, struct stat *stbuf) |
| int | dfs_ostat (dfs_t *dfs, dfs_obj_t *obj, struct stat *stbuf) |
| int | dfs_osetattr (dfs_t *dfs, dfs_obj_t *obj, struct stat *stbuf, int flags) |
| int | dfs_access (dfs_t *dfs, dfs_obj_t *parent, const char *name, int mask) |
| int | dfs_chmod (dfs_t *dfs, dfs_obj_t *parent, const char *name, mode_t mode) |
| int | dfs_chown (dfs_t *dfs, dfs_obj_t *parent, const char *name, uid_t uid, gid_t gid, int flags) |
| int | dfs_sync (dfs_t *dfs) |
| int | dfs_setxattr (dfs_t *dfs, dfs_obj_t *obj, const char *name, const void *value, daos_size_t size, int flags) |
| int | dfs_getxattr (dfs_t *dfs, dfs_obj_t *obj, const char *name, void *value, daos_size_t *size) |
| int | dfs_removexattr (dfs_t *dfs, dfs_obj_t *obj, const char *name) |
| int | dfs_listxattr (dfs_t *dfs, dfs_obj_t *obj, char *list, daos_size_t *size) |
| int | dfs_cont_check (daos_handle_t poh, const char *cont, uint64_t flags, const char *name) |
| int | dfs_cont_set_owner (daos_handle_t coh, d_string_t user, uid_t uid, d_string_t group, gid_t gid) |
| int | dfs_get_size_by_oid (dfs_t *dfs, daos_obj_id_t oid, daos_size_t chunk_size, daos_size_t *size) |
| int | dfs_pipeline_create (dfs_t *dfs, dfs_predicate_t pred, uint64_t flags, dfs_pipeline_t **dpipe) |
| int | dfs_pipeline_destroy (dfs_pipeline_t *dpipe) |
| int | dfs_readdir_with_filter (dfs_t *dfs, dfs_obj_t *obj, dfs_pipeline_t *dpipe, daos_anchor_t *anchor, uint32_t *nr, struct dirent *dirs, daos_obj_id_t *oids, daos_size_t *csizes, uint64_t *nr_scanned) |
| int | dfs_cont_scan (daos_handle_t poh, const char *cont, uint64_t flags, const char *name) |
DAOS File System API
The DFS API provides an encapuslated namespace with a POSIX like API directly on top of the DAOS API. The namespace is encapsulated under a single DAOS container where directories and files are objects in that container.
Definition in file daos_fs.h.
| #define DFS_BALANCED 4 |
| #define DFS_DEFAULT_CHUNK_SIZE 1048576 |
| #define DFS_RELAXED 0 |
| #define DFS_SET_ATTR_ATIME (1 << 1) |
| #define DFS_SET_ATTR_GID (1 << 5) |
| #define DFS_SET_ATTR_MODE (1 << 0) |
| #define DFS_SET_ATTR_MTIME (1 << 2) |
| #define DFS_SET_ATTR_SIZE (1 << 3) |
| #define DFS_SET_ATTR_UID (1 << 4) |
| typedef struct dfs_obj dfs_obj_t |
| typedef struct dfs_pipeline dfs_pipeline_t |
| anonymous enum |
Check access permissions on an object. Similar to Linux access(2). Symlinks are dereferenced.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | parent | Opened parent directory object. If NULL, use root obj. |
| [in] | name | Link name of the object. Can be NULL if parent is root, which means operation will be on root object. |
| [in] | mask | accessibility check(s) to be performed. It should be either the value F_OK, or a mask with bitwise OR of one or more of R_OK, W_OK, and X_OK. |
Change permission access bits. Symlinks are dereferenced.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | parent | Opened parent directory object. If NULL, use root obj. |
| [in] | name | Link name of the object. Can be NULL if parent is root, which means operation will be on root object. |
| [in] | mode | New permission access modes. For now, we don't support the sticky bit, setuid, and setgid. |
| int dfs_chown | ( | dfs_t * | dfs, |
| dfs_obj_t * | parent, | ||
| const char * | name, | ||
| uid_t | uid, | ||
| gid_t | gid, | ||
| int | flags ) |
Change owner and group. Since uid and gid are not enforced at the DFS level, we do not also enforce the process privileges to be able to change the uid and gid. Any process with write access to the DFS container can make changes to the uid and gid using this function.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | parent | Opened parent directory object. If NULL, use root obj. |
| [in] | name | Link name of the object. Can be NULL if parent is root, which means operation will be on root object. |
| [in] | uid | change owner of file (-1 to leave unchanged). |
| [in] | gid | change group of file (-1 to leave unchanged). |
| [in] | flags | if 0, symlinks are dereferenced. Pass O_NOFOLLOW to not dereference. |
| int dfs_connect | ( | const char * | pool, |
| const char * | sys, | ||
| const char * | cont, | ||
| int | flags, | ||
| dfs_attr_t * | attr, | ||
| dfs_t ** | dfs ) |
Mount a DFS namespace over the specified pool and container. The container can be optionally created if it doesn't exist, and O_CREAT is passed in flags. The handle must be released using dfs_disconnect() and not dfs_umount(). Using the latter in this case will leak open handles for the pool and container.
This function works only if dfs_init() is called, otherwise would return EACCES. In addition to setting up the pool and container handles for the user, this also utilizes an internal cache for keeping the pool and container handles open internally with a ref count and closes those handles on dfs_finalize().
| [in] | pool | Pool label. |
| [in] | sys | DAOS system name to use for the pool connect. Pass NULL to use the default system. |
| [in] | cont | Container label. |
| [in] | flags | Mount flags (O_RDONLY or O_RDWR, O_CREAT). O_CREAT attempts to create the DFS container if it doesn't exists. |
| [in] | attr | Optional set of properties and attributes to set on the container (if being created). Pass NULL to use default. |
| [out] | dfs | Pointer to the created DFS mount point. |
| int dfs_cont_check | ( | daos_handle_t | poh, |
| const char * | cont, | ||
| uint64_t | flags, | ||
| const char * | name ) |
Scan the DFS namespace and check if there are any leaked objects. Depending on the flag passed, either remove those leaked objects to reclaim space, add those object to "Lost+Found" directory, or just print the oids to stdout.
| [in] | poh | Open pool handle. |
| [in] | cont | POSIX container label. |
| [in] | flags | Flags to indicate what to do with leaked objects: punch, link to l+f, or print to stdout. |
| [in] | name | Optional directory name to be created under lost+found where all oids are stored. If NULL is specified, a directory will be created with a name corresponding to the current timestamp with the format "%Y-%m-%d-%H:%M:%S". If the DFS_CHECK_LINK_LF is not set, this is ignored. |
| int dfs_cont_create | ( | daos_handle_t | poh, |
| uuid_t * | uuid, | ||
| dfs_attr_t * | attr, | ||
| daos_handle_t * | coh, | ||
| dfs_t ** | dfs ) |
Create a DFS container with the POSIX property layout set. Optionally set attributes for hints on the container.
| [in] | poh | Pool open handle. |
| [out] | uuid | Pointer to uuid_t to hold the implementation-generated container UUID. |
| [in] | attr | Optional set of properties and attributes to set on the container. Pass NULL if none. |
| [out] | coh | Optionally leave the container open and return its hdl. |
| [out] | dfs | Optionally mount DFS on the container and return the dfs handle. |
| int dfs_cont_create_with_label | ( | daos_handle_t | poh, |
| const char * | label, | ||
| dfs_attr_t * | attr, | ||
| uuid_t * | uuid, | ||
| daos_handle_t * | coh, | ||
| dfs_t ** | dfs ) |
Create a DFS container with label label. This is the same as dfs_container_create() with the label property set in attr->da_props.
| [in] | poh | Pool open handle. |
| [in] | label | Required, label property of the new container. Supersedes any label specified in cont_prop. |
| [in] | attr | Optional set of properties and attributes to set on the container. Pass NULL if none. |
| [out] | uuid | Optional pointer to uuid_t to hold the implementation-generated container UUID. |
| [out] | coh | Optionally leave the container open and return its hdl. |
| [out] | dfs | Optionally mount DFS on the container and return the dfs handle. |
| int dfs_cont_get | ( | dfs_t * | dfs, |
| daos_handle_t * | coh ) |
Retrieve the open cont handle on the DFS mount. This is refcounted internally and must be released with dfs_cont_put().
| [in] | dfs | Pointer to the mounted file system. |
| [out] | coh | Open cont handle. |
| int dfs_cont_put | ( | dfs_t * | dfs, |
| daos_handle_t | coh ) |
Release refcount of cont handle taken by dfs_cont_get().
| [in] | dfs | Pointer to the mounted file system. |
| [out] | coh | Cont handle that was returned from dfs_cont_get(). |
| int dfs_cont_scan | ( | daos_handle_t | poh, |
| const char * | cont, | ||
| uint64_t | flags, | ||
| const char * | name ) |
Scan the DFS namespace and report statistics about file/dir size and namespace structure.
| [in] | poh | Open pool handle. |
| [in] | cont | POSIX container label. |
| [in] | flags | Unused flag, added for future use. |
| [in] | name | Optional subdirectory path to scan from. Start from container root if not specified. |
| int dfs_cont_set_owner | ( | daos_handle_t | coh, |
| d_string_t | user, | ||
| uid_t | uid, | ||
| d_string_t | group, | ||
| gid_t | gid ) |
Update a POSIX's container's owner user and/or owner group. This is the same as calling daos_cont_set_owner() but will also update the owner of the root directory in the container.
| [in] | coh | Open container handle |
| [in] | user | New owner user (NULL if not updating) |
| [in] | uid | New owner uid, if different from user's on local system (-1 otherwise) |
| [in] | group | New owner group (NULL if not updating) |
| [in] | gid | New owner gid, if different from group's on local system (-1 otherwise) |
| int dfs_destroy | ( | const char * | pool, |
| const char * | sys, | ||
| const char * | cont, | ||
| int | force, | ||
| daos_event_t * | ev ) |
Evict all the container handles from the hashtable and destroy the container.
| [in] | pool | Pool label where the container is. |
| [in] | sys | DAOS system name to use for the pool. Pass NULL to use the default system. |
| [in] | cont | Container label to destroy. |
| [in] | force | Container destroy will return failure if the container is still busy (outstanding open handles from other open calls). This parameter will force the destroy to proceed even if there is an outstanding open handle. |
| [in] | ev | Completion event, it is optional and can be NULL. The function will run in blocking mode if ev is NULL. |
| int dfs_dir_anchor_set | ( | dfs_obj_t * | obj, |
| const char | name[], | ||
| daos_anchor_t * | anchor ) |
Set the readdir/iterate anchor to start from a specific entry name in a directory object. When using the anchor in a readdir call, the iteration will start from the position of that entry.
| [in] | obj | Opened directory object. |
| [in] | name | Entry name of a file/dir in the open directory where anchor should be set. |
| [out] | anchor | Hash anchor returned for the position of the entry name in obj. |
| int dfs_disconnect | ( | dfs_t * | dfs | ) |
Umount the DFS namespace, and release the ref count on the container and pool handles. This should be called on a dfs mount created with dfs_connect() and not dfs_mount().
| [in] | dfs | Pointer to the mounted file system from dfs_connect(). |
Duplicate the DFS object without any RPCs (locally) by using the existing open handles. This is used mostly for low-level fuse to avoid re-opening. The duplicated object must be released with dfs_release().
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Object to dup. |
| [in] | flags | Access flags to open with (O_RDONLY or O_RDWR). |
| [out] | new_obj | DFS object that is duplicated/opened. |
| int dfs_exchange | ( | dfs_t * | dfs, |
| dfs_obj_t * | parent1, | ||
| const char * | name1, | ||
| dfs_obj_t * | parent2, | ||
| const char * | name2 ) |
Exchange two objects.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | parent1 | Parent directory object of name1. If NULL, use root obj. |
| [in] | name1 | Link name of first object. |
| [in] | parent2 | Parent directory object of name2. If NULL, use root obj. |
| [in] | name2 | link name of second object. |
| int dfs_fini | ( | void | ) |
Finalize the DAOS and DFS library. Typically this is called at the end of a user program or in IO middleware finalization. This is required to be called if dfs_init() was called and closes all cached open pool and container handles that resulted from dfs_connect() calls.
| int dfs_get_chunk_size | ( | dfs_obj_t * | obj, |
| daos_size_t * | chunk_size ) |
Retrieve the chunk size of a DFS file object.
| [in] | obj | Open object. |
| [out] | chunk_size | Chunk size of array object. |
| int dfs_get_file_oh | ( | dfs_obj_t * | obj, |
| daos_handle_t * | oh ) |
Retrieve the DAOS open handle of a DFS file object. User should not close this handle. This is used in cases like MPI-IO where 1 rank creates the file with dfs, but wants to access the file with the array API directly rather than the DFS API.
| [in] | obj | Open object. |
| [out] | oh | DAOS object open handle. |
| int dfs_get_mode | ( | dfs_obj_t * | obj, |
| mode_t * | mode ) |
Retrieve mode of an open object.
| [in] | obj | Open object to query. |
| [out] | mode | mode_t (permissions + type). |
Query size of file data.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Opened file object. |
| [out] | size | Size of file. |
| int dfs_get_size_by_oid | ( | dfs_t * | dfs, |
| daos_obj_id_t | oid, | ||
| daos_size_t | chunk_size, | ||
| daos_size_t * | size ) |
Same as dfs_get_size() but using the OID of the file instead of the open handle. Note that the chunk_size of the file is also required to be passed if the file was created with a different chunk size than the default (passing other than 0 to dfs_open). Otherwise, 0 should be passed to chunk size.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | oid | Object ID of the file. |
| [in] | chunk_size | Chunk size of the file (pass 0 if it was created with default). |
| [out] | size | Returned size of the file. |
| int dfs_get_symlink_value | ( | dfs_obj_t * | obj, |
| char * | buf, | ||
| daos_size_t * | size ) |
Retrieve Symlink value of object if it's a symlink. If the buffer size passed in is not large enough, we copy up to size of the buffer, and update the size to actual value size. The size returned includes the null terminator.
| [in] | obj | Open object to query. |
| [in] | buf | user buffer to copy the symlink value in. |
| [in,out] | size | [in]: Size of buffer passed in. [out]: Actual size of value. |
| int dfs_getxattr | ( | dfs_t * | dfs, |
| dfs_obj_t * | obj, | ||
| const char * | name, | ||
| void * | value, | ||
| daos_size_t * | size ) |
Get extended attribute of an open object. If object is a symlink, the link itself is interogated.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Open object where xattr is checked. |
| [in] | name | Name of xattr to get. |
| [out] | value | Buffer to place value of xattr. |
| [in,out] | size | [in]: Size of buffer value. [out]: Actual size of xattr. |
| int dfs_global2local | ( | daos_handle_t | poh, |
| daos_handle_t | coh, | ||
| int | flags, | ||
| d_iov_t | glob, | ||
| dfs_t ** | dfs ) |
Create a dfs mount from global representation data. This has to be closed with dfs_umount().
| [in] | poh | Pool connection handle |
| [in] | coh | Container open handle. |
| [in] | flags | Mount flags (O_RDONLY or O_RDWR). If 0, inherit flags of serialized DFS handle. |
| [in] | glob | Global (shared) representation of a collective handle to be extracted |
| [out] | dfs | Returned dfs mount |
| int dfs_global2local_all | ( | int | flags, |
| d_iov_t | glob, | ||
| dfs_t ** | dfs ) |
Create a dfs mount from global representation data. This has to be closed with dfs_disconnect() since the pool and container connections are established with it.
| [in] | flags | Mount flags (O_RDONLY or O_RDWR). If 0, inherit flags of serialized DFS handle. |
| [in] | glob | Global (shared) representation of a collective handle to be extracted. |
| [out] | dfs | Returned dfs mount |
| int dfs_init | ( | void | ) |
Initialize the DAOS and DFS library. Typically this is called at the beginning of a user program or in IO middleware initialization. This is required to be called if using the dfs_connect/disconnect calls to setup the DFS cache for the pool and container handles. There is no harm however in calling it whenever using any of the DFS API (mount/umount) and can be equivalent to calling daos_init() instead.
| int dfs_iterate | ( | dfs_t * | dfs, |
| dfs_obj_t * | obj, | ||
| daos_anchor_t * | anchor, | ||
| uint32_t * | nr, | ||
| size_t | size, | ||
| dfs_filler_cb_t | op, | ||
| void * | arg ) |
Same as dfs_readdir, but this also adds a buffer size limitation when enumerating. On every entry, it issues a user defined callback. If size limitation is reached, function returns E2BIG
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Opened directory object. |
| [in,out] | anchor | Hash anchor for the next call, it should be set to zeroes for the first call, it should not be changed by caller between calls. |
| [in,out] | nr | [in]: MAX number of entries to enumerate. [out]: Actual number of entries enumerated. |
| [in] | size | Max buffer size to be used internally before breaking. |
| [in] | op | Optional callback to be issued on every entry. |
| [in] | arg | Pointer to user data to be passed to op. |
list extended attributes of an open object and place them all in a buffer NULL terminated one after the other. If object is a symlink, the link itself is interogated.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Open object where xattrs will be listed. |
| [in,out] | list | [in]: Allocated buffer for all xattr names. [out]: Names placed after each other (null terminated). |
| [in,out] | size | [in]: Size of list. [out]: Actual size of list. |
| int dfs_local2global | ( | dfs_t * | dfs, |
| d_iov_t * | glob ) |
Convert a local dfs mount to global representation data which can be shared with peer processes. If glob->iov_buf is set to NULL, the actual size of the global handle is returned through glob->iov_buf_len. This function does not involve any communication and does not block.
| [in] | dfs | valid dfs mount to be shared |
| [out] | glob | pointer to iov of the buffer to store mount information |
| int dfs_local2global_all | ( | dfs_t * | dfs, |
| d_iov_t * | glob ) |
Convert a local dfs mount including the pool and container handles to global representation data which can be shared with peer processes. If glob->iov_buf is set to NULL, the actual size of the global handle is returned through glob->iov_buf_len. This function does not involve any communication and does not block.
| [in] | dfs | valid dfs mount to be shared |
| [out] | glob | pointer to iov of the buffer to store mount information |
| int dfs_lookup | ( | dfs_t * | dfs, |
| const char * | path, | ||
| int | flags, | ||
| dfs_obj_t ** | obj, | ||
| mode_t * | mode, | ||
| struct stat * | stbuf ) |
Lookup a path in the DFS and return the associated open object and mode. The object must be released with dfs_release().
| [in] | dfs | Pointer to the mounted file system. |
| [in] | path | Path to lookup. |
| [in] | flags | Access flags to open with (O_RDONLY or O_RDWR). |
| [out] | obj | Pointer to the object looked up. |
| [out] | mode | Optional mode_t of object looked up. |
| [out] | stbuf | Optional stat struct of object looked up. |
| int dfs_lookup_rel | ( | dfs_t * | dfs, |
| dfs_obj_t * | parent, | ||
| const char * | name, | ||
| int | flags, | ||
| dfs_obj_t ** | obj, | ||
| mode_t * | mode, | ||
| struct stat * | stbuf ) |
Lookup an entry in the parent object and return the associated open object and mode of that entry. If the entry is a symlink, the symlink value is not resolved and the user can decide what to do to further resolve the value of the symlink. The object must be released with dfs_release().
| [in] | dfs | Pointer to the mounted file system. |
| [in] | parent | Opened parent directory object. If NULL, use root obj. This is useful in cases where the creator/opener is working in a flat namespace and doesn't need to lookup/release the root object. |
| [in] | name | Link name of the object to create/open. |
| [in] | flags | Access flags to open with (O_RDONLY or O_RDWR). |
| [out] | obj | Pointer to the object looked up. |
| [out] | mode | Optional mode_t of object looked up. |
| [out] | stbuf | Optional stat struct of object looked up. |
| int dfs_mkdir | ( | dfs_t * | dfs, |
| dfs_obj_t * | parent, | ||
| const char * | name, | ||
| mode_t | mode, | ||
| daos_oclass_id_t | cid ) |
Create a directory.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | parent | Opened parent directory object. If NULL, use root obj. |
| [in] | name | Link name of new dir. |
| [in] | mode | mkdir mode. |
| [in] | cid | DAOS object class id (pass 0 for default MAX_RW). |
| int dfs_mount | ( | daos_handle_t | poh, |
| daos_handle_t | coh, | ||
| int | flags, | ||
| dfs_t ** | dfs ) |
Mount a file system over DAOS. The pool and container handle must remain connected/open until after dfs_umount() is called; otherwise access to the dfs namespace will fail.
The mount will create a root directory (DAOS object) for the file system. The user will associate the dfs object returned with a mount point.
| [in] | poh | Pool connection handle |
| [in] | coh | Container open handle. |
| [in] | flags | Mount flags (O_RDONLY or O_RDWR). |
| [out] | dfs | Pointer to the file system object created. |
| int dfs_move | ( | dfs_t * | dfs, |
| dfs_obj_t * | parent, | ||
| const char * | name, | ||
| dfs_obj_t * | new_parent, | ||
| const char * | new_name, | ||
| daos_obj_id_t * | oid ) |
Move/rename an object.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | parent | Source parent directory object. If NULL, use root obj. |
| [in] | name | Link name of object. |
| [in] | new_parent | Target parent directory object. If NULL, use root obj. |
| [in] | new_name | New link name of object. |
| [out] | oid | Optional: return the internal object ID of the removed obj if the move clobbered it. |
| int dfs_obj2id | ( | dfs_obj_t * | obj, |
| daos_obj_id_t * | oid ) |
Convert from a dfs_obj_t to a daos_obj_id_t.
| [in] | obj | Object to convert |
| [out] | oid | Daos object ID. |
| int dfs_obj_anchor_set | ( | dfs_obj_t * | obj, |
| uint32_t | index, | ||
| daos_anchor_t * | anchor ) |
Set an anchor with an index based on split done with dfs_obj_anchor_split. The anchor passed will be re-intialized and set to start and finish iteration based on the specified index.
| [in] | obj | Dir object to split anchor for. |
| [in] | index | Index of set this anchor for iteration. |
| [in,out] | anchor | Hash anchor to set. |
| int dfs_obj_anchor_split | ( | dfs_obj_t * | obj, |
| uint32_t * | nr, | ||
| daos_anchor_t * | anchors ) |
Provide a function for large directories to split an anchor to be able to execute a parallel readdir or iterate. This routine suggests the optimal number of anchors to use instead of just 1 and optionally returns all those anchors. The user would allocate the array of anchors after querying the number of anchors needed. Alternatively, user does not provide an array and can call dfs_obj_anchor_set() for every anchor to set.
The user could suggest how many anchors to split the iteration over. This feature is not supported yet.
| [in] | obj | Dir object to split anchor for. |
| [in,out] | nr | [in]: Number of anchors requested and allocated in anchors. Pass 0 for DAOS to recommend split num. [out]: Number of anchors recommended if 0 is passed in. |
| [in] | anchors | Optional array of anchors that are split. |
| int dfs_obj_get_info | ( | dfs_t * | dfs, |
| dfs_obj_t * | obj, | ||
| dfs_obj_info_t * | info ) |
Retrieve some attributes of DFS object. Those include the object class and the chunk size.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Open object handle to query. |
| [out] | info | info object container object class, chunks size, etc. |
Create a dfs object from global representation data. This has to be closed with dfs_release().
| [in] | dfs | Pointer to the mounted file system. |
| [in] | flags | Access flags (O_RDONLY/O_RDWR/O_WRONLY). If 0, inherit flags of serialized object handle. |
| [in] | glob | Global (shared) representation of a collective handle to be extracted |
| [out] | obj | Returned open object handle |
Convert a local DFS object to global representation data which can be shared with peer processes. If glob->iov_buf is set to NULL, the actual size of the global handle is returned through glob->iov_buf_len. This function does not involve any communication and does not block.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | DFS Object to serialize |
| [out] | glob | pointer to iov of the buffer to store obj information |
Set the chunk size on a directory for new files or sub-dirs that are created in that dir. This does not change the chunk size for existing files or dirs in that directory. Note that this is only supported on directories and will fail if called on non-directory objects.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Open object handle to access. |
| [in] | flags | Flags for setting chunk size (currently ignored) |
| [in] | csize | Chunk size to set object to. |
Set the object class on a directory for new files or sub-dirs that are created in that dir. This does not change the chunk size for existing files or dirs in that directory, nor it does change the object class of the directory itself. Note that this is only supported on directories and will fail if called on non-directory objects.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Open object handle to access. |
| [in] | flags | Flags for setting oclass (currently ignored) |
| [in] | cid | object class. |
| int dfs_open | ( | dfs_t * | dfs, |
| dfs_obj_t * | parent, | ||
| const char * | name, | ||
| mode_t | mode, | ||
| int | flags, | ||
| daos_oclass_id_t | cid, | ||
| daos_size_t | chunk_size, | ||
| const char * | value, | ||
| dfs_obj_t ** | obj ) |
Create/Open a directory, file, or Symlink. The object must be released with dfs_release().
| [in] | dfs | Pointer to the mounted file system. |
| [in] | parent | Opened parent directory object. If NULL, use root obj. This is useful in cases where the creator/opener is working in a flat namespace and doesn't need to lookup/release the root object. |
| [in] | name | Link name of the object to create/open. |
| [in] | mode | mode_t (permissions + type). |
| [in] | flags | Access flags (handles: O_RDONLY, O_RDWR, O_EXCL, O_CREAT, O_TRUNC). |
| [in] | cid | DAOS object class id (pass 0 for default MAX_RW). Valid on create only; ignored otherwise. |
| [in] | chunk_size | Chunk size of the array object to be created. (pass 0 for default 1 MiB chunk size). Valid on file create only; ignored otherwise. |
| [in] | value | Symlink value (NULL if not syml). |
| [out] | obj | Pointer to object opened. |
Set stat attributes for a file and fetch new values. If the object is a symlink the link itself is modified. See dfs_stat() for which entries are filled. While the set-user/group-id bits in stbuf::st_mode are stored by libdfs, it up to the caller to implement support for the associated functionality since libdfs does not provide any way to execute binaries.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Open object (File, dir or syml) to modify. |
| [in,out] | stbuf | [in]: Stat struct with the members set. [out]: Stat struct with all valid members filled. |
| [in] | flags | Bitmask of flags to set |
Same as dfs_stat but works directly on an open object.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Open object (File, dir or syml) to stat. |
| [out] | stbuf | Stat struct with the members above filled. |
| int dfs_pipeline_create | ( | dfs_t * | dfs, |
| dfs_predicate_t | pred, | ||
| uint64_t | flags, | ||
| dfs_pipeline_t ** | dpipe ) |
Create a pipeline object to be used during readdir with filter. Should be destroyed with dfs_pipeline_destroy().
| [in] | dfs | Pointer to the mounted file system. |
| [in] | pred | Predicate condition values (name/regex, newer timestamp, etc.). |
| [in] | flags | Pipeline flags (conditions to apply). |
| [out] | dpipe | Pipeline object created. |
| int dfs_pipeline_destroy | ( | dfs_pipeline_t * | dpipe | ) |
Destroy pipeline object.
| [in] | dpipe | Pipeline object. |
| int dfs_pool_get | ( | dfs_t * | dfs, |
| daos_handle_t * | poh ) |
Retrieve the open pool handle on the DFS mount. This is refcounted internally and must be released with dfs_pool_put().
| [in] | dfs | Pointer to the mounted file system. |
| [out] | poh | Open pool handle. |
| int dfs_pool_put | ( | dfs_t * | dfs, |
| daos_handle_t | poh ) |
Release refcount of pool handle taken by dfs_pool_get().
| [in] | dfs | Pointer to the mounted file system. |
| [out] | poh | Pool handle that was returned from dfs_pool_get(). |
Punch a hole in the file starting at offset to len. If len is set to DFS_MAX_FSIZE, this will be equivalent to a truncate operation to shrink or extend the file to offset bytes depending on the file size.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Opened file object. |
| [in] | offset | offset of file to punch at. |
| [in] | len | number of bytes to punch. |
| int dfs_query | ( | dfs_t * | dfs, |
| dfs_attr_t * | attr ) |
Query attributes of a DFS mount.
| [in] | dfs | Pointer to the mounted file system. |
| [out] | attr | Attributes on the DFS container. |
| int dfs_read | ( | dfs_t * | dfs, |
| dfs_obj_t * | obj, | ||
| d_sg_list_t * | sgl, | ||
| daos_off_t | off, | ||
| daos_size_t * | read_size, | ||
| daos_event_t * | ev ) |
Read data from the file object, and return actual data read.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Opened file object. |
| [in] | sgl | Scatter/Gather list for data buffer. |
| [in] | off | Offset into the file to read from. |
| [out] | read_size | How much data is actually read. |
| [in] | ev | Completion event, it is optional and can be NULL. Function will run in blocking mode if ev is NULL. |
| int dfs_readdir | ( | dfs_t * | dfs, |
| dfs_obj_t * | obj, | ||
| daos_anchor_t * | anchor, | ||
| uint32_t * | nr, | ||
| struct dirent * | dirs ) |
directory readdir.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Opened directory object. |
| [in,out] | anchor | Hash anchor for the next call, it should be set to zeroes for the first call, it should not be changed by caller between calls. |
| [in,out] | nr | [in]: number of dirents allocated in dirs. [out]: number of returned dirents. |
| [in,out] | dirs | [in] preallocated array of dirents. [out]: dirents returned with d_name filled only. |
| int dfs_readdir_with_filter | ( | dfs_t * | dfs, |
| dfs_obj_t * | obj, | ||
| dfs_pipeline_t * | dpipe, | ||
| daos_anchor_t * | anchor, | ||
| uint32_t * | nr, | ||
| struct dirent * | dirs, | ||
| daos_obj_id_t * | oids, | ||
| daos_size_t * | csizes, | ||
| uint64_t * | nr_scanned ) |
Same as dfs_readdir() but this additionally applies a filter created with dfs_pipeline_create() on the entries that are enumerated. This function also optionally returns the object ID of each dirent if requested through a pre-allocated OID input array.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Opened directory object. |
| [in] | dpipe | DFS pipeline filter. |
| [in,out] | anchor | Hash anchor for the next call, it should be set to zeroes for the first call, it should not be changed by caller between calls. |
| [in,out] | nr | [in]: number of dirents allocated in dirs. [out]: number of returned dirents. |
| [in,out] | dirs | [in] preallocated array of dirents. [out]: dirents returned with d_name filled only. |
| [in,out] | oids | [in] Optional preallocated array of object IDs. [out]: Object ID associated with each dirent that was read. |
| [in,out] | csizes | [in] Optional preallocated array of sizes. [out]: chunk size associated with each dirent that was read. |
| [out] | nr_scanned | Total number of entries scanned by readdir before returning. |
| int dfs_readdirplus | ( | dfs_t * | dfs, |
| dfs_obj_t * | obj, | ||
| daos_anchor_t * | anchor, | ||
| uint32_t * | nr, | ||
| struct dirent * | dirs, | ||
| struct stat * | stbufs ) |
directory readdir + stat.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Opened directory object. |
| [in,out] | anchor | Hash anchor for the next call, it should be set to zeroes for the first call, it should not be changed by caller between calls. |
| [in,out] | nr | [in]: number of dirents allocated in dirs. [out]: number of returned dirents. |
| [in,out] | dirs | [in] preallocated array of dirents. [out]: dirents returned with d_name filled only. |
| [in,out] | stbufs | [in] preallocated array of struct stat. [out]: stat of every entry in dirs. |
| int dfs_readx | ( | dfs_t * | dfs, |
| dfs_obj_t * | obj, | ||
| dfs_iod_t * | iod, | ||
| d_sg_list_t * | sgl, | ||
| daos_size_t * | read_size, | ||
| daos_event_t * | ev ) |
Non-contiguous read interface to a DFS file. Same as dfs_read with the ability to have a segmented file layout to read.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Opened file object. |
| [in] | iod | IO descriptor for list-io. |
| [in] | sgl | Scatter/Gather list for data buffer. |
| [out] | read_size | How much data is actually read. |
| [in] | ev | Completion event, it is optional and can be NULL. Function will run in blocking mode if ev is NULL. |
| int dfs_release | ( | dfs_obj_t * | obj | ) |
Close/release open object.
| [in] | obj | Object to release. |
| int dfs_remove | ( | dfs_t * | dfs, |
| dfs_obj_t * | parent, | ||
| const char * | name, | ||
| bool | force, | ||
| daos_obj_id_t * | oid ) |
Remove an object from parent directory. If object is a directory and is non-empty; this will fail unless force option is true. If object is a symlink, the symlink is removed.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | parent | Opened parent directory object. If NULL, use root obj. |
| [in] | name | Name of object to remove in parent dir. |
| [in] | force | If true, remove dir even if non-empty. |
| [in] | oid | Optionally return the DAOS Object ID of the removed obj. |
Remove extended attribute of an open object. If object is a symlink, the link itself is interogated.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Open object where xattr will be removed. |
| [in] | name | Name of xattr to remove. |
| int dfs_set_prefix | ( | dfs_t * | dfs, |
| const char * | prefix ) |
Optionally set a prefix on the dfs mount where all paths passed to dfs_lookup are trimmed off that prefix. This is helpful when using DFS API with a dfuse mount and the user would like to reference files in the dfuse mount instead of the absolute path from the root of the DFS container.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | prefix | absolute prefix to trim off path to dfs_lookup. Passing NULL unsets the prefix. |
| int dfs_setxattr | ( | dfs_t * | dfs, |
| dfs_obj_t * | obj, | ||
| const char * | name, | ||
| const void * | value, | ||
| daos_size_t | size, | ||
| int | flags ) |
Set extended attribute on an open object (File, dir, syml). If object is a symlink, the value is set on the symlink itself.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Open object where xattr will be added. |
| [in] | name | Name of xattr to add. |
| [in] | value | Value of xattr. |
| [in] | size | Size in bytes of the value. |
| [in] | flags | Set flags. passing 0 does not check for xattr existence. XATTR_CREATE: create or fail if xattr exists. XATTR_REPLACE: replace or fail if xattr does not exist. |
stat attributes of an entry. If object is a symlink, the link itself is interogated. The following elements of the stat struct are populated (the rest are set to 0): mode_t st_mode; uid_t st_uid; gid_t st_gid; off_t st_size; blkcnt_t st_blocks struct timespec st_atim; struct timespec st_mtim; struct timespec st_ctim;
| [in] | dfs | Pointer to the mounted file system. |
| [in] | parent | Opened parent directory object. If NULL, use root obj. |
| [in] | name | Link name of the object. Can be NULL if parent is root, which means operation will be on root object. |
| [out] | stbuf | Stat struct with the members above filled. |
| int dfs_suggest_oclass | ( | dfs_t * | dfs, |
| const char * | hint, | ||
| daos_oclass_id_t * | cid ) |
Suggest an oclass for creating DFS objects given a hint from the user of the format: obj:val where obj can be either file or dir/directory and val from: single: tiny files or directories to be single sharded. max: large files or directories to be max shared.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | hint | hint from user for a file or directory |
| [out] | cid | object class suggested to use |
| int dfs_sync | ( | dfs_t * | dfs | ) |
Sync to commit the latest epoch on the container. This applies to the entire namespace and not to a particular file/directory.
TODO: This should take a persistent snapshot at current timestamp.
| [in] | dfs | Pointer to the mounted file system. |
| int dfs_umount | ( | dfs_t * | dfs | ) |
Unmount a DAOS file system. This closes open handles to the root object and commits the epoch at current timestamp. The internal dfs struct is freed, so further access to that dfs will be invalid.
| [in] | dfs | Pointer to the mounted file system. |
A DFS object open handle has links to its parent (oid) and the entry name of that object in that parent. In some cases a user would want to update the oh of an object in case of a rename. This API would allow modifying an existing open handle of an object to change it's parent and it's entry name. Note this is a local operation and doesn't change anything on the storage.
| [in] | obj | Open object handle to update. |
| [in] | src_obj | Open object handle of the object whose parent will be used as the new parent of obj. |
| [in] | name | Optional new name of entry in parent. Pass NULL to leave the entry name unchanged. |
| int dfs_write | ( | dfs_t * | dfs, |
| dfs_obj_t * | obj, | ||
| d_sg_list_t * | sgl, | ||
| daos_off_t | off, | ||
| daos_event_t * | ev ) |
Write data to the file object.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Opened file object. |
| [in] | sgl | Scatter/Gather list for data buffer. |
| [in] | off | Offset into the file to write to. |
| [in] | ev | Completion event, it is optional and can be NULL. Function will run in blocking mode if ev is NULL. |
| int dfs_writex | ( | dfs_t * | dfs, |
| dfs_obj_t * | obj, | ||
| dfs_iod_t * | iod, | ||
| d_sg_list_t * | sgl, | ||
| daos_event_t * | ev ) |
Non-contiguous write interface to a DFS file.
| [in] | dfs | Pointer to the mounted file system. |
| [in] | obj | Opened file object. |
| [in] | iod | IO descriptor of file view. |
| [in] | sgl | Scatter/Gather list for data buffer. |
| [in] | ev | Completion event, it is optional and can be NULL. Function will run in blocking mode if ev is NULL. |
1.12.0