LLAPI\_GET\_LUM\_FILE\_FD(3) Lustre Library Functions LLAPI\_GET\_LUM\_FILE\_FD(3)

# [NAME](#NAME)

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.

# [SYNOPSIS](#SYNOPSIS)

```
#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);
```

# [DESCRIPTION](#DESCRIPTION)

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:

[OBD\_MD\_FLSIZE](#OBD_MD_FLSIZE)

The returned file size is known strictly correct.

[OBD\_MD\_FLBLOCKS](#OBD_MD_FLBLOCKS)

The returned file blocks is known strictly correct.

[OBD\_MD\_FLLAZYSIZE](#OBD_MD_FLLAZYSIZE)

The returned file size is approximate, may never have been strictly correct.

[OBD\_MD\_FLLAZYBLOCKS](#OBD_MD_FLLAZYBLOCKS)

The returned file blocks is approximate, may never have been strictly correct.

[OBD\_MD\_FLID](#OBD_MD_FLID)

The returned object ID is valid.

[OBD\_MD\_FLATIME](#OBD_MD_FLATIME)

The returned access time is valid.

[OBD\_MD\_FLMTIME](#OBD_MD_FLMTIME)

The returned data modification time is valid.

[OBD\_MD\_FLCTIME](#OBD_MD_FLCTIME)

The returned change time is valid.

[OBD\_MD\_FLBLKSZ](#OBD_MD_FLBLKSZ)

The returned block size is valid.

[OBD\_MD\_FLMODE](#OBD_MD_FLMODE)

The returned access bits (mode & ~S\_IFMT) is valid.

[OBD\_MD\_FLTYPE](#OBD_MD_FLTYPE)

The returned object type (mode & S\_IFMT) is valid.

[OBD\_MD\_FLUID](#OBD_MD_FLUID)

The returned user ID is valid.

[OBD\_MD\_FLGID](#OBD_MD_FLGID)

The returned group ID is valid.

[OBD\_MD\_FLFLAGS](#OBD_MD_FLFLAGS)

The returned flags word is valid.

[OBD\_MD\_FLNLINK](#OBD_MD_FLNLINK)

The returned link count is valid.

[OBD\_MD\_FLRDEV](#OBD_MD_FLRDEV)

The returned device number is valid.

# [RETURN VALUES](#RETURN_VALUES)

**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.

# [ERRORS](#ERRORS)

[**-ENOMEM**](#ENOMEM)

Insufficient memory to complete operation.

[**-EFAULT**](#EFAULT)

Memory region is not properly mapped.

[**-EINVAL**](#EINVAL)

One or more invalid arguments are given.

[**-EOPNOTSUPP**](#EOPNOTSUPP)

The operation is not supported.

[**-ENOTTY**](#ENOTTY)

File does not reside on a Lustre filesystem.

[**-ENOENT**](#ENOENT)

*path* does not exist.

[**-EBADF**](#EBADF)

*dir\_fd* is not a valid open file descriptor.

# [AVAILABILITY](#AVAILABILITY)

**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)](/man/enterprise-packages/lustre/lustre.7) user application interface library since release 2.13.0

# [SEE ALSO](#SEE_ALSO)

[**lustreapi**(7)](/man/enterprise-packages/lustre/lustreapi.7)

2024-08-27 Lustre User API

---

Document: llapi_get_lum_dir(3) from lustre 2.17.60-r0 (Chainguard OS)
Source: https://github.com/lustre/lustre-release