DAOS API (v2.1 - dev)
Loading...
Searching...
No Matches
daos_fs_sys.h File Reference
#include <dirent.h>
#include <daos.h>
#include <daos_fs.h>

Go to the source code of this file.

Macros

#define DFS_SYS_NO_CACHE   1
 
#define DFS_SYS_NO_LOCK   2
 

Typedefs

typedef struct dfs_sys dfs_sys_t
 

Functions

int dfs_sys_connect (const char *pool, const char *sys, const char *cont, int mflags, int sflags, dfs_attr_t *attr, dfs_sys_t **dfs_sys)
 
int dfs_sys_disconnect (dfs_sys_t *dfs_sys)
 
int dfs_sys_local2global_all (dfs_sys_t *dfs_sys, d_iov_t *glob)
 
int dfs_sys_global2local_all (int mflags, int sflags, d_iov_t glob, dfs_sys_t **dfs_sys)
 
int dfs_sys_mount (daos_handle_t poh, daos_handle_t coh, int mflags, int sflags, dfs_sys_t **dfs_sys)
 
int dfs_sys_umount (dfs_sys_t *dfs_sys)
 
int dfs_sys_local2global (dfs_sys_t *dfs_sys, d_iov_t *glob)
 
int dfs_sys_global2local (daos_handle_t poh, daos_handle_t coh, int mflags, int sflags, d_iov_t glob, dfs_sys_t **dfs_sys)
 
int dfs_sys2base (dfs_sys_t *dfs_sys, dfs_t **dfs)
 
int dfs_sys_access (dfs_sys_t *dfs_sys, const char *path, int mask, int flags)
 
int dfs_sys_chmod (dfs_sys_t *dfs_sys, const char *path, mode_t mode)
 
int dfs_sys_chown (dfs_sys_t *dfs_sys, const char *path, uid_t uid, gid_t gid, int flags)
 
int dfs_sys_setattr (dfs_sys_t *dfs_sys, const char *path, struct stat *stbuf, int flags, int sflags)
 
int dfs_sys_utimens (dfs_sys_t *dfs_sys, const char *path, const struct timespec times[2], int flags)
 
int dfs_sys_stat (dfs_sys_t *dfs_sys, const char *path, int flags, struct stat *stbuf)
 
int dfs_sys_mknod (dfs_sys_t *dfs_sys, const char *path, mode_t mode, daos_oclass_id_t cid, daos_size_t chunk_size)
 
int dfs_sys_listxattr (dfs_sys_t *dfs_sys, const char *path, char *list, daos_size_t *size, int flags)
 
int dfs_sys_getxattr (dfs_sys_t *dfs_sys, const char *path, const char *name, void *value, daos_size_t *size, int flags)
 
int dfs_sys_setxattr (dfs_sys_t *dfs_sys, const char *path, const char *name, const void *value, daos_size_t size, int flags, int sflags)
 
int dfs_sys_removexattr (dfs_sys_t *dfs_sys, const char *path, const char *name, int flags)
 
int dfs_sys_readlink (dfs_sys_t *dfs_sys, const char *path, char *buf, daos_size_t *size)
 
int dfs_sys_symlink (dfs_sys_t *dfs_sys, const char *target, const char *path)
 
int dfs_sys_open (dfs_sys_t *dfs_sys, const char *path, mode_t mode, int flags, daos_oclass_id_t cid, daos_size_t chunk_size, const char *value, dfs_obj_t **obj)
 
int dfs_sys_close (dfs_obj_t *obj)
 
int dfs_sys_read (dfs_sys_t *dfs_sys, dfs_obj_t *obj, void *buf, daos_off_t off, daos_size_t *size, daos_event_t *ev)
 
int dfs_sys_write (dfs_sys_t *dfs_sys, dfs_obj_t *obj, const void *buf, daos_off_t off, daos_size_t *size, daos_event_t *ev)
 
int dfs_sys_punch (dfs_sys_t *dfs_sys, const char *path, daos_off_t offset, daos_off_t len)
 
int dfs_sys_remove (dfs_sys_t *dfs_sys, const char *path, bool force, daos_obj_id_t *oid)
 
int dfs_sys_remove_type (dfs_sys_t *dfs_sys, const char *path, bool force, mode_t mode, daos_obj_id_t *oid)
 
int dfs_sys_mkdir (dfs_sys_t *dfs_sys, const char *dir, mode_t mode, daos_oclass_id_t cid)
 
int dfs_sys_opendir (dfs_sys_t *dfs_sys, const char *dir, int flags, DIR **dirp)
 
int dfs_sys_closedir (DIR *dirp)
 
int dfs_sys_readdir (dfs_sys_t *dfs_sys, DIR *dirp, struct dirent **dirent)
 

Detailed Description

(C) Copyright 2018-2022 Intel Corporation.

SPDX-License-Identifier: BSD-2-Clause-Patent

DAOS File System "Sys" API

The DFS Sys API provides a simplified layer directly on top of the DFS API that is more similar to the equivalent POSIX libraries. While the DFS Sys API stands on its own, the DFS API can be used directly by getting the DFS Object with dfs_sys2base().

Definition in file daos_fs_sys.h.

Macro Definition Documentation

◆ DFS_SYS_NO_CACHE

#define DFS_SYS_NO_CACHE   1

Mount flags for dfs_sys_mount. By default, mount with caching and locking turned on. Turn off directory caching

Definition at line 29 of file daos_fs_sys.h.

◆ DFS_SYS_NO_LOCK

#define DFS_SYS_NO_LOCK   2

Turn off locking. Useful for single-threaded applications.

Definition at line 30 of file daos_fs_sys.h.

Typedef Documentation

◆ dfs_sys_t

typedef struct dfs_sys dfs_sys_t

struct holding attributes for the dfs_sys calls

Definition at line 33 of file daos_fs_sys.h.

Function Documentation

◆ dfs_sys2base()

int dfs_sys2base ( dfs_sys_t * dfs_sys,
dfs_t ** dfs )

Get the underlying dfs_t from the dfs_sys_t. This should not be closed with dfs_umount().

Parameters
[in]dfs_sysPointer to the mounted file system.
[out]dfsPointer to the underlying dfs_t.
Returns
0 on success, errno code on failure.

◆ dfs_sys_access()

int dfs_sys_access ( dfs_sys_t * dfs_sys,
const char * path,
int mask,
int flags )

Check access permissions on a path. Similar to Linux access(2). By default, symlinks are dereferenced.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of object.
[in]maskaccessibility 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.
[in]flagsAccess flags (O_NOFOLLOW).
Returns
0 on success, errno code on failure.

◆ dfs_sys_chmod()

int dfs_sys_chmod ( dfs_sys_t * dfs_sys,
const char * path,
mode_t mode )

Change permission access bits. Symlinks are dereferenced.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of object.
[in]modeNew permission access modes. For now, we don't support the sticky bit, setuid, and setgid.
Returns
0 on success, errno code on failure.

◆ dfs_sys_chown()

int dfs_sys_chown ( dfs_sys_t * dfs_sys,
const char * path,
uid_t uid,
gid_t gid,
int flags )

Change owner/group. Symlinks are dereferenced. 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.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of object.
[in]uidchange owner of file (-1 to leave unchanged).
[in]gidchange group of file (-1 to leave unchanged).
[in]flags(O_NOFOLLOW)
Returns
0 on success, errno code on failure.

◆ dfs_sys_close()

int dfs_sys_close ( dfs_obj_t * obj)

Close/release open object.

Parameters
[in]objObject to release.
Returns
0 on success, errno code on failure.

◆ dfs_sys_closedir()

int dfs_sys_closedir ( DIR * dirp)

Close a directory opened with dfs_sys_opendir().

Parameters
[in]dirpPointer to the open directory.
Returns
0 on success, errno code on failure.

◆ dfs_sys_connect()

int dfs_sys_connect ( const char * pool,
const char * sys,
const char * cont,
int mflags,
int sflags,
dfs_attr_t * attr,
dfs_sys_t ** dfs_sys )

Wrapper around dfs_connect for the dfs_sys API.

Parameters
[in]poolPool label.
[in]sysDAOS system name to use for the pool connect. Pass NULL to use the default system.
[in]contContainer label.
[in]mflagsMount flags (O_RDONLY or O_RDWR, O_CREAT). O_CREAT attempts to create the DFS container if it doesn't exists.
[in]sflagsSys flags (DFS_SYS_NO_CACHE or DFS_SYS_NO_LOCK)
[in]attrOptional set of properties and attributes to set on the container (if being created). Pass NULL to use default.
[out]dfs_sysPointer to the file system object created.
Returns
0 on success, errno code on failure.

◆ dfs_sys_disconnect()

int dfs_sys_disconnect ( dfs_sys_t * dfs_sys)

Umount the DFS sys namespace, and release the ref count on the container and pool handles. This should be called on a dfs_sys mount created with dfs_sys_connect() and not dfs_sys_mount().

Parameters
[in]dfs_sysPointer to the mounted file system from dfs_sys_connect().
Returns
0 on success, errno code on failure.

◆ dfs_sys_getxattr()

int dfs_sys_getxattr ( dfs_sys_t * dfs_sys,
const char * path,
const char * name,
void * value,
daos_size_t * size,
int flags )

Get extended attribute of a path. By default, if path is a symlink, the link itself is interrogated.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of object.
[in]nameName of xattr to get.
[out]valueBuffer to place value of xattr.
[in,out]size[in]: Size of buffer value. [out]: Actual size of xattr.
[in]flags(O_NOFOLLOW)
Returns
0 on success, errno code on failure. ERANGE If size is too small.

◆ dfs_sys_global2local()

int dfs_sys_global2local ( daos_handle_t poh,
daos_handle_t coh,
int mflags,
int sflags,
d_iov_t glob,
dfs_sys_t ** dfs_sys )

Create a dfs_sys mount from global representation data. This has to be closed with dfs_sys_umount().

Parameters
[in]pohPool connection handle.
[in]cohContainer open handle.
[in]mflagsMount flags (O_RDONLY or O_RDWR). If 0, inherit flags of serialized DFS Sys handle.
[in]sflagsSys flags (DFS_SYS_NO_CACHE or DFS_SYS_NO_LOCK). This is not inherited from the DFS Sys handle.
[in]globGlobal (shared) representation of a collective handle to be extracted.
[out]dfs_sysReturned dfs_sys mount.

◆ dfs_sys_global2local_all()

int dfs_sys_global2local_all ( int mflags,
int sflags,
d_iov_t glob,
dfs_sys_t ** dfs_sys )

Create a dfs_sys mount from global representation data. This has to be closed with dfs_sys_disconnect().

Parameters
[in]mflagsMount flags (O_RDONLY or O_RDWR). If 0, inherit flags of serialized DFS Sys handle.
[in]sflagsSys flags (DFS_SYS_NO_CACHE or DFS_SYS_NO_LOCK). This is not inherited from the DFS Sys handle.
[in]globGlobal (shared) representation of a collective handle to be extracted.
[out]dfs_sysReturned dfs_sys mount.

◆ dfs_sys_listxattr()

int dfs_sys_listxattr ( dfs_sys_t * dfs_sys,
const char * path,
char * list,
daos_size_t * size,
int flags )

list extended attributes of a path and place them all in a buffer NULL terminated one after the other. By default, if path is a symlink, the link itself is interrogated.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of object.
[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.
[in]flags(O_NOFOLLOW)
Returns
0 on success, errno code on failure. ERANGE If size is too small.

◆ dfs_sys_local2global()

int dfs_sys_local2global ( dfs_sys_t * dfs_sys,
d_iov_t * glob )

Convert a local dfs_sys 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.

Parameters
[in]dfs_sysvalid dfs_sys mount to be shared.
[out]globpointer to iov of the buffer to store mount information.
Returns
0 on success, errno code on failure.

◆ dfs_sys_local2global_all()

int dfs_sys_local2global_all ( dfs_sys_t * dfs_sys,
d_iov_t * glob )

Convert a local dfs_sys 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.

Parameters
[in]dfs_sysvalid dfs_sys mount to be shared.
[out]globpointer to iov of the buffer to store mount information.
Returns
0 on success, errno code on failure.

◆ dfs_sys_mkdir()

int dfs_sys_mkdir ( dfs_sys_t * dfs_sys,
const char * dir,
mode_t mode,
daos_oclass_id_t cid )

Create a directory.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]dirLink path of new dir.
[in]modemkdir mode.
[in]cidDAOS object class id (pass 0 for default MAX_RW).
Returns
0 on success, errno code on failure.

◆ dfs_sys_mknod()

int dfs_sys_mknod ( dfs_sys_t * dfs_sys,
const char * path,
mode_t mode,
daos_oclass_id_t cid,
daos_size_t chunk_size )

Create a file or directory.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of new object.
[in]modemode_t (permissions + type).
[in]cidDAOS object class id (pass 0 for default MAX_RW). Valid on create only; ignored otherwise.
[in]chunk_sizeChunk size of the array object to be created. (pass 0 for default 1 MiB chunk size). Valid on file create only; ignored otherwise.
Returns
0 on success, errno code on failure. EEXIST If path already exists.

◆ dfs_sys_mount()

int dfs_sys_mount ( daos_handle_t poh,
daos_handle_t coh,
int mflags,
int sflags,
dfs_sys_t ** dfs_sys )

Mount a file system with dfs_mount and optionally initialize a cache.

Parameters
[in]pohPool connection handle.
[in]cohContainer open handle.
[in]mflagsMount flags (O_RDONLY or O_RDWR).
[in]sflagsSys flags (DFS_SYS_NO_CACHE or DFS_SYS_NO_LOCK)
[out]dfs_sysPointer to the file system object created.
Returns
0 on success, errno code on failure.

◆ dfs_sys_open()

int dfs_sys_open ( dfs_sys_t * dfs_sys,
const char * path,
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_sys_close().

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of the object to create/open.
[in]modemode_t (permissions + type).
[in]flagsAccess flags (handles: O_RDONLY, O_RDWR, O_EXCL, O_CREAT, O_TRUNC, O_NOFOLLOW).
[in]cidDAOS object class id (pass 0 for default MAX_RW). Valid on create only; ignored otherwise.
[in]chunk_sizeChunk size of the array object to be created. (pass 0 for default 1 MiB chunk size). Valid on file create only; ignored otherwise.
[in]valueSymlink value (NULL if not syml).
[out]objPointer to object opened.
Returns
0 on success, errno code on failure.

◆ dfs_sys_opendir()

int dfs_sys_opendir ( dfs_sys_t * dfs_sys,
const char * dir,
int flags,
DIR ** dirp )

Open a directory. The directory must be closed with dfs_sys_closedir().

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]dirLink path of dir.
[in]flags(O_NOFOLLOW)
[out]dirpPointer to the open directory.
Returns
0 on success, errno code on failure.

◆ dfs_sys_punch()

int dfs_sys_punch ( dfs_sys_t * dfs_sys,
const char * path,
daos_off_t offset,
daos_off_t len )

Punch a hole in the file starting at offset to len. If len is set to DFS_MAX_FSIZE, this will be a truncate operation to punch all bytes in the file above offset. If the file size is smaller than offset, the file is extended to offset and len is ignored.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of file.
[in]offsetoffset of file to punch at.
[in]lennumber of bytes to punch.
Returns
0 on success, errno code on failure.

◆ dfs_sys_read()

int dfs_sys_read ( dfs_sys_t * dfs_sys,
dfs_obj_t * obj,
void * buf,
daos_off_t off,
daos_size_t * size,
daos_event_t * ev )

Read data from the file object, and return actual data read.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]objOpened file object.
[in,out]buf[in]: Allocated buffer for data. [out]: Actual data read.
[in]offOffset into the file to read from.
[in,out]size[in]: Size of buffer passed in. [out]: Actual size of data read.
[in]evCompletion event, it is optional and can be NULL. Function will run in blocking mode if ev is NULL.
Returns
0 on success, errno code on failure.

◆ dfs_sys_readdir()

int dfs_sys_readdir ( dfs_sys_t * dfs_sys,
DIR * dirp,
struct dirent ** dirent )

Return the next directory entry in a directory opened by dfs_sys_readdir(), or NULL if there are no more entries.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]dirpPointer to open directory.
[out]direntPointer to the next directory entry. This is NULL if there are no more directory entries.
Returns
0 on success, errno code on failure.

◆ dfs_sys_readlink()

int dfs_sys_readlink ( dfs_sys_t * dfs_sys,
const char * path,
char * buf,
daos_size_t * size )

Retrieve Symlink value of path 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.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of object.
[in,out]buf[in]: Allocated buffer for value. [out]: Symlink value.
[in,out]size[in]: Size of buffer passed in. [out]: Actual size of value.
Returns
0 on success, errno code on failure.

◆ dfs_sys_remove()

int dfs_sys_remove ( dfs_sys_t * dfs_sys,
const char * path,
bool force,
daos_obj_id_t * oid )

Remove an object identified by path. 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. See dfs_remove() for details.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of object.
[in]forceIf true, remove dir even if non-empty.
[in]oidOptionally return the DAOS Object ID of the removed obj.
Returns
0 on success, errno code on failure.

◆ dfs_sys_remove_type()

int dfs_sys_remove_type ( dfs_sys_t * dfs_sys,
const char * path,
bool force,
mode_t mode,
daos_obj_id_t * oid )

Similar to dfs_sys_remove but optionally enforces a type check on the entry.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of object.
[in]forceIf true, remove dir even if non-empty.
[in]modemode_t (S_IFREG | S_IFDIR | S_IFLNK). Pass 0 skip the type check.
[out]oidOptionally return the DAOS Object ID of the removed obj.
Returns
0 on success, errno code on failure.

◆ dfs_sys_removexattr()

int dfs_sys_removexattr ( dfs_sys_t * dfs_sys,
const char * path,
const char * name,
int flags )

Remove extended attribute of a path. By default, if path is a symlink, the link itself is interogated.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of object.
[in]nameName of xattr to remove.
[in]flags(O_NOFOLLOW)
Returns
0 on success, errno code on failure.

◆ dfs_sys_setattr()

int dfs_sys_setattr ( dfs_sys_t * dfs_sys,
const char * path,
struct stat * stbuf,
int flags,
int sflags )

set stat attributes for a file and fetch new values. By default, if the object is a symlink the link itself is modified. See dfs_sys_stat() for which entries are filled.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of object.
[in,out]stbuf[in]: Stat struct with the members set. [out]: Stat struct with all valid members filled.
[in]flagsBitmask of flags to set.
[in]sflags(O_NOFOLLOW)
Returns
0 on Success. errno code on Failure.

◆ dfs_sys_setxattr()

int dfs_sys_setxattr ( dfs_sys_t * dfs_sys,
const char * path,
const char * name,
const void * value,
daos_size_t size,
int flags,
int sflags )

Set extended attribute on a path (file, dir, syml). By default, if path is a symlink, the value is set on the symlink itself.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of object.
[in]nameName of xattr to add.
[in]valueValue of xattr.
[in]sizeSize in bytes of the value.
[in]flagsSet 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.
[in]sflags(O_NOFOLLOW)
Returns
0 on success, errno code on failure.

◆ dfs_sys_stat()

int dfs_sys_stat ( dfs_sys_t * dfs_sys,
const char * path,
int flags,
struct stat * stbuf )

stat attributes of an entry. By default, if object is a symlink, the link itself is interrogated. 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;

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of object.
[in]flagsStat flags (O_NOFOLLOW).
[out]stbufStat struct with the members above filled.
Returns
0 on success, errno code on failure.

◆ dfs_sys_symlink()

int dfs_sys_symlink ( dfs_sys_t * dfs_sys,
const char * target,
const char * path )

Create a symlink.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]targetSymlink value.
[in]pathPath to the new symlink.
Returns
0 on success, errno code on failure.

◆ dfs_sys_umount()

int dfs_sys_umount ( dfs_sys_t * dfs_sys)

Unmount a file system with dfs_mount.

Parameters
[in]dfs_sysPointer to the mounted file system.
Returns
0 on success, errno code on failure.

◆ dfs_sys_utimens()

int dfs_sys_utimens ( dfs_sys_t * dfs_sys,
const char * path,
const struct timespec times[2],
int flags )

Set atime and mtime of a path. atime as of 2.2 is ignored.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]pathLink path of object.
[in]times[0]: atime to set [1]: mtime to set
[in]flags(O_NOFOLLOW)
Returns
0 on success, errno code on failure.

◆ dfs_sys_write()

int dfs_sys_write ( dfs_sys_t * dfs_sys,
dfs_obj_t * obj,
const void * buf,
daos_off_t off,
daos_size_t * size,
daos_event_t * ev )

Write data to the file object.

Parameters
[in]dfs_sysPointer to the mounted file system.
[in]objOpened file object.
[in]bufData to write.
[in]offOffset into the file to write to.
[in,out]size[in]: Size of buffer passed in. [out]: Actual size of data written.
[in]evCompletion event, it is optional and can be NULL. Function will run in blocking mode if ev is NULL.
Returns
0 on success, errno code on failure.