OS Manuals

llapi_get_lum_dir_fd(3)

llapi_get_lum_file_fd, llapi_get_lum_dir_fd, llapi_get_lum_file, llapi_get_lum_dir - get valid file attributes and LOV stripe information to the user.

LLAPI_GET_LUM_FILE_FD(3) Lustre Library Functions LLAPI_GET_LUM_FILE_FD(3)

llapi_get_lum_file_fd, llapi_get_lum_dir_fd, llapi_get_lum_file, llapi_get_lum_dir - get valid file attributes and LOV stripe information to the user.

#include <lustre/lustreapi.h>
int llapi_get_lum_file_fd(int dir_fd, const char *fname,
                          __u64 *valid, lstatx_t *statx,
                          struct lov_user_md *lum,
                          size_t lumsize);
int llapi_get_lum_dir_fd(int dir_fd, __u64 *valid,
                         lstatx_t *statx, struct lov_user_md *lum,
                         size_t lumsize);
int llapi_get_lum_file(const char *path, __u64 *valid,
                       lstatx_t *statx, struct lov_user_md *lum,
                       size_t lumsize);
int llapi_get_lum_dir(const char *path, __u64 *valid,
                      lstatx_t *statx, struct lov_user_md *lum,
                      size_t lumsize);

The function llapi_get_lum_file_fd(), llapi_get_lum_dir_fd(), llapi_get_lum_file(), and llapi_get_lum_dir() returns file attributes and LOV stripe information by an ioctl on the dir. dir_fd is a file descriptor that refers to a directory. For function llapi_get_lum_file_fd(), if fname is provided, it is a relative pathname that is interpreted relative to the directory referred to by dir_fd.

The function llapi_get_lum_dir_fd(), llapi_get_lum_file(), and llapi_get_lum_dir() can be used for applications that are only processing a single file or directory referred to by dir_fd or path.

The function llapi_get_lum_file_fd() can be used for applications that process lots of files. It avoids opening, locking, and closing each file on the client if that is not needed. Multiple calls of this llapi can be done on the parent dir referenced by dir_fd with a single open for all files in that directory, and it also does not pollute the client dcache with millions of dentries when traversing a large filesystem.

The stripe information for the target file is returned to the user in the struct lov_user_md pointed to by lum if it is not a NULL pointer. The file attribute information for the target file is returned in the lstatx_t structure pointed to by statx if it is not a NULL pointer. The output argument valid contains the flags to indicate which fields in the returned file attributes have been validly filled in.

The valid flags are as follows:

The returned file size is known strictly correct.
The returned file blocks is known strictly correct.
The returned file size is approximate, may never have been strictly correct.
The returned file blocks is approximate, may never have been strictly correct.
The returned object ID is valid.
The returned access time is valid.
The returned data modification time is valid.
The returned change time is valid.
The returned block size is valid.
The returned access bits (mode & ~S_IFMT) is valid.
The returned object type (mode & S_IFMT) is valid.
The returned user ID is valid.
The returned group ID is valid.
The returned flags word is valid.
The returned link count is valid.
The returned device number is valid.

llapi_get_lum_file_fd(), llapi_get_lum_dir_fd(), llapi_get_lum_file(), and llapi_get_lum_dir() return 0 on success or a negative errno value on failure.

Insufficient memory to complete operation.
Memory region is not properly mapped.
One or more invalid arguments are given.
The operation is not supported.
File does not reside on a Lustre filesystem.
path does not exist.
dir_fd is not a valid open file descriptor.

llapi_get_lum_file_fd(), llapi_get_lum_file(), llapi_get_lum_dir_fd() and llapi_get_lum_dir() are part of the lustre(7) user application interface library since release 2.13.0

lustreapi(7)

2024-08-27 Lustre User API

lustre 2.17.59-r1 · enterprise-packages · ingested 2026-10-02