DAOS API: src/include/daos_uns.h File Reference

| DAOS API (v2.1 - dev)

Loading...
Searching...
No Matches
daos_uns.h File Reference

Go to the source code of this file.

## Data Structures
struct | duns_attr_t

## Macros
#define | DUNS_XATTR_NAME "user.daos"
#define | DUNS_MAX_XATTR_LEN 170
#define | DUNS_XATTR_FMT "DAOS.%s://%36s/%36s"
#define | DUNS_LUSTRE_XATTR_FMT "%36s/%36s"

## Enumerations
enum | { DUNS_NO_PREFIX = (1 << 0) , DUNS_NO_REVERSE_LOOKUP = (1 << 1) , DUNS_NO_CHECK_PATH = (1 << 2) }

## Functions
int | duns_create_path (daos_handle_t poh, const char *path, struct duns_attr_t *attrp)
int | duns_resolve_path (const char *path, struct duns_attr_t *attr)
int | duns_destroy_path (daos_handle_t poh, const char *path)
int | duns_parse_attr (char *str, daos_size_t len, struct duns_attr_t *attr)
int | duns_set_sys_name (struct duns_attr_t *attrp, const char *sys)
void | duns_destroy_attr (struct duns_attr_t *attrp)
int | duns_link_cont (daos_handle_t poh, const char *cont, const char *path)

## Detailed Description

DAOS Unified Namespace API

The unified namespace API provides functions and tools to be able to link files and directories in a system namespace to a location in the DAOS tier (pool and container), in addition to other properties such as object class.

Definition in file daos_uns.h.

## Macro Definition Documentation

## ◆ DUNS_LUSTRE_XATTR_FMT

#define DUNS_LUSTRE_XATTR_FMT "%36s/%36s"

Lustre specific foreign LOV/LMV format (container type will be encoded in lfm_flag field and extra slashes will be added when needed by foreign_symlink Lustre code)

Definition at line 136 of file daos_uns.h.

## ◆ DUNS_MAX_XATTR_LEN

#define DUNS_MAX_XATTR_LEN 170

Length of the extended attribute

Definition at line 128 of file daos_uns.h.

## ◆ DUNS_XATTR_FMT

#define DUNS_XATTR_FMT "DAOS.%s://%36s/%36s"

Format of daos attributes in the extended attribute

Definition at line 130 of file daos_uns.h.

## ◆ DUNS_XATTR_NAME

#define DUNS_XATTR_NAME "user.daos"

extended attribute name that will store the UNS info

Definition at line 126 of file daos_uns.h.

## Enumeration Type Documentation

## ◆ anonymous enum

anonymous enum

Flags for duns_resolve_path

Definition at line 24 of file daos_uns.h.

## Function Documentation

## ◆ duns_create_path()

int duns_create_path | ( | daos_handle_t | poh,
|  | const char * | path,
|  | struct duns_attr_t * | attrp )

Create a special directory (POSIX) or file (HDF5) depending on the container type, and create a new DAOS container. The uuid of the container can be either passed in attrp->da_cuuid (deprecated) or generated internally and returned in da_cont. The extended attributes are set on the dir/file created that points to pool uuid, container uuid. This is to be used in a unified namespace solution to be able to map a path in the unified namespace to a location in the DAOS tier. The container and pool can have labels, but the UNS stores the uuids only and so labels are ignored in attrp. The user is not required to call duns_destory_attrs on attrp as this call does not allocate any buffers in attrp.

Parameters

  [in] | poh | Pool handle
  [in] | path | Valid path in an existing namespace.
  [in,out] | attrp | Struct containing the attributes. The uuid of the container created is returned in da_cuuid.

Returns
  0 on Success. errno code on failure.

## ◆ duns_destroy_attr()

void duns_destroy_attr | ( | struct duns_attr_t * | attrp | ) |

Free internal buffers allocated by the DUNS on the attr struct.

Parameters

  [in] | attrp | Attr pointer that was passed in to duns_resolve_path.

## ◆ duns_destroy_path()

int duns_destroy_path | ( | daos_handle_t | poh,
|  | const char * | path )

Destroy a container and remove the path associated with it in the UNS.

Parameters

  [in] | poh | Pool handle
  [in] | path | Valid path in an existing namespace.

Returns
  0 on Success. errno code on failure.

## ◆ duns_link_cont()

int duns_link_cont | ( | daos_handle_t | poh,
|  | const char * | cont,
|  | const char * | path )

Create a special directory (POSIX) or file (HDF5) depending on the container type that links to an existing DAOS container. This is similar to duns_create_path except for the fact that a new container is not created, and the container that is passed should be an existing container in the poh. Note that it is possible that a user creates multiple paths in the namespace to the same container, however when any path is destroyed, the container is destroyed with it, leaving other dangling paths in the namespace to a non-existing container. It is the responsibility of the user to cleanup those dangling paths in the namespace and ensure that the container is not going to be accessed anymore through the remaining paths after the destroy operation on any of the paths that were created to that container.

Parameters

  [in] | poh | Pool handle
  [in] | cont | Existing container in the pool to create the uns path to.
  [in] | path | Path in an existing namespace to create with the uns link to the container.

Returns
  0 on Success. errno code on failure.

## ◆ duns_parse_attr()

int duns_parse_attr | ( | char * | str,
|  | daos_size_t | len,
|  | struct duns_attr_t * | attr )

Convert a string into duns_attr_t.

Parameters

  [in] | str | Input string
  [in] | len | Length of input string
  [out] | attr | Struct containing the attrs on the path.

Returns
  0 on Success. errno code on failure.

## ◆ duns_resolve_path()

int duns_resolve_path | ( | const char * | path,
|  | struct duns_attr_t * | attr )

Retrieve the pool and container uuids from a path corresponding to a DAOS location. If this was a path created with duns_create_path(), then this call would return the pool, container, and type values in the attr struct (the rest of the values are not populated. By default, this call does a reverse lookup on the realpath until it finds an entry in the path that has the UNS attr. The rest of the path from that entry point is returned in attr.da_rel_path. If the entire path does not have the entry, ENODATA error is returned. To avoid doing the reverse lookup and check only that last entry, set attr.da_no_reverse_lookup.

To avoid going through the UNS if the user knows the pool and container uuids, a special format can be passed as a prefix for a "fast path", and this call would parse those out in the attr struct and return whatever is left from the path in attr.da_rel_path. This mode is provided as a convenience to IO middleware libraries and to settle on a unified format for a mode where users know the pool and container uuids and would just like to pass them directly instead of a traditional path. The format of this path should be: daos://pool_uuid/container_uuid/xyz xyz here can be a path relative to the root of a POSIX container if the user is accessing a posix container, or it can be empty for example in the case of an HDF5 file.

User is responsible to call duns_destroy_attr on attr to free the internal buffers allocated.

Parameters

  [in] | path | Valid path in an existing namespace.
  [in,out] | attr | Struct containing the attrs on the path.

Returns
  0 on Success. errno code on failure.

## ◆ duns_set_sys_name()

int duns_set_sys_name | ( | struct duns_attr_t * | attrp,
|  | const char * | sys )

Set the system name in the duns struct in case it was obtained in a different way than using duns_resolve_path().

Parameters

  [in] | attrp | Attr pointer
  [in] | sys | DAOS System name

Returns
  0 on Success. errno code on failure.